diff options
Diffstat (limited to 'doc')
544 files changed, 10919 insertions, 6350 deletions
diff --git a/doc/.vale/gitlab/ReadingLevel.yml b/doc/.vale/gitlab/ReadingLevel.yml index 2e78c3ef36c..cd7597ee8dc 100644 --- a/doc/.vale/gitlab/ReadingLevel.yml +++ b/doc/.vale/gitlab/ReadingLevel.yml @@ -3,11 +3,11 @@ # # Checks the Flesch-Kincaid reading level. # -# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles -extends: readability -message: "Grade level (%s) is high. To lower the score, use shorter sentences and words." +# https://docs.errata.ai/vale/styles#metric +extends: metric +message: "The grade level - %s - refers to how hard the content is to understand. Aim for 8th grade or lower by using shorter sentences and words." link: https://docs.gitlab.com/ee/development/documentation/testing.html#vale-readability-score level: suggestion -grade: 8 -metrics: - - Flesch-Kincaid +formula: | + (0.39 * (words / sentences)) + (11.8 * (syllables / words)) - 15.59 +condition: "> 1" diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml index fefc0f85cf4..8000328a20c 100644 --- a/doc/.vale/gitlab/SubstitutionWarning.yml +++ b/doc/.vale/gitlab/SubstitutionWarning.yml @@ -11,6 +11,7 @@ link: https://about.gitlab.com/handbook/communication/#top-misused-terms level: warning ignorecase: true swap: + click: select code base: codebase config: configuration distro: distribution diff --git a/doc/.vale/gitlab/Uppercase.yml b/doc/.vale/gitlab/Uppercase.yml index ae011748748..c9021dc862e 100644 --- a/doc/.vale/gitlab/Uppercase.yml +++ b/doc/.vale/gitlab/Uppercase.yml @@ -53,6 +53,7 @@ exceptions: - EOL - EXIF - FAQ + - FIDO - FIFO - FIPS - FLAG @@ -179,6 +180,7 @@ exceptions: - TLS - TODO - TOML + - TOTP - TTL - UID - UDP diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 5ed8dc92249..98254c2259b 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -9,6 +9,7 @@ allowlist allowlisted allowlisting allowlists +AlmaLinux anonymization anonymized Ansible @@ -220,6 +221,7 @@ Fluentd Flycheck Forgerock formatters +Fortinet Fugit fuzzer Gantt @@ -364,7 +366,7 @@ Microsoft middleware middlewares migratus -Minikube +minikube MinIO misconfiguration misconfigurations diff --git a/doc/.vale/vale.tmpl b/doc/.vale/vale.tmpl index 36dfbd6b778..8a6c6e5157d 100644 --- a/doc/.vale/vale.tmpl +++ b/doc/.vale/vale.tmpl @@ -48,4 +48,4 @@ {{end -}} {{end -}} -{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}}, and {{$s}} {{"suggestions" | blue}} found in {{$f}} {{$f | int | plural "file" "files"}}. +{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}}, and {{$s}} {{"suggestions" | blue}} found. diff --git a/doc/administration/audit_event_streaming.md b/doc/administration/audit_event_streaming.md index cee6cddbbf0..eac54416924 100644 --- a/doc/administration/audit_event_streaming.md +++ b/doc/administration/audit_event_streaming.md @@ -6,11 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Audit event streaming **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332747) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `ff_external_audit_events_namespace`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332747) in GitLab 14.5 [with a flag](../administration/feature_flags.md) named `ff_external_audit_events_namespace`. Disabled by default. +> - [Enabled on GitLab.com and by default on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338939) in GitLab 14.7. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `ff_external_audit_events_namespace`. On GitLab.com, this feature is not available. -You should not use this feature for production environments. +On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `ff_external_audit_events_namespace`. On GitLab.com, this feature is available. Event streaming allows owners of top-level groups to set an HTTP endpoint to receive **all** audit events about the group, and its subgroups and projects. diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 5fa10c4c119..08d07b13e22 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md index 4220e552196..23735b75991 100644 --- a/doc/administration/auth/authentiq.md +++ b/doc/administration/auth/authentiq.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md index 718a2919ed0..2509bbb73d7 100644 --- a/doc/administration/auth/cognito.md +++ b/doc/administration/auth/cognito.md @@ -1,7 +1,7 @@ --- type: concepts, howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 265bba8a9b1..9a5f6b0a642 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/index.md b/doc/administration/auth/index.md index 959c5218554..d469988e719 100644 --- a/doc/administration/auth/index.md +++ b/doc/administration/auth/index.md @@ -2,7 +2,7 @@ comments: false type: index stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 9298b04cbc1..ac2f699dd5d 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 69f0bfdce4c..6b8e699e861 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index f551c362784..b773281b216 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -21,7 +21,7 @@ This integration works with most LDAP-compliant directory servers, including: Users added through LDAP: -- Take a [licensed seat](../../../subscriptions/self_managed/index.md#billable-users). +- Usually use a [licensed seat](../../../subscriptions/self_managed/index.md#billable-users). - Can authenticate with Git using either their GitLab username or their email and LDAP password, even if password authentication for Git [is disabled](../../../user/admin_area/settings/sign_in_restrictions.md#password-authentication-enabled). @@ -153,13 +153,22 @@ production: ### Basic configuration settings +> `hosts` configuration setting [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/139) in GitLab 14.7. + +You can configure either: + +- A single LDAP server using `host` and `port`. +- Many LDAP servers using `hosts`. This setting takes precedence over `host` and `port`. GitLab attempts to use the + LDAP servers in the order specified, and the first reachable LDAP server is used. + These configuration settings are available: | Setting | Description | Required | Examples | |--------------------|-------------|----------|----------| | `label` | A human-friendly name for your LDAP server. It is displayed on your sign-in page. | **{check-circle}** Yes | `'Paris'` or `'Acme, Ltd.'` | -| `host` | IP address or domain name of your LDAP server. | **{check-circle}** Yes | `'ldap.mydomain.com'` | -| `port` | The port to connect with on your LDAP server. Always an integer, not a string. | **{check-circle}** Yes | `389` or `636` (for SSL) | +| `host` | IP address or domain name of your LDAP server. Ignored when `hosts` is defined. | **{check-circle}** Yes | `'ldap.mydomain.com'` | +| `port` | The port to connect with on your LDAP server. Always an integer, not a string. Ignored when `hosts` is defined. | **{check-circle}** Yes | `389` or `636` (for SSL) | +| `hosts` (GitLab 14.7 and later) | An array of host and port pairs to open connections. | **{dotted-circle}** No | `[['ldap1.mydomain.com', 636], ['ldap2.mydomain.com', 636]]` | | `uid` | LDAP attribute for username. Should be the attribute, not the value that maps to the `uid`. | **{check-circle}** Yes | `'sAMAccountName'` or `'uid'` or `'userPrincipalName'` | | `bind_dn` | The full DN of the user you bind with. | **{dotted-circle}** No | `'america\momo'` or `'CN=Gitlab,OU=Users,DC=domain,DC=com'` | | `password` | The password of the bind user. | **{dotted-circle}** No | `'your_great_password'` | diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 63e4490e332..97a626f4a40 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index 8ccd8fecbcf..3329ea8e9cc 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index 7ab1f2f5feb..efe4b7440ee 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index d79837776b2..f77d3a36a7b 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index b5c0a6ee76a..ba0d7280b74 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -6,13 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Install the GitLab Agent Server (KAS) **(FREE SELF)** +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. > [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. The GitLab Agent Server (KAS) is a GitLab backend service dedicated to managing the [GitLab Agent](../../user/clusters/agent/index.md). The KAS is already installed and available in GitLab.com under `wss://kas.gitlab.com`. -See [how to use GitLab.com's KAS](../../user/clusters/agent/install/index.md#set-up-the-agent-server). This document describes how to install a KAS for GitLab self-managed instances. ## Installation options diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 7cecc0c30fd..843d5d0930a 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -6,37 +6,49 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Compliance features **(FREE)** -These GitLab features can help ensure that your GitLab instance meets common compliance standards. For more information -about compliance management, see the compliance management [solutions page](https://about.gitlab.com/solutions/compliance/). +These GitLab features can help ensure that your GitLab instance meets common +compliance standards. For more information about compliance management, see the +compliance management [solutions page](https://about.gitlab.com/solutions/compliance/). -The [security features](../security/index.md) in GitLab may also help you meet relevant compliance standards. +The [security features](../security/index.md) in GitLab may also help you meet +relevant compliance standards. ## Policy management -Organizations have unique policy requirements, either due to organizational standards or mandates from regulatory bodies. -The following features help you define rules and policies to adhere to workflow requirements, separation of duties, and -secure supply chain best practices: +Organizations have unique policy requirements, either due to organizational +standards or mandates from regulatory bodies. The following features help you +define rules and policies to adhere to workflow requirements, separation of duties, +and secure supply chain best practices: -- [**Credentials inventory**](../user/admin_area/credentials_inventory.md) (for instances): With a credentials inventory, - GitLab administrators can keep track of the credentials used by all of the users in their GitLab instance. -- [**Granular user roles and flexible permissions**](../user/permissions.md) (for instances, groups, and projects): 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. -- [**Merge request approvals**](../user/project/merge_requests/approvals/index.md) (for instances, groups, and projects): - Configure approvals required for merge requests. -- [**Push rules**](../push_rules/push_rules.md) (for instances, groups, and projects): Control pushes to your - repositories. +- [**Credentials inventory**](../user/admin_area/credentials_inventory.md) (for + instances): With a credentials inventory, GitLab administrators can keep track + of the credentials used by all of the users in their GitLab instance. +- [**Granular user roles and flexible permissions**](../user/permissions.md) + (for instances, groups, and projects): 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. +- [**Merge request approvals**](../user/project/merge_requests/approvals/index.md) + (for instances, groups, and projects): Configure approvals required for + merge requests. +- [**Push rules**](../push_rules/push_rules.md) (for instances, groups, and + projects): Control pushes to your repositories. - Separation of duties using [**protected branches**](../user/project/protected_branches.md#require-code-owner-approval-on-a-protected-branch) - and [**custom CI/CD configuration paths**](../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file) (for projects): - Users can leverage the GitLab cross-project YAML configurations to define deployers of code and developers of code. - See how to use this setup to define these roles in: + and [**custom CI/CD configuration paths**](../ci/pipelines/settings.md#specify-a-custom-cicd-configuration-file) (for projects): Users can leverage the GitLab cross-project YAML configurations + to define deployers of code and developers of code. See how to use this setup + to define these roles in: - The [Separation of Duties deploy project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md). - The [Separation of Duties project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md). ## Compliant workflow automation -It is important for compliance teams to be confident that their controls and requirements are set up correctly, but also that they _stay_ set up correctly. One way of doing this is manually checking settings periodically, but this is error prone and time consuming. A better approach is to use single-source-of-truth settings and automation to ensure that whatever a compliance team has configured, stays configured and working correctly. These features can help you automate compliance: +It is important for compliance teams to be confident that their controls and +requirements are set up correctly, but also that they _stay_ set up correctly. +One way of doing this is manually checking settings periodically, but this is +error prone and time consuming. A better approach is to use single-source-of-truth +settings and automation to ensure that whatever a compliance team has configured, +stays configured and working correctly. These features can help you automate +compliance: - [**Compliance frameworks**](../user/project/settings/index.md#compliance-frameworks) (for groups): Create a custom compliance framework at the group level to describe the type of compliance requirements any child project needs to follow. @@ -45,42 +57,59 @@ It is important for compliance teams to be confident that their controls and req ## Audit management -An important part of any compliance program is being able to go back and understand what happened, when -it happened, and who was responsible. This is useful in audit situations as well as for understanding -the root cause of issues when they occur. It is useful to have both low-level, raw lists of audit data -as well as high-level, summary lists of audit data. Between these two, compliance teams can quickly -identify if problems exist and then drill down into the specifics of those issues. These features can help provide visibility into GitLab and audit what is happening: +An important part of any compliance program is being able to go back and understand +what happened, when it happened, and who was responsible. This is useful in audit +situations as well as for understanding the root cause of issues when they occur. +It is useful to have both low-level, raw lists of audit data as well as high-level, +summary lists of audit data. Between these two, compliance teams can quickly +identify if problems exist and then drill down into the specifics of those issues. +These features can help provide visibility into GitLab and audit what is happening: -- [**Audit events**](audit_events.md) (for instances, groups, and projects): To maintain the integrity of your code, - audit events give administrators 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. -- [**Auditor users**](auditor_users.md) (for instances): Auditor users are users who are given read-only access to all - projects, groups, and other resources on the GitLab instance. -- [**Compliance report**](../user/compliance/compliance_report/index.md) (for groups): Quickly get visibility into the - compliance posture of your organization. +- [**Audit events**](audit_events.md) (for instances, groups, and projects): To + maintain the integrity of your code, audit events give administrators 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. +- [**Audit reports**](audit_reports.md) (for instances, groups, and projects): + Create and access reports based on the audit events that have occurred. Use + pre-built GitLab reports or the API to build your own. +- [**Auditor users**](auditor_users.md) (for instances): Auditor users are users + who are given read-only access to all projects, groups, and other resources on + the GitLab instance. +- [**Compliance report**](../user/compliance/compliance_report/index.md) (for + groups): Quickly get visibility into the compliance posture of your organization. ## Other compliance features These features can also help with compliance requirements: -- [**Email all users of a project, group, or entire server**](../tools/email.md) (for instances): An administrator can - email groups of users based on project or group membership, or email everyone using the GitLab instance. These emails +- [**Email all users of a project, group, or entire server**](../tools/email.md) + (for instances): An administrator can email groups of users based on project + or group membership, or email everyone using the GitLab instance. These emails are great for scheduled maintenance or upgrades. -- [**Enforce ToS acceptance**](../user/admin_area/settings/terms.md) (for instances): Enforce your users accepting new - terms of service by blocking GitLab traffic. -- [**External Status Checks**](../user/project/merge_requests/status_checks.md) (for projects): Interface with third-party - systems you already use during development to ensure you remain compliant. -- [**Generate reports on permission levels of users**](../user/admin_area/index.md#user-permission-export) (for - instances): Administrators can generate a report listing all users' access permissions for groups and projects in the - instance. -- [**Lock project membership to group**](../user/group/index.md#prevent-members-from-being-added-to-projects-in-a-group) (for - groups): Group owners can prevent new members from being added to projects within a group. -- [**LDAP group sync**](auth/ldap/ldap_synchronization.md#group-sync) (for instances): Gives administrators 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. -- [**LDAP group sync filters**](auth/ldap/ldap_synchronization.md#group-sync) (for instances): Gives more flexibility to - synchronize with LDAP based on filters, meaning you can leverage LDAP attributes to map GitLab permissions. +- [**Enforce ToS acceptance**](../user/admin_area/settings/terms.md) (for + instances): Enforce your users accepting new terms of service by blocking GitLab + traffic. +- [**External Status Checks**](../user/project/merge_requests/status_checks.md) + (for projects): Interface with third-party systems you already use during + development to ensure you remain compliant. +- [**Generate reports on permission levels of users**](../user/admin_area/index.md#user-permission-export) + (for instances): Administrators can generate a report listing all users' access + permissions for groups and projects in the instance. +- [**License compliance**](../user/compliance/license_compliance/index.md) (for + projects): Search dependencies for their licenses. This lets you determine if + the licenses of your project's dependencies are compatible with your project's + license. +- [**Lock project membership to group**](../user/group/index.md#prevent-members-from-being-added-to-projects-in-a-group) + (for groups): Group owners can prevent new members from being added to projects + within a group. +- [**LDAP group sync**](auth/ldap/ldap_synchronization.md#group-sync) (for + instances): Gives administrators 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. +- [**LDAP group sync filters**](auth/ldap/ldap_synchronization.md#group-sync) + (for instances): Gives more flexibility to synchronize with LDAP based on + filters, meaning you can leverage LDAP attributes to map GitLab permissions. - [**Omnibus GitLab package supports log forwarding**](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-forwarding) (for instances): Forward your logs to a central system. -- [**Restrict SSH Keys**](../security/ssh_keys_restrictions.md) (for instances): Control the technology and key length - of SSH keys used to access GitLab. +- [**Restrict SSH Keys**](../security/ssh_keys_restrictions.md) (for instances): + Control the technology and key length of SSH keys used to access GitLab. diff --git a/doc/administration/configure.md b/doc/administration/configure.md index 822acc1a74e..e42eb632f14 100644 --- a/doc/administration/configure.md +++ b/doc/administration/configure.md @@ -15,7 +15,7 @@ Customize and configure your self-managed GitLab installation. Here are some qui - [Geo](geo/index.md) - [Packages](packages/index.md) -The following tables are intended to guide you to choose the right combination of capabilties based on your requirements. It is common to want the most +The following tables are intended to guide you to choose the right combination of capabilities based on your requirements. It is common to want the most available, quickly recoverable, highly performant and fully data resilient solution. However, there are tradeoffs. The tables lists features on the left and provides their capabilities to the right along with known trade-offs. diff --git a/doc/administration/docs_self_host.md b/doc/administration/docs_self_host.md new file mode 100644 index 00000000000..007055b5de7 --- /dev/null +++ b/doc/administration/docs_self_host.md @@ -0,0 +1,131 @@ +--- +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 self-host the docs site **(FREE SELF)** + +If you have a self-managed instance of GitLab, you may not be able to access the +product documentation as hosted on `docs.gitlab.com` from your GitLab instance. + +Be aware of the following items if you self-host the product documentation: + +- You must host the product documentation site under a subdirectory that matches + your installed GitLab version (for example, `14.5/`). The + [Docker images](https://gitlab.com/gitlab-org/gitlab-docs/container_registry/631635) + hosted by the GitLab Docs team provide this by default. We use a + [script](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/2995d1378175803b22fb8806ba77adf63e79f32c/scripts/normalize-links.sh#L28-82) + to normalize the links and prefix them with the respective version. +- The version dropdown will display additional versions that don't exist, selecting + those versions will display a 404 Not Found page. +- Results when using the search box will display results from `docs.gitlab.com` + and not the local documentation. +- When you use the Docker images to serve the product documentation site, by + default the landing page redirects to the respective version (for example, `/14.5/`), + which causes the landing page <https://docs.gitlab.com> to not be displayed. + +## Documentation self-hosting options + +You can self-host the GitLab product documentation locally using one of these +methods: + +- Docker +- GitLab Pages +- From your own webserver + +The examples on this page are based on GitLab 14.5. + +### Self-host the product documentation with Docker + +The Docker images use a built-in webserver listening on port `4000`, so you need +to expose that. + +In the server that you host GitLab, or any other server that your GitLab instance +can talk to, you can use Docker to pull the docs site: + +```shell +docker run -it --rm -p 4000:4000 registry.gitlab.com/gitlab-org/gitlab-docs:14.5 +``` + +If you use [Docker compose](../install/docker.md#install-gitlab-using-docker-compose) +to host your GitLab instance, add the following to `docker-compose.yaml`: + +```yaml +version: '3.6' +services: + docs: + image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5 + hostname: 'https://gitlab.example.com' + ports: + - '4000:4000' +``` + +### Self-host the product documentation with GitLab Pages + +You use GitLab Pages to host the GitLab product documentation locally. + +Prerequisite: + +- The Pages site URL must not use a subfolder. Due to the nature of how the docs + site is pre-compiled, the CSS and JavaScript files are relative to the + main domain or subdomain. For example, URLs like `https://example.com/docs/` + are not supported. + +To host the product documentation site with GitLab Pages: + +1. [Create a new blank project](../user/project/working_with_projects.md#create-a-blank-project). +1. Create a new or edit your existing `.gitlab-ci.yml` file, and add the following + `pages` job, while ensuring the version is the same as your GitLab installation: + + ```yaml + image: registry.gitlab.com/gitlab-org/gitlab-docs:14.5 + pages: + script: + - mkdir public + - cp -a /usr/share/nginx/html/* public/ + artifacts: + paths: + - public + ``` + +1. Optional. Set the GitLab Pages domain name. Depending on the type of the + GitLab Pages website, you have two options: + + | Type of website | [Default domain](../user/project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names) | [Custom domain](../user/project/pages/custom_domains_ssl_tls_certification/index.md) | + |-------------------------|----------------|---------------| + | [Project website](../user/project/pages/getting_started_part_one.md#project-website-examples) | Not supported | Supported | + | [User or group website](../user/project/pages/getting_started_part_one.md#user-and-group-website-examples) | Supported | Supported | + +### Self-host the product documentation on your own webserver + +Because the product documentation site is static, you can grab the directory from +the container (in `/usr/share/nginx/html`) and use your own web server to host +it wherever you want. + +Use the following commands, and replace `<destination>` with the directory where the +documentation files will be copied to: + +```shell +docker create -it --name gitlab-docs registry.gitlab.com/gitlab-org/gitlab-docs:14.5 +docker cp gitlab-docs:/usr/share/nginx/html <destination> +docker rm -f gitlab-docs +``` + +## Redirect the `/help` links to the new docs page + +After your local product documentation site is running, [redirect the help +links](../user/admin_area/settings/help_page.md#redirect-help-pages) in the GitLab +application to your local site. + +Be sure to use the fully qualified domain name as the docs URL. For example, if you +used the [Docker method](#self-host-the-product-documentation-with-docker), enter `http://0.0.0.0:4000`. + +You don't need to append the version, as GitLab will detect it and append it to +any documentation URL requests, as needed. For example, if your GitLab version is +14.5, the GitLab Docs URL becomes `http://0.0.0.0:4000/14.5/`. The link +inside GitLab displays as `<instance_url>/help/user/admin_area/settings/help_page#destination-requirements`, +but when you select it, you are redirected to +`http://0.0.0.0:4000/14.5/ee/user/admin_area/settings/help_page/#destination-requirements`. + +To test the setting, select a **Learn more** link within the GitLab application. diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index caa806c92c8..d7db48bb6cf 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -2,7 +2,6 @@ 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 --- # Automatic background verification **(PREMIUM SELF)** @@ -89,8 +88,6 @@ in sync. ## Repository re-verification -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8550) in GitLab 11.6. - Due to bugs or transient infrastructure failures, it is possible for Git repositories to change unexpectedly without being marked for verification. Geo constantly reverifies the repositories to ensure the integrity of the diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index bf28eb76ffd..f7367ef863b 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -2,7 +2,6 @@ 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 --- # Disaster Recovery (Geo) **(PREMIUM SELF)** @@ -503,7 +502,7 @@ secondary domain, like changing Git remotes and API URLs. This command uses the changed `external_url` configuration defined in `/etc/gitlab/gitlab.rb`. -1. For GitLab 11.11 through 12.7 only, you may need to update the **primary** +1. For GitLab 12.0 through 12.7, you may need to update the **primary** node's name in the database. This bug has been fixed in GitLab 12.8. To determine if you need to do this, search for the @@ -672,7 +671,7 @@ Data that was created on the primary while the secondary was paused is lost. If you are running GitLab 14.5 and later: -1. SSH to every Sidekiq, PostgresSQL, and Gitaly node in the **secondary** site and run one of the following commands: +1. For each node outside of the **secondary** Kubernetes cluster using Omnibus such as PostgreSQL or Gitaly, SSH into the node and run one of the following commands: - To promote the secondary node to primary: @@ -686,19 +685,17 @@ If you are running GitLab 14.5 and later: sudo gitlab-ctl geo promote --force ``` -1. SSH into each Rails node on your **secondary** site and run one of the following commands: +1. Find the `toolbox` pod: - - To promote the secondary node to primary: - - ```shell - sudo gitlab-ctl geo promote - ``` + ```shell + kubectl --namespace gitlab get pods -lapp=toolbox + ``` - - To promote the secondary node to primary **without any further confirmation**: +1. Promote the secondary: - ```shell - sudo gitlab-ctl geo promote --force - ``` + ```shell + kubectl --namespace gitlab exec -ti gitlab-geo-toolbox-XXX -- gitlab-rake geo:set_secondary_as_primary + ``` If you are running GitLab 14.4 and earlier: @@ -709,8 +706,6 @@ If you are running GitLab 14.4 and earlier: sudo gitlab-ctl promote-db ``` - In GitLab 12.8 and earlier, see [Message: `sudo: gitlab-pg-ctl: command not found`](../replication/troubleshooting.md#message-sudo-gitlab-pg-ctl-command-not-found). - 1. Edit `/etc/gitlab/gitlab.rb` on the database node in the **secondary** site to reflect its new status as **primary** by removing any lines that enabled the `geo_secondary_role`: diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 2cb1a424ce8..b5eb0ba5841 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -25,7 +25,8 @@ For a video introduction to Geo, see [Introduction to GitLab Geo - GitLab Featur To make sure you're using the right version of the documentation, navigate to [the Geo page on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/administration/geo/index.md) and choose the appropriate release from the **Switch branch/tag** dropdown. For example, [`v13.7.6-ee`](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.7.6-ee/doc/administration/geo/index.md). -Geo uses a set of defined terms that is described in the [Geo Glossary](glossary.md), please familiarize yourself with those terms. +Geo uses a set of defined terms that are described in the [Geo Glossary](glossary.md). +Be sure to familiarize yourself with those terms. ## Use cases @@ -119,7 +120,8 @@ The following are required to run Geo: The following operating systems are known to ship with a current version of OpenSSH: - [CentOS](https://www.centos.org) 7.4 or later - [Ubuntu](https://ubuntu.com) 16.04 or later -- PostgreSQL 12 or later with [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication) +- PostgreSQL 12 with [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication) + - PostgreSQL 13 is not supported for Geo, see [epic 3832](https://gitlab.com/groups/gitlab-org/-/epics/3832) - Git 2.9 or later - Git-lfs 2.4.2 or later on the user side when using LFS - All sites must run the same GitLab version. diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 3cbde77903d..16b4848e6d3 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -199,20 +199,21 @@ keys must be manually replicated to the **secondary** site. gitlab-ctl reconfigure ``` -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Geo > Sites**. -1. Select **New site**. +1. Navigate to the Primary Node GitLab Instance: + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Geo > Sites**. + 1. Select **Add site**.  -1. Fill in **Name** with the `gitlab_rails['geo_node_name']` in + 1. Fill in **Name** with the `gitlab_rails['geo_node_name']` in `/etc/gitlab/gitlab.rb`. These values must always match *exactly*, character for character. -1. Fill in **URL** with the `external_url` in `/etc/gitlab/gitlab.rb`. These + 1. Fill in **URL** with the `external_url` in `/etc/gitlab/gitlab.rb`. These values must always match, but it doesn't matter if one ends with a `/` and the other doesn't. -1. Optionally, choose which groups or storage shards should be replicated by the + 1. (Optional) Choose which groups or storage shards should be replicated by the **secondary** site. Leave blank to replicate all. Read more in [selective synchronization](#selective-synchronization). -1. Select **Add site** to add the **secondary** site. + 1. Select **Save changes** to add the **secondary** site. 1. SSH into **each Rails, and Sidekiq node on your secondary** site and restart the services: ```shell diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 31bc473d74b..0fa08dcc9e0 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -188,8 +188,8 @@ successfully, you must replicate their data using some other means. |[Project repository](../../../user/project/repository/) | **Yes** (10.2) | **Yes** (10.7) | No | | |[Project wiki repository](../../../user/project/wiki/) | **Yes** (10.2) | **Yes** (10.7) | No | | |[Group wiki repository](../../../user/project/wiki/group.md) | [**Yes** (13.10)](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | No | No | Behind feature flag `geo_group_wiki_repository_replication`, enabled by default. | -|[Uploads](../../uploads.md) | **Yes** (10.2) | **Yes** (14.6) | Via Object Storage provider if supported. Native Geo support (Beta). | Replication is behind the feature flag `geo_upload_replication`, enabled by default. Verification is behind the feature flag `geo_upload_verification` introduced and enabled by default in 14.6. | -|[LFS objects](../../lfs/index.md) | **Yes** (10.2) | **Yes** (14.6) | Via Object Storage provider if supported. Native Geo support (Beta). | GitLab versions 11.11.x and 12.0.x are affected by [a bug that prevents any new LFS objects from replicating](https://gitlab.com/gitlab-org/gitlab/-/issues/32696).<br /><br />Replication is behind the feature flag `geo_lfs_object_replication`, enabled by default. Verification is behind the feature flag `geo_lfs_object_verification` introduced and enabled by default in 14.6. | +|[Uploads](../../uploads.md) | **Yes** (10.2) | **Yes** (14.6) | Via Object Storage provider if supported. Native Geo support (Beta). | Replication is behind the feature flag `geo_upload_replication`, enabled by default. Verification was behind the feature flag `geo_upload_verification`, removed in 14.8. | +|[LFS objects](../../lfs/index.md) | **Yes** (10.2) | **Yes** (14.6) | Via Object Storage provider if supported. Native Geo support (Beta). | GitLab versions 11.11.x and 12.0.x are affected by [a bug that prevents any new LFS objects from replicating](https://gitlab.com/gitlab-org/gitlab/-/issues/32696).<br /><br />Replication is behind the feature flag `geo_lfs_object_replication`, enabled by default. Verification was behind the feature flag `geo_lfs_object_verification`, removed in 14.7. | |[Personal snippets](../../../user/snippets.md) | **Yes** (10.2) | **Yes** (10.2) | No | | |[Project snippets](../../../user/snippets.md) | **Yes** (10.2) | **Yes** (10.2) | No | | |[CI job artifacts](../../../ci/pipelines/job_artifacts.md) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Via Object Storage provider if supported. Native Geo support (Beta). | Verified only manually using [Integrity Check Rake Task](../../raketasks/check.md) on both sites and comparing the output between them. Job logs also verified on transfer. | @@ -200,9 +200,9 @@ successfully, you must replicate their data using some other means. |[Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | No | Designs also require replication of LFS objects and Uploads. | |[Package Registry](../../../user/packages/package_registry/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | 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) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.12) | Via Object Storage provider if supported. Native Geo support (Beta). | Replication is behind the feature flag `geo_terraform_state_version_replication`, enabled by default. Verification was behind the feature flag `geo_terraform_state_version_verification`, which was removed in 14.0. | -|[External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | **Yes** (14.6) | Via Object Storage provider if supported. Native Geo support (Beta). | Replication is behind the feature flag `geo_merge_request_diff_replication`, enabled by default. Verification is behind the feature flag `geo_merge_request_diff_verification`, enabled by default in 14.6.| +|[External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | **Yes** (14.6) | Via Object Storage provider if supported. Native Geo support (Beta). | Replication is behind the feature flag `geo_merge_request_diff_replication`, enabled by default. Verification was behind the feature flag `geo_merge_request_diff_verification`, removed in 14.7.| |[Versioned snippets](../../../user/snippets.md#versioned-snippets) | [**Yes** (13.7)](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [**Yes** (14.2)](https://gitlab.com/groups/gitlab-org/-/epics/2810) | No | Verification was implemented behind the feature flag `geo_snippet_repository_verification` in 13.11, and the feature flag was removed in 14.2. | -|[GitLab Pages](../../pages/index.md) | [**Yes** (14.3)](https://gitlab.com/groups/gitlab-org/-/epics/589) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (14.6) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_pages_deployment_replication`, enabled by default. Verification is behind the feature flag `geo_pages_deployment_verification`, enabled by default in 14.6. | +|[GitLab Pages](../../pages/index.md) | [**Yes** (14.3)](https://gitlab.com/groups/gitlab-org/-/epics/589) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (14.6) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_pages_deployment_replication`, enabled by default. Verification was behind the feature flag `geo_pages_deployment_verification`, removed in 14.7. | |[Server-side Git hooks](../../server_hooks.md) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/1867) | No | No | Not planned because of current implementation complexity, low customer interest, and availability of alternatives to hooks. | |[Elasticsearch integration](../../../integration/elasticsearch.md) | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | No | Not planned because further product discovery is required and Elasticsearch (ES) clusters can be rebuilt. Secondaries use the same ES cluster as the primary. | |[Dependency proxy images](../../../user/packages/dependency_proxy/index.md) | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/259694) | No | No | Blocked by [Geo: Secondary Mimicry](https://gitlab.com/groups/gitlab-org/-/epics/1528). Replication of this cache is not needed for disaster recovery purposes because it can be recreated from external sources. | diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index e613a9b5670..12b3b382bf7 100644 --- a/doc/administration/geo/replication/faq.md +++ b/doc/administration/geo/replication/faq.md @@ -2,7 +2,6 @@ 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 Frequently Asked Questions **(PREMIUM SELF)** @@ -54,7 +53,7 @@ For more details, see the [supported Geo data types](datatypes.md). ## Can I `git push` to a **secondary** site? -Yes! Pushing directly to a **secondary** site (for both HTTP and SSH, including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in GitLab 11.3. +Pushing directly to a **secondary** site (for both HTTP and SSH, including Git LFS) is supported. ## How long does it take to have a commit replicated to a **secondary** site? diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md index a4c2f156216..ce1bd8a9d3c 100644 --- a/doc/administration/geo/replication/geo_validation_tests.md +++ b/doc/administration/geo/replication/geo_validation_tests.md @@ -2,7 +2,6 @@ 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 validation tests **(PREMIUM SELF)** @@ -175,7 +174,7 @@ The following are PostgreSQL upgrade validation tests we performed. [Test and validate PostgreSQL 10.0 upgrade for Geo](https://gitlab.com/gitlab-org/gitlab/-/issues/12092): - Description: With the 12.0 release, GitLab required an upgrade to PostgreSQL 10.0. We tested - various upgrade scenarios from GitLab 11.11.5 through to GitLab 12.1.8. + various upgrade scenarios up to GitLab 12.1.8. - Outcome: Multiple issues were found when upgrading and addressed in follow-up issues. - Follow up issues: - [`gitlab-ctl` reconfigure fails on Redis node in multi-node Geo setup](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4706). diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index 673d8388af1..a6ea41171a9 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -2,19 +2,18 @@ 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 --- # Troubleshooting Geo **(PREMIUM SELF)** -Setting up Geo requires careful attention to details and sometimes it's easy to +Setting up Geo requires careful attention to details, and sometimes it's easy to miss a step. Here is a list of steps you should take to attempt to fix problem: -- Perform [basic troubleshooting](#basic-troubleshooting). -- Fix any [replication errors](#fixing-replication-errors). -- Fix any [common](#fixing-common-errors) errors. +1. Perform [basic troubleshooting](#basic-troubleshooting). +1. Fix any [replication errors](#fixing-replication-errors). +1. Fix any [common](#fixing-common-errors) errors. ## Basic troubleshooting @@ -41,11 +40,11 @@ to help identify if something is wrong:  -For information on how to resolve common errors reported from the UI, see -[Fixing Common Errors](#fixing-common-errors). +For information about how to resolve common error messages reported from the user interface, +see [Fixing Common Errors](#fixing-common-errors). -If the UI is not working, or you are unable to log in, you can run the Geo -health check manually to get this information as well as a few more details. +If the user interface is not working, or you are unable to sign in, you can run the Geo +health check manually to get this information and a few more details. #### Health check Rake task @@ -173,124 +172,129 @@ HINT: Close open transactions soon to avoid wraparound problems. You might also need to commit or roll back old prepared transactions, or drop stale replication slots. ``` -To fix this, do the following: +To fix this: 1. [Connect to the primary database](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database). + 1. Run `SELECT * FROM pg_replication_slots;`. -1. Note the `slot_name` that reports `active` as `f` (false). -1. Follow [all these steps to remove that Geo site](remove_geo_site.md). + Note the `slot_name` that reports `active` as `f` (false). + +1. Follow [the steps to remove that Geo site](remove_geo_site.md). ## Fixing errors found when running the Geo check Rake task -When running this Rake task, you may see errors if the nodes are not properly configured: +When running this Rake task, you may see error messages if the nodes are not properly configured: ```shell sudo gitlab-rake gitlab:geo:check ``` -1. Rails did not provide a password when connecting to the database +- Rails did not provide a password when connecting to the database. - ```plaintext - Checking Geo ... + ```plaintext + Checking Geo ... - GitLab Geo is available ... Exception: fe_sendauth: no password supplied - GitLab Geo is enabled ... Exception: fe_sendauth: no password supplied - ... - Checking Geo ... Finished - ``` + GitLab Geo is available ... Exception: fe_sendauth: no password supplied + GitLab Geo is enabled ... Exception: fe_sendauth: no password supplied + ... + Checking Geo ... Finished + ``` - - Ensure that you have the `gitlab_rails['db_password']` set to the plain text-password used when creating the hash for `postgresql['sql_user_password']`. + Ensure you have the `gitlab_rails['db_password']` set to the plain-text + password used when creating the hash for `postgresql['sql_user_password']`. -1. Rails is unable to connect to the database +- Rails is unable to connect to the database. - ```plaintext - Checking Geo ... + ```plaintext + Checking Geo ... - GitLab Geo is available ... Exception: FATAL: no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL on - FATAL: no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off - GitLab Geo is enabled ... Exception: FATAL: no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL on - FATAL: no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off - ... - Checking Geo ... Finished - ``` + GitLab Geo is available ... Exception: FATAL: no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL on + FATAL: no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off + GitLab Geo is enabled ... Exception: FATAL: no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL on + FATAL: no pg_hba.conf entry for host "1.1.1.1", user "gitlab", database "gitlabhq_production", SSL off + ... + Checking Geo ... Finished + ``` - - Ensure that you have the IP address of the rails node included in `postgresql['md5_auth_cidr_addresses']`. - - Ensure that you have included the subnet mask on the IP address: `postgresql['md5_auth_cidr_addresses'] = ['1.1.1.1/32']`. + Ensure you have the IP address of the rails node included in `postgresql['md5_auth_cidr_addresses']`. + Also, ensure you have included the subnet mask on the IP address: `postgresql['md5_auth_cidr_addresses'] = ['1.1.1.1/32']`. -1. Rails has supplied the incorrect password +- Rails has supplied the incorrect password. - ```plaintext - Checking Geo ... - GitLab Geo is available ... Exception: FATAL: password authentication failed for user "gitlab" - FATAL: password authentication failed for user "gitlab" - GitLab Geo is enabled ... Exception: FATAL: password authentication failed for user "gitlab" - FATAL: password authentication failed for user "gitlab" - ... - Checking Geo ... Finished - ``` + ```plaintext + Checking Geo ... + GitLab Geo is available ... Exception: FATAL: password authentication failed for user "gitlab" + FATAL: password authentication failed for user "gitlab" + GitLab Geo is enabled ... Exception: FATAL: password authentication failed for user "gitlab" + FATAL: password authentication failed for user "gitlab" + ... + Checking Geo ... Finished + ``` - - Verify the correct password is set for `gitlab_rails['db_password']` that was used when creating the hash in `postgresql['sql_user_password']` by running `gitlab-ctl pg-password-md5 gitlab` and entering the password. + Verify the correct password is set for `gitlab_rails['db_password']` that was + used when creating the hash in `postgresql['sql_user_password']` by running + `gitlab-ctl pg-password-md5 gitlab` and entering the password. -1. Check returns `not a secondary node` +- Check returns `not a secondary node`. - ```plaintext - Checking Geo ... + ```plaintext + Checking Geo ... - GitLab Geo is available ... yes - GitLab Geo is enabled ... yes - GitLab Geo secondary database is correctly configured ... not a secondary node - Database replication enabled? ... not a secondary node - ... - Checking Geo ... Finished - ``` + GitLab Geo is available ... yes + GitLab Geo is enabled ... yes + GitLab Geo secondary database is correctly configured ... not a secondary node + Database replication enabled? ... not a secondary node + ... + Checking Geo ... Finished + ``` - - Ensure that you have added the secondary node in the Admin Area of the **primary** node. - - Ensure that you entered the `external_url` or `gitlab_rails['geo_node_name']` when adding the secondary node in the Admin Area of the **primary** node. - - Prior to GitLab 12.4, edit the secondary node in the Admin Area of the **primary** node and ensure that there is a trailing `/` in the `Name` field. + Ensure you have added the secondary node in the Admin Area of the **primary** node. + Also ensure you entered the `external_url` or `gitlab_rails['geo_node_name']` + when adding the secondary node in the Admin Area of the **primary** node. + In GitLab 12.3 and earlier, edit the secondary node in the Admin Area of the **primary** + node and ensure that there is a trailing `/` in the `Name` field. -1. Check returns `Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist` +- Check returns `Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist`. - ```plaintext - Checking Geo ... + ```plaintext + Checking Geo ... - GitLab Geo is available ... no - Try fixing it: - Upload a new license that includes the GitLab Geo feature - For more information see: - https://about.gitlab.com/features/gitlab-geo/ - GitLab Geo is enabled ... Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist - LINE 8: WHERE a.attrelid = '"geo_nodes"'::regclass + GitLab Geo is available ... no + Try fixing it: + Upload a new license that includes the GitLab Geo feature + For more information see: + https://about.gitlab.com/features/gitlab-geo/ + GitLab Geo is enabled ... Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist + LINE 8: WHERE a.attrelid = '"geo_nodes"'::regclass ^ - : SELECT a.attname, format_type(a.atttypid, a.atttypmod), - pg_get_expr(d.adbin, d.adrelid), a.attnotnull, a.atttypid, a.atttypmod, - c.collname, col_description(a.attrelid, a.attnum) AS comment - FROM pg_attribute a - LEFT JOIN pg_attrdef d ON a.attrelid = d.adrelid AND a.attnum = d.adnum - LEFT JOIN pg_type t ON a.atttypid = t.oid - LEFT JOIN pg_collation c ON a.attcollation = c.oid AND a.attcollation <> t.typcollation - WHERE a.attrelid = '"geo_nodes"'::regclass - AND a.attnum > 0 AND NOT a.attisdropped - ORDER BY a.attnum - ... - Checking Geo ... Finished - ``` - - When performing a PostgreSQL major version (9 > 10) update this is expected. Follow: + : SELECT a.attname, format_type(a.atttypid, a.atttypmod), + pg_get_expr(d.adbin, d.adrelid), a.attnotnull, a.atttypid, a.atttypmod, + c.collname, col_description(a.attrelid, a.attnum) AS comment + FROM pg_attribute a + LEFT JOIN pg_attrdef d ON a.attrelid = d.adrelid AND a.attnum = d.adnum + LEFT JOIN pg_type t ON a.atttypid = t.oid + LEFT JOIN pg_collation c ON a.attcollation = c.oid AND a.attcollation <> t.typcollation + WHERE a.attrelid = '"geo_nodes"'::regclass + AND a.attnum > 0 AND NOT a.attisdropped + ORDER BY a.attnum + ... + Checking Geo ... Finished + ``` - - [initiate-the-replication-process](../setup/database.md#step-3-initiate-the-replication-process) + When performing a PostgreSQL major version (9 > 10) update this is expected. Follow + the [initiate-the-replication-process](../setup/database.md#step-3-initiate-the-replication-process). ## Fixing replication errors The following sections outline troubleshooting steps for fixing replication -errors (indicated by `Database replication working? ... no` in the +error messages (indicated by `Database replication working? ... no` in the [`geo:check` output](#health-check-rake-task). ### Message: `ERROR: replication slots can only be used if max_replication_slots > 0`? This means that the `max_replication_slots` PostgreSQL variable needs to -be set on the **primary** database. In GitLab 9.4, we have made this setting -default to 1. You may need to increase this value if you have more -**secondary** nodes. +be set on the **primary** database. This setting defaults to 1. You may need to +increase this value if you have more **secondary** nodes. Be sure to restart PostgreSQL for this to take effect. See the [PostgreSQL replication setup](../setup/database.md#postgresql-replication) guide for more details. @@ -306,7 +310,7 @@ process](../setup/database.md) on the **secondary** node . ### Message: "Command exceeded allowed execution time" when setting up replication? This may happen while [initiating the replication process](../setup/database.md#step-3-initiate-the-replication-process) on the **secondary** node, -and indicates that your initial dataset is too large to be replicated in the default timeout (30 minutes). +and indicates your initial dataset is too large to be replicated in the default timeout (30 minutes). Re-run `gitlab-ctl replicate-geo-database`, but include a larger value for `--backup-timeout`: @@ -320,7 +324,7 @@ sudo gitlab-ctl \ ``` This gives the initial replication up to six hours to complete, rather than -the default thirty minutes. Adjust as required for your installation. +the default 30 minutes. Adjust as required for your installation. ### Message: "PANIC: could not write to file `pg_xlog/xlogtemp.123`: No space left on device" @@ -336,7 +340,7 @@ log data to build up in `pg_xlog`. Removing the unused slots can reduce the amou NOTE: Using `gitlab-rails dbconsole` does not work, because managing replication slots requires superuser permissions. -1. View your replication slots with: +1. View your replication slots: ```sql SELECT * FROM pg_replication_slots; @@ -345,7 +349,7 @@ log data to build up in `pg_xlog`. Removing the unused slots can reduce the amou Slots where `active` is `f` are not active. - When this slot should be active, because you have a **secondary** node configured using that slot, - log in to that **secondary** node and check the [PostgreSQL logs](../../logs.md#postgresql-logs) + sign in to that **secondary** node and check the [PostgreSQL logs](../../logs.md#postgresql-logs) to view why the replication is not running. - If you are no longer using the slot (for example, you no longer have Geo enabled), you can remove it with in the @@ -357,11 +361,11 @@ Slots where `active` is `f` are not active. ### Message: "ERROR: canceling statement due to conflict with recovery" -This error occurs infrequently under normal usage, and the system is resilient +This error message occurs infrequently under normal usage, and the system is resilient enough to recover. However, under certain conditions, some database queries on secondaries may run -excessively long, which increases the frequency of this error. This can lead to a situation +excessively long, which increases the frequency of this error message. This can lead to a situation where some queries never complete due to being canceled on every replication. These long-running queries are @@ -428,7 +432,16 @@ If large repositories are affected by this problem, their resync may take a long time and cause significant load on your Geo nodes, storage and network systems. -If you get the error `Synchronization failed - Error syncing repository` along with the following log messages, this indicates that the expected `geo` remote is not present in the `.git/config` file +If you see the error message `Synchronization failed - Error syncing repository` along with `fatal: fsck error in packed object`, this indicates +a consistency check error when syncing the repository. + +One example of a consistency error is: `error: object f4a87a3be694fbbd6e50a668a31a8513caeaafe3: hasDotgit: contains '.git`. + +Removing the malformed objects causing consistency errors require rewriting the repository history, which is not always an option. However, +it's possible to override the consistency checks instead. To do that, follow +[the instructions in the Gitaly docs](../../gitaly/configure_gitaly.md#repository-consistency-checks). + +You can also get the error message `Synchronization failed - Error syncing repository` along with the following log messages, this indicates that the expected `geo` remote is not present in the `.git/config` file of a repository on the secondary Geo node's file system: ```json @@ -451,11 +464,11 @@ of a repository on the secondary Geo node's file system: To solve this: -1. Log into the secondary Geo node. +1. Sign in to the secondary Geo node. 1. Back up [the `.git` folder](../../repository_storage_types.md#translate-hashed-storage-paths). -1. Optional: [Spot-check](../../troubleshooting/log_parsing.md#find-all-projects-affected-by-a-fatal-git-problem) +1. Optional. [Spot-check](../../troubleshooting/log_parsing.md#find-all-projects-affected-by-a-fatal-git-problem) a few of those IDs whether they indeed correspond to a project with known Geo replication failures. Use `fatal: 'geo'` as the `grep` term and the following API call: @@ -490,18 +503,19 @@ GitLab places a timeout on all repository clones, including project imports and Geo synchronization operations. If a fresh `git clone` of a repository on the **primary** takes more than the default three hours, you may be affected by this. -To increase the timeout, add the following line to `/etc/gitlab/gitlab.rb` -on the **secondary** node: +To increase the timeout: -```ruby -gitlab_rails['gitlab_shell_git_timeout'] = 14400 -``` +1. On the **secondary** node, add the following line to `/etc/gitlab/gitlab.rb`: -Then reconfigure GitLab: + ```ruby + gitlab_rails['gitlab_shell_git_timeout'] = 14400 + ``` -```shell -sudo gitlab-ctl reconfigure -``` +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` This increases the timeout to four hours (14400 seconds). Choose a time long enough to accommodate a full clone of your largest repositories. @@ -512,7 +526,7 @@ If new LFS objects are never replicated to secondary Geo nodes, check the versio GitLab you are running. GitLab versions 11.11.x or 12.0.x are 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). -To resolve the issue, upgrade to GitLab 12.1 or newer. +To resolve the issue, upgrade to GitLab 12.1 or later. ### Failures during backfill @@ -524,7 +538,7 @@ of the backfill queue, therefore these failures only clear up **after** the back If you get a **secondary** node in a broken state and want to reset the replication state, to start again from scratch, there are a few steps that can help you: -1. Stop Sidekiq and the Geo LogCursor +1. Stop Sidekiq and the Geo LogCursor. It's possible to make Sidekiq stop gracefully, but making it stop getting new jobs and wait until the current jobs to finish processing. @@ -547,7 +561,7 @@ to start again from scratch, there are a few steps that can help you: gitlab-ctl tail sidekiq ``` -1. Rename repository storage folders and create new ones. If you are not concerned about possible orphaned directories and files, then you can simply skip this step. +1. Rename repository storage folders and create new ones. If you are not concerned about possible orphaned directories and files, you can skip this step. ```shell mv /var/opt/gitlab/git-data/repositories /var/opt/gitlab/git-data/repositories.old @@ -559,14 +573,14 @@ to start again from scratch, there are a few steps that can help you: 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 +1. Optional. Rename other data folders and create new ones. WARNING: You may still have files on the **secondary** node that have been removed from the **primary** node, but this - removal has not been reflected. If you skip this step, these files are not removed at all from the Geo node. + removal has not been reflected. If you skip this step, these files are not removed from the Geo node. - Any uploaded content like file attachments, avatars or LFS objects are stored in a - subfolder in one of the two paths below: + Any uploaded content (like file attachments, avatars, or LFS objects) is stored in a + subfolder in one of these paths: - `/var/opt/gitlab/gitlab-rails/shared` - `/var/opt/gitlab/gitlab-rails/uploads` @@ -593,7 +607,7 @@ to start again from scratch, there are a few steps that can help you: gitlab-ctl reconfigure ``` -1. Reset the Tracking Database +1. Reset the Tracking Database. ```shell gitlab-rake geo:db:drop # on a secondary app node @@ -601,7 +615,7 @@ to start again from scratch, there are a few steps that can help you: gitlab-rake geo:db:setup # on a secondary app node ``` -1. Restart previously stopped services +1. Restart previously stopped services. ```shell gitlab-ctl start @@ -611,10 +625,10 @@ to start again from scratch, there are a few steps that can help you: On the top bar, under **Menu > Admin > Geo > Nodes**, if the Design repositories progress bar shows -`Synced` and `Failed` greater than 100%, and negative `Queued`, then the instance +`Synced` and `Failed` greater than 100%, and negative `Queued`, the instance is likely affected by [a bug in GitLab 13.2 and 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/241668). -It was [fixed in 13.4+](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40643). +It was [fixed in GitLab 13.4 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40643). To determine the actual replication status of design repositories in a [Rails console](../../operations/rails_console.md): @@ -665,7 +679,7 @@ determine the actual replication status of Design repositories. `gitlab-ctl promote-to-primary-node` fails since it runs preflight checks. If the [previous snippet](#design-repository-failures-on-mirrored-projects-and-project-imports) -shows that all designs are synced, then you can use the +shows that all designs are synced, you can use the `--skip-preflight-checks` option or the `--force` option to move forward with promotion. @@ -676,15 +690,70 @@ promotion. [previous snippet](#design-repository-failures-on-mirrored-projects-and-project-imports) to determine the actual replication status of Design repositories. +### Sync failure message: "Verification failed with: Error during verification: File is not checksummable" + +In GitLab 14.5 and earlier, certain data types which were missing on the Geo primary site were marked as "synced" on Geo secondary sites. This was because from the perspective of Geo secondary sites, the state matched the primary site and nothing more could be done on secondary sites. + +Secondaries would regularly try to sync these files again by using the "verification" feature: + +- Verification fails since the file doesn't exist. +- The file is marked "sync failed". +- Sync is retried. +- The file is marked "sync succeeded". +- The file is marked "needs verification". +- Repeat until the file is available again on the primary site. + +This can be confusing to troubleshoot, since the registry entries are moved through a logical loop by various background jobs. Also, `last_sync_failure` and `verification_failure` are empty after "sync succeeded" but before verification is retried. + +If you see sync failures repeatedly and alternately increase, while successes decrease and vice versa, this is likely to be caused by missing files on the primary site. You can confirm this by searching `geo.log` on secondary sites for `File is not checksummable` affecting the same files over and over. + +After confirming this is the problem, the files on the primary site need to be fixed. Some possible causes: + +- An NFS share became unmounted. +- A disk died or became corrupted. +- Someone unintentionally deleted a file or directory. +- Bugs in GitLab application: + - A file was moved when it shouldn't have been moved. + - A file wasn't moved when it should have been moved. + - A wrong path was generated in the code. +- A non-atomic backup was restored. +- Services or servers or network infrastructure was interrupted/restarted during use. + +The appropriate action sometimes depends on the cause. For example, you can remount an NFS share. Often, a root cause may not be apparent or not useful to discover. If you have regular backups, it may be expedient to look through them and pull files from there. + +In some cases, a file may be determined to be of low value, and so it may be worth deleting the record. + +Geo itself is an excellent mitigation for files missing on the primary. If a file disappears on the primary but it was already synced to the secondary, you can grab the secondary's file. In cases like this, the `File is not checksummable` error message will not occur on Geo secondary sites, and only the primary will log this error message. + +This problem is more likely to show up in Geo secondary sites which were set up long after the original GitLab site. In this case, Geo is only surfacing an existing problem. + +This behavior affects only the following data types through GitLab 14.6: + +| Data type | From version | +| ------------------------ | ------------ | +| Package Registry | 13.10 | +| Pipeline Artifacts | 13.11 | +| Terraform State Versions | 13.12 | +| Infrastructure Registry | 14.0 | +| External MR diffs | 14.6 | +| LFS Objects | 14.6 | +| Pages Deployments | 14.6 | +| Uploads | 14.6 | +| CI Job Artifacts | 14.6 | + +[Since GitLab 14.7, files that are missing on the primary site are now treated as sync failures](https://gitlab.com/gitlab-org/gitlab/-/issues/348745) +to make Geo visibly surface data loss risks. The sync/verification loop is +therefore short-circuited. `last_sync_failure` is now set to `The file is missing on the Geo primary site`. + ## Fixing errors during a failover or when promoting a secondary to a primary node -The following are possible errors that might be encountered during failover or +The following are possible error messages that might be encountered during failover or when promoting a secondary to a primary node with strategies to resolve them. ### Message: ActiveRecord::RecordInvalid: Validation failed: Name has already been taken When [promoting a **secondary** site](../disaster_recovery/index.md#step-3-promoting-a-secondary-site), -you might encounter the following error: +you might encounter the following error message: ```plaintext Running gitlab-rake geo:set_secondary_as_primary... @@ -712,7 +781,7 @@ or `gitlab-ctl promote-to-primary-node`, either: Rake::Task['geo:set_secondary_as_primary'].invoke ``` -- Upgrade to GitLab 12.6.3 or newer if it is safe to do so. For example, +- Upgrade to GitLab 12.6.3 or later if it is safe to do so. For example, if the failover was just a test. A [caching-related bug](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22021) was fixed. @@ -720,8 +789,8 @@ or `gitlab-ctl promote-to-primary-node`, either: ### Message: ActiveRecord::RecordInvalid: Validation failed: Enabled Geo primary node cannot be disabled If you disabled a secondary node, either with the [replication pause task](../index.md#pausing-and-resuming-replication) -(13.2) or by using the user interface (13.1 and earlier), you must first -re-enable the node before you can continue. This is fixed in 13.4. +(GitLab 13.2) or by using the user interface (GitLab 13.1 and earlier), you must first +re-enable the node before you can continue. This is fixed in GitLab 13.4. This can be fixed in the database. @@ -747,12 +816,12 @@ This can be fixed in the database. UPDATE geo_nodes SET enabled = true WHERE url = 'https://<secondary url>/' AND enabled = false;" ``` - This should update 1 row. + This should update one row. ### Message: ``NoMethodError: undefined method `secondary?' for nil:NilClass`` When [promoting a **secondary** site](../disaster_recovery/index.md#step-3-promoting-a-secondary-site), -you might encounter the following error: +you might encounter the following error message: ```plaintext sudo gitlab-rake geo:set_secondary_as_primary @@ -767,7 +836,7 @@ Tasks: TOP => geo:set_secondary_as_primary (See full trace by running task with --trace) ``` -This command is intended to be executed on a secondary site only, and this error +This command is intended to be executed on a secondary site only, and this error message is displayed if you attempt to run this command on a primary site. ### Message: `sudo: gitlab-pg-ctl: command not found` @@ -789,7 +858,7 @@ In this case, the workaround is to use the full path to the binary, for example: sudo /opt/gitlab/embedded/bin/gitlab-pg-ctl promote ``` -GitLab 12.9 and later are [unaffected by this error](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5147). +GitLab 12.9 and later are [unaffected by this error message](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5147). ### Message: `ERROR - Replication is not up-to-date` during `gitlab-ctl promotion-preflight-checks` @@ -807,7 +876,7 @@ shows that it is complete, you can add `--skip-preflight-checks` to make the com ### Errors when using `--skip-preflight-checks` or `--force` -Before GitLab 13.5, you could bump into one of the following errors when using +In GitLab 13.4 and earlier, you could receive one of the following error messages when using `--skip-preflight-checks` or `--force`: ```plaintext @@ -817,7 +886,7 @@ get_ctl_options': invalid option: --force (OptionParser::InvalidOption) ``` This can happen with XFS or file systems that list files in lexical order, because the -load order of the Omnibus command files can be different than expected, and a global function would get redefined. +load order of the Omnibus GitLab command files can be different than expected, and a global function would get redefined. More details can be found in [the related issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6076). The workaround is to manually run the preflight checks and promote the database, by running @@ -843,8 +912,8 @@ registry record related to the orphan files on disk. ### Message: The redirect URI included is not valid -If you are able to log in to the **primary** node, but you receive this error -when attempting to log into a **secondary**, you should check that the Geo +If you are able to sign in to the **primary** node, but you receive this error message +when attempting to sign in to a **secondary**, you should verify the Geo node's URL matches its external URL. On the **primary** node: @@ -858,7 +927,7 @@ On the **primary** node: ## Fixing common errors -This section documents common errors reported in the Admin Area and how to fix them. +This section documents common error messages reported in the Admin Area, and how to fix them. ### Geo database configuration file is missing @@ -879,20 +948,28 @@ It is safest to use a fresh secondary, or reset the whole secondary by following ### Geo node has a database that is writable which is an indication it is not configured for replication with the primary node -This error refers to a problem with the database replica on a **secondary** node, +This error message refers to a problem with the database replica on a **secondary** node, which Geo expects to have access to. It usually means, either: - An unsupported replication method was used (for example, logical replication). -- The instructions to setup a [Geo database replication](../setup/database.md) were not followed correctly. +- The instructions to set up a [Geo database replication](../setup/database.md) were not followed correctly. - Your database connection details are incorrect, that is you have specified the wrong user in your `/etc/gitlab/gitlab.rb` file. -A common source of confusion with **secondary** nodes is that it requires two separate -PostgreSQL instances: +Geo **secondary** sites require two separate PostgreSQL instances: - A read-only replica of the **primary** node. - A regular, writable instance that holds replication metadata. That is, the Geo tracking database. +This error message indicates that the replica database in the **secondary** site is misconfigured and replication has stopped. + +To restore the database and resume replication, you can do one of the following: + +- [Reset the Geo secondary site replication](#resetting-geo-secondary-node-replication). +- [Set up a new secondary Geo Omnibus instance](../setup/index.md#using-omnibus-gitlab). + +If you set up a new secondary from scratch, you must also [remove the old site from the Geo cluster](remove_geo_site.md#removing-secondary-geo-sites). + ### Geo node does not appear to be replicating the database from the primary node The most common problems that prevent the database from replicating correctly are: @@ -920,7 +997,7 @@ This can be caused by orphaned records in the project registry. You can clear th ### Geo Admin Area returns 404 error for a secondary node Sometimes `sudo gitlab-rake gitlab:geo:check` indicates that the **secondary** node is -healthy, but a 404 error for the **secondary** node is returned in the Geo Admin Area on +healthy, but a 404 Not Found error message for the **secondary** node is returned in the Geo Admin Area on the **primary** node. To resolve this issue: @@ -938,7 +1015,7 @@ If using a load balancer, ensure that the load balancer's URL is set as the `ext ### Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode -In GitLab 13.9 through GitLab 14.3, when [GitLab Maintenance Mode](../../maintenance_mode/index.md) is enabled, the status of Geo secondary sites will stop getting updated. After 10 minutes, the status will become `Unhealthy`. +In GitLab 13.9 through GitLab 14.3, when [GitLab Maintenance Mode](../../maintenance_mode/index.md) is enabled, the status of Geo secondary sites will stop getting updated. After 10 minutes, the status changes to `Unhealthy`. Geo secondary sites will continue to replicate and verify data, and the secondary sites should still be usable. You can use the [Sync status Rake task](#sync-status-rake-task) to determine the actual status of a secondary site during Maintenance Mode. @@ -947,7 +1024,7 @@ This bug was [fixed in GitLab 14.4](https://gitlab.com/gitlab-org/gitlab/-/issue ### GitLab Pages return 404 errors after promoting This is due to [Pages data not being managed by Geo](datatypes.md#limitations-on-replicationverification). -Find advice to resolve those errors in the +Find advice to resolve those error messages in the [Pages administration documentation](../../../administration/pages/index.md#404-error-after-promoting-a-geo-secondary-to-a-primary-node). ## Fixing client errors @@ -958,4 +1035,4 @@ You may have problems if you're running a version of [Git LFS](https://git-lfs.g As noted in [this authentication issue](https://github.com/git-lfs/git-lfs/issues/3025), requests redirected from the secondary to the primary node do not properly send the Authorization header. This may result in either an infinite `Authorization <-> Redirect` -loop, or Authorization errors. +loop, or Authorization error messages. diff --git a/doc/administration/geo/replication/usage.md b/doc/administration/geo/replication/usage.md index f3c8f6ac759..b1183e56cd0 100644 --- a/doc/administration/geo/replication/usage.md +++ b/doc/administration/geo/replication/usage.md @@ -2,7 +2,6 @@ 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 --- <!-- Please update EE::GitLab::GeoGitAccess::GEO_SERVER_DOCS_URL if this file is moved) --> @@ -11,7 +10,8 @@ type: howto After you set up the [database replication and configure the Geo nodes](../index.md#setup-instructions), use your closest GitLab site as you would do with the primary one. -You can push directly to a **secondary** site (for both HTTP, SSH including Git LFS), and the request will be proxied to the primary site instead ([introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in GitLab 11.3). +You can push directly to a **secondary** site (for both HTTP, SSH including +Git LFS), and the request will be proxied to the primary site instead. Example of the output you will see when pushing to a **secondary** site: diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md index 883e335ff94..d3a132a6666 100644 --- a/doc/administration/geo/replication/version_specific_updates.md +++ b/doc/administration/geo/replication/version_specific_updates.md @@ -2,7 +2,6 @@ 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 --- # Version-specific update instructions **(PREMIUM SELF)** @@ -378,10 +377,3 @@ 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 - -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. diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index 756e73f022f..cd77647e7dc 100644 --- a/doc/administration/geo/setup/external_database.md +++ b/doc/administration/geo/setup/external_database.md @@ -2,7 +2,6 @@ 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 with external PostgreSQL instances **(PREMIUM SELF)** @@ -184,7 +183,7 @@ To configure the connection to the external read-replica database and enable Log database to keep track of replication status and automatically recover from potential replication issues. Omnibus automatically configures a tracking database when `roles ['geo_secondary_role']` is set. -If you want to run this database external to Omnibus, please follow the instructions below. +If you want to run this database external to Omnibus GitLab, use the following instructions. If you are using a cloud-managed service for the tracking database, you may need to grant additional roles to your tracking database user (by default, this is diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index bff2aee1d2d..3be3c11947e 100644 --- a/doc/administration/get_started.md +++ b/doc/administration/get_started.md @@ -1,5 +1,7 @@ --- info: For assistance with this TAM Onboarding page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +stage: none +group: unassigned --- # Get started administering GitLab **(FREE)** diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index c8c532e9a01..29156d9b3e1 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -1,20 +1,17 @@ --- 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/#assignments" -type: reference +info: To 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: "Set and configure Git protocol v2" --- # Configuring Git Protocol v2 **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/46555) in GitLab 11.4. -> - [Temporarily disabled](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55769) in GitLab 11.5.8, 11.6.6, 11.7.1, and 11.8+. -> - [Re-enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/27828) in GitLab 12.8. +> [Re-enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/27828) in GitLab 12.8. Git protocol v2 improves the v1 wire protocol in several ways and is -enabled by default in GitLab for HTTP requests. In order to enable SSH, -further configuration is needed by the administrator. +enabled by default in GitLab for HTTP requests. To enable SSH, additional +configuration is required by an administrator. More details about the new features and improvements are available in the [Google Open Source Blog](https://opensource.googleblog.com/2018/05/introducing-git-protocol-version-2.html) @@ -51,7 +48,7 @@ sudo systemctl restart ssh ## Instructions -In order to use the new protocol, clients need to either pass the configuration +To use the new protocol, clients need to either pass the configuration `-c protocol.version=2` to the Git command, or set it globally: ```shell diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md index b31a02aae0a..a0c959d5de9 100644 --- a/doc/administration/gitaly/configure_gitaly.md +++ b/doc/administration/gitaly/configure_gitaly.md @@ -565,6 +565,12 @@ Note the following: - You can configure Gitaly servers with both an unencrypted listening address `listen_addr` and an encrypted listening address `tls_listen_addr` at the same time. This allows you to gradually transition from unencrypted to encrypted traffic if necessary. +- When running Praefect sub-commands such as `dial-nodes` and `list-untracked-repositories` from the command line with Gitaly TLS enabled, you must set + the `SSL_CERT_DIR` or `SSL_CERT_FILE` environment variable so that the Gitaly certificate is trusted. For example: + + ```shell + sudo SSL_CERT_DIR=/etc/gitlab/trusted_certs /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dial-nodes + ``` To configure Gitaly with TLS: @@ -1125,3 +1131,66 @@ Example: "time":"2021-03-25T14:57:53.543Z" } ``` + +## Repository consistency checks + +Gitaly runs repository consistency checks: + +- When triggering a repository check. +- When changes are fetched from a mirrored repository. +- When users push changes into repository. + +These consistency checks verify that a repository has all required objects and +that these objects are valid objects. They can be categorized as: + +- Basic checks that assert that a repository doesn't become corrupt. This + includes connectivity checks and checks that objects can be parsed. +- Security checks that recognize objects that are suitable to exploit past + security-related bugs in Git. +- Cosmetic checks that verify that all object metadata is valid. Older Git + versions and other Git implementations may have produced objects with invalid + metadata, but newer versions can interpret these malformed objects. + +Removing malformed objects that fail the consistency checks requires a +rewrite of the repository's history, which often can't be done. Therefore, +Gitaly by default disables consistency checks for a range of cosmetic issues +that don't negatively impact repository consistency. + +By default, Gitaly doesn't disable basic or security-related checks so +to not distribute objects that can trigger known vulnerabilities in Git +clients. This also limits the ability to import repositories containing such +objects even if the project doesn't have malicious intent. + +### Override repository consistency checks + +Instance administrators can override consistency checks if they must +process repositories that do not pass consistency checks. + +For Omnibus GitLab installations, edit `/etc/gitlab/gitlab.rb` and set the +following keys (in this example, to disable the `hasDotgit` consistency check): + +```ruby +ignored_git_errors = ["hasDotgit = ignore"] +omnibus_gitconfig['system'] = { + "fsck" => ignored_git_errors, + "fetch.fsck" => ignored_git_errors, + "receive.fsck" => ignored_git_errors, +} +``` + +For source installs, edit the Gitaly configuration (`gitaly.toml`) to do the +equivalent: + +```toml +[[git.config]] +key = "fsck.hasDotgit" +value = "ignore" + +[[git.config]] +key = "fetch.fsck.hasDotgit" +value = "ignore" + +[[git.config]] +key = "receive.fsck.hasDotgit" +value = "ignore" +``` diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index f99bbf21840..4d60832720b 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -490,7 +490,15 @@ The following are useful queries for monitoring Gitaly: ### Monitor Gitaly Cluster -To monitor Gitaly Cluster (Praefect), you can use these Prometheus metrics: +To monitor Gitaly Cluster (Praefect), you can use these Prometheus metrics. There are two separate metrics +endpoints from which metrics can be scraped: + +- The default `/metrics` endpoint. +- `/db_metrics`, which contains metrics that require database queries. + +#### Default Prometheus `/metrics` endpoint + +The following metrics are available from the `/metrics` endpoint: - `gitaly_praefect_read_distribution`, a counter to track [distribution of reads](#distributed-reads). It has two labels: @@ -523,6 +531,18 @@ To monitor [strong consistency](#strong-consistency), you can use the following You can also monitor the [Praefect logs](../logs.md#praefect-logs). +#### Database metrics `/db_metrics` endpoint + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/3286) in GitLab 14.5. + +The following metrics are available from the `/db_metrics` endpoint: + +- `gitaly_praefect_unavailable_repositories`, the number of repositories that have no healthy, up to date replicas. +- `gitaly_praefect_read_only_repositories`, the number of repositories in read-only mode within a virtual storage. + This metric is available for backwards compatibility reasons. `gitaly_praefect_unavailable_repositories` is more + accurate. +- `gitaly_praefect_replication_queue_depth`, the number of jobs in the replication queue. + ## Recover from failure Gitaly Cluster can [recover from certain types of failure](recovery.md). diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index d3a8662080f..e2db30b8358 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -20,6 +20,9 @@ Configure Gitaly Cluster using either: Smaller GitLab installations may need only [Gitaly itself](index.md). +To upgrade a Gitaly Cluster, follow the documentation for +[zero downtime upgrades](../../update/zero_downtime.md#gitaly-cluster). + ## Requirements The minimum recommended configuration for a Gitaly Cluster requires: @@ -376,8 +379,8 @@ configuration option is set. For more details, consult the PgBouncer documentati If there are multiple Praefect nodes: -- Complete the following steps for **each** node. -- Designate one node as the "deploy node", and configure it first. +1. Designate one node as the deploy node, and configure it using the following steps. +1. Complete the following steps for each additional node. To complete this section you need a [configured PostgreSQL server](#postgresql), including: @@ -405,7 +408,7 @@ On the **Praefect** node: # Enable only the Praefect service praefect['enable'] = true - # Prevent database connections during 'gitlab-ctl reconfigure' + # Disable database migrations to prevent database connections during 'gitlab-ctl reconfigure' gitlab_rails['auto_migrate'] = false praefect['auto_migrate'] = false ``` @@ -415,10 +418,21 @@ On the **Praefect** node: ```ruby praefect['listen_addr'] = '0.0.0.0:2305' + ``` +1. Configure Prometheus metrics by editing + `/etc/gitlab/gitlab.rb`: + + ```ruby # Enable Prometheus metrics access to Praefect. You must use firewalls # to restrict access to this address/port. + # The default metrics endpoint is /metrics praefect['prometheus_listen_addr'] = '0.0.0.0:9652' + + # Some metrics run queries against the database. Enabling separate database metrics allows + # these metrics to be collected when the metrics are + # scraped on a separate /db_metrics endpoint. + praefect['separate_database_metrics'] = true ``` 1. Configure a strong `auth_token` for **Praefect** by editing @@ -517,7 +531,7 @@ On the **Praefect** node: 1. For: - The "deploy node": - 1. Enable Praefect auto-migration again by setting `praefect['auto_migrate'] = true` in + 1. Enable Praefect database auto-migration again by setting `praefect['auto_migrate'] = true` in `/etc/gitlab/gitlab.rb`. 1. To ensure database migrations are only run during reconfigure and not automatically on upgrade, run: @@ -556,8 +570,6 @@ On the **Praefect** node: edit `/etc/gitlab/gitlab.rb`, remember to run `sudo gitlab-ctl reconfigure` again before trying the `sql-ping` command. -**The steps above must be completed for each Praefect node!** - #### Enabling TLS support > [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/1698) in GitLab 13.2. @@ -755,7 +767,7 @@ For more information on Gitaly server configuration, see our # Enable Prometheus if needed prometheus['enable'] = true - # Prevent database connections during 'gitlab-ctl reconfigure' + # Disable database migrations to prevent database connections during 'gitlab-ctl reconfigure' gitlab_rails['auto_migrate'] = false ``` @@ -883,9 +895,9 @@ of choice already. Some examples include [HAProxy](https://www.haproxy.org/) Big-IP LTM, and Citrix Net Scaler. This documentation outlines what ports and protocols you need configure. -WARNING: -Long-running background jobs can maintain an idle connection with Praefect for up 6 hours. Set your load balancer timeout to be at least -6 hours long. +NOTE: +We recommend the equivalent of HAProxy `leastconn` load-balancing strategy because long-running operations (for example, +clones) keep some connections open for extended periods. | LB Port | Backend Port | Protocol | |:--------|:-------------|:---------| @@ -1217,9 +1229,9 @@ To migrate existing clusters: 1. Praefect nodes didn't historically keep database records of every repository stored on the cluster. When the `per_repository` election strategy is configured, Praefect expects to have database records of - each repository. A [background migration](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2749) is - included in GitLab 13.6 and later to create any missing database records for repositories. Before migrating - you should verify the migration has run by checking Praefect's logs: + each repository. A [background database migration](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2749) is + included in GitLab 13.6 and later to create any missing database records for repositories. Before migrating, + check Praefect's logs to verify that the database migration ran. Check Praefect's logs for `repository importer finished` message. The `virtual_storages` field contains the names of virtual storages and whether they've had any missing database records created. @@ -1236,8 +1248,8 @@ To migrate existing clusters: {"level":"info","msg":"repository importer finished","pid":19752,"time":"2021-04-28T11:41:36.743Z","virtual_storages":{"default":false}} ``` - The migration is ran when Praefect starts up. If the migration is unsuccessful, you can restart - a Praefect node to reattempt it. The migration only runs with `sql` election strategy configured. + The database migration runs when Praefect starts. If the database migration is unsuccessful, you can restart + a Praefect node to reattempt it. 1. Running two different election strategies side by side can cause a split brain, where different Praefect nodes consider repositories to have different primaries. This can be avoided either: diff --git a/doc/administration/img/instance_review_button.png b/doc/administration/img/instance_review_button.png Binary files differdeleted file mode 100644 index b7604d7c7e5..00000000000 --- a/doc/administration/img/instance_review_button.png +++ /dev/null diff --git a/doc/administration/img/instance_review_v14_7.png b/doc/administration/img/instance_review_v14_7.png Binary files differnew file mode 100644 index 00000000000..e9f6316c237 --- /dev/null +++ b/doc/administration/img/instance_review_v14_7.png diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 3f54f5dd576..84b30724dff 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -170,6 +170,15 @@ Reply by email should now be working. cd /home/git/gitlab ``` +1. Install the `gitlab-mail_room` gem manually: + + ```shell + gem install gitlab-mail_room + ``` + + NOTE: This step is necessary to avoid thread deadlocks and to support the latest MailRoom features. See + [this explanation](../development/emails.md#mailroom-gem-updates) for more details. + 1. Find the `incoming_email` section in `config/gitlab.yml`, enable the feature and fill in the details for your specific IMAP server and email account (see [examples](#configuration-examples) below). @@ -470,6 +479,10 @@ incoming_email: ##### Dedicated email address +NOTE: +Supports [Reply by Email](reply_by_email.md) only. +Cannot support [Service Desk](../user/project/service_desk.md). + Assumes the dedicated email address `incoming@exchange.example.com`. Example for Omnibus installs: @@ -531,19 +544,20 @@ enabled by default, and must be enabled through PowerShell. This series of PowerShell commands enables [sub-addressing](#email-sub-addressing) at the organization level in Office 365. This allows all mailboxes in the organization -to receive sub-addressed mail: +to receive sub-addressed mail. -```powershell -Set-ExecutionPolicy RemoteSigned -Scope CurrentUser +To enable sub-addressing: -$UserCredential = Get-Credential +1. Download and install the `ExchangeOnlineManagement` module from the [PowerShell gallery](https://www.powershellgallery.com/packages/ExchangeOnlineManagement/). +1. In PowerShell, run the following commands: -$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection - -Import-PSSession $Session -DisableNameChecking - -Set-OrganizationConfig -AllowPlusAddressInRecipients $true -``` + ```powershell + Set-ExecutionPolicy RemoteSigned -Scope CurrentUser + Import-Module ExchangeOnlineManagement + Connect-ExchangeOnline + Set-OrganizationConfig -AllowPlusAddressInRecipients $true + Disconnect-ExchangeOnline + ``` This example for Omnibus GitLab assumes the mailbox `incoming@office365.example.com`: @@ -655,6 +669,10 @@ incoming_email: ##### Dedicated email address +NOTE: +Supports [Reply by Email](reply_by_email.md) only. +Cannot support [Service Desk](../user/project/service_desk.md). + This example for Omnibus installs assumes the dedicated email address `incoming@office365.example.com`: ```ruby diff --git a/doc/administration/index.md b/doc/administration/index.md index d78c9d80b5f..bd6549fca80 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -55,7 +55,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [File hooks](file_hooks.md): With custom file hooks, 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) +- [Customer experience improvement and 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. @@ -172,7 +172,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Job artifacts](job_artifacts.md): Enable, disable, and configure job artifacts (a set of files and directories which are outputted by a job when it completes successfully). - [Job logs](job_logs.md): Information about the job logs. - [Register runners](../ci/runners/runners_scope.md): Learn how to register and configure runners. -- [Shared runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota): Limit the usage of pipeline minutes for shared runners. +- [Shared runners quota of CI/CD minutes](../ci/pipelines/cicd_minutes.md): Limit the usage of CI/CD minutes for shared runners. - [Enable or disable Auto DevOps](../topics/autodevops/index.md#enable-or-disable-auto-devops): Enable or disable Auto DevOps for your instance. ## Snippet settings diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index bfe59d5277b..3bedb6b01bd 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -151,7 +151,7 @@ Plan.default.actual_limits.update!(web_hook_calls: 10) Set the limit to `0` to disable it. -- **Default rate limit**: Disabled. +- **Default rate limit**: Disabled (unlimited). ## Gitaly concurrency limit @@ -230,10 +230,8 @@ There is a limit when embedding metrics in GitLab Flavored Markdown (GFM) for pe ## Number of webhooks -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 for 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): +To set the maximum number of group or project webhooks for 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: @@ -248,6 +246,11 @@ Plan.default.actual_limits.update!(group_hooks: 100) Set the limit to `0` to disable it. +- **Default maximum number of webhooks**: `100` per project, `50` per group +- **Maximum payload size**: 25 MB + +For GitLab.com, see the [webhook limits for GitLab.com](../user/gitlab_com/index.md#webhooks). + ## Pull Mirroring Interval > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/237891) in GitLab 13.7. @@ -640,7 +643,7 @@ To set this limit to `100` on a self-managed instance, run the following command [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby -Plan.default.actual_limits.update!(dotenv_variable_limit: 100) +Plan.default.actual_limits.update!(dotenv_variables: 100) ``` This limit is [enabled on GitLab.com](../user/gitlab_com/index.md#gitlab-cicd). @@ -658,7 +661,7 @@ To set this limit to 5KB on a self-managed installation, run the following in th [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby -Plan.default.actual_limits.update!(dotenv_size_limit: 5.kilobytes) +Plan.default.actual_limits.update!(dotenv_size: 5.kilobytes) ``` ## Instance monitoring and metrics diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index 872cdb239bd..f444589bdf3 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -4,26 +4,26 @@ 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/#assignments --- -# Instance Review **(FREE SELF)** +# Instance review **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6995) in GitLab 11.3. +If you run a self-managed instance with 50 or more users on the Free tier +([either Community Edition or unlicensed Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/)), +you can request a free instance review. -If you run a medium-sized self-managed instance (50+ users) of a free version of GitLab, -[either Community Edition or unlicensed Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/), -you qualify for a free Instance Review. +<!-- vale gitlab.FutureTense = NO --> -1. Sign in as an administrator. -1. In the top menu, click your user icon, and select - **Get a free instance review**: +After you submit the request, a GitLab team member will review your instance +details and contact you with suggestions to improve your use of GitLab. -  +<!-- vale gitlab.FutureTense = YES --> -1. GitLab redirects you to a form with prefilled data obtained from your instance. -1. Click **Submit** to see the initial report. +To request an instance review: -<!-- vale gitlab.FutureTense = NO --> +1. Sign in as an administrator. +1. On the top bar, in the top right corner, select your avatar. +1. Select **Get a free instance review**. -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 --> +1. On the instance review page, enter your contact details. +1. Select **Request Instance Review**. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 64b5ddbd165..62c403bfe43 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Jobs artifacts administration **(FREE SELF)** -This is the administration documentation. For the user guide see [pipelines/job_artifacts](../ci/pipelines/job_artifacts.md). +This is the administration documentation. To learn how to use job artifacts in your GitLab CI/CD pipeline, +see the [job artifacts configuration documentation](../ci/pipelines/job_artifacts.md). An artifact is a list of files and directories attached to a job after it finishes. This feature is enabled by default in all GitLab installations. diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index f2748305c24..5c6ea7f52eb 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -150,8 +150,8 @@ server, these two locations on the file system have to be shared using NFS. To eliminate both file system requirements: -- [Enable the incremental logging feature](#enable-or-disable-incremental-logging), which uses Redis instead of disk space for temporary caching of job logs. -- Configure [object storage](job_artifacts.md#object-storage-settings) for storing archived job logs. +1. Configure [object storage](job_artifacts.md#object-storage-settings) for storing archived job logs. +1. [Enable the incremental logging feature](#enable-or-disable-incremental-logging), which uses Redis instead of disk space for temporary caching of job logs. ### Technical details diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 263fe699529..0d7635405d6 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -20,6 +20,54 @@ including adjusting log retention, log forwarding, switching logs from JSON to plain text logging, and more. - [How to parse and analyze JSON logs](troubleshooting/log_parsing.md). +## Log Levels + +Each log message has an assigned log level that indicates its importance and verbosity. +Each logger has an assigned minimum log level. +A logger emits a log message only if its log level is equal to or above the minimum log level. + +The following log levels are supported: + +| Level | Name | +|:------|:----------| +| 0 | `DEBUG` | +| 1 | `INFO` | +| 2 | `WARN` | +| 3 | `ERROR` | +| 4 | `FATAL` | +| 5 | `UNKNOWN` | + +GitLab loggers emit all log messages because they are set to `DEBUG` by default. + +### Override default log level + +You can override the minimum log level for GitLab loggers using the `GITLAB_LOG_LEVEL` environment variable. +Valid values are either a value of `0` to `5`, or the name of the log level. + +Example: + +```shell +GITLAB_LOG_LEVEL=info +``` + +For some services, other log levels are in place that are not affected by this setting. +Some of these services have their own environment variables to override the log level. For example: + +| Service | Log level | Environment variable | +|:---------------------|:----------|:---------------------| +| GitLab API | `INFO` | | +| GitLab Cleanup | `INFO` | `DEBUG` | +| GitLab Doctor | `INFO` | `VERBOSE` | +| GitLab Export | `INFO` | `EXPORT_DEBUG` | +| GitLab Geo | `INFO` | | +| GitLab Import | `INFO` | `IMPORT_DEBUG` | +| GitLab QA Runtime | `ERROR` | `QA_DEBUG` | +| Google APIs | `INFO` | | +| Rack Timeout | `ERROR` | | +| Sidekiq (server) | `INFO` | | +| Snowplow Tracker | `FATAL` | | +| gRPC Client (Gitaly) | `WARN` | `GRPC_LOG_LEVEL` | + ## Log Rotation The logs for a given service may be managed and rotated by: @@ -36,26 +84,26 @@ are written to a file called `current`. The `logrotate` service built into GitLa [manages all logs](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate) except those captured by `runit`. -| Log type | Managed by logrotate | Managed by svlogd/runit | -|-------------------------------------------------|------------------------|-------------------------| -| [Alertmanager Logs](#alertmanager-logs) | **{dotted-circle}** No | **{check-circle}** Yes | -| [Crond Logs](#crond-logs) | **{dotted-circle}** No | **{check-circle}** Yes | -| [Gitaly](#gitaly-logs) | **{check-circle}** Yes | **{check-circle}** Yes | -| [GitLab Exporter for Omnibus](#gitlab-exporter) | **{dotted-circle}** No | **{check-circle}** Yes | -| [GitLab Pages Logs](#pages-logs) | **{check-circle}** Yes | **{check-circle}** Yes | -| GitLab Rails | **{check-circle}** Yes | **{dotted-circle}** No | -| [GitLab Shell Logs](#gitlab-shelllog) | **{check-circle}** Yes | **{dotted-circle}** No | -| [Grafana Logs](#grafana-logs) | **{dotted-circle}** No | **{check-circle}** Yes | -| [LogRotate Logs](#logrotate-logs) | **{dotted-circle}** No | **{check-circle}** Yes | -| [Mailroom](#mail_room_jsonlog-default) | **{check-circle}** Yes | **{check-circle}** Yes | -| [NGINX](#nginx-logs) | **{check-circle}** Yes | **{check-circle}** Yes | -| [PostgreSQL Logs](#postgresql-logs) | **{dotted-circle}** No | **{check-circle}** Yes | -| [Praefect Logs](#praefect-logs) | **{dotted-circle}** Yes| **{check-circle}** Yes | -| [Prometheus Logs](#prometheus-logs) | **{dotted-circle}** No | **{check-circle}** Yes | -| [Puma](#puma-logs) | **{check-circle}** Yes | **{check-circle}** Yes | -| [Redis Logs](#redis-logs) | **{dotted-circle}** No | **{check-circle}** Yes | -| [Registry Logs](#registry-logs) | **{dotted-circle}** No | **{check-circle}** Yes | -| [Workhorse Logs](#workhorse-logs) | **{check-circle}** Yes | **{check-circle}** Yes | +| Log type | Managed by logrotate | Managed by svlogd/runit | +|:------------------------------------------------|:------------------------|:------------------------| +| [Alertmanager Logs](#alertmanager-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Crond Logs](#crond-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Gitaly](#gitaly-logs) | **{check-circle}** Yes | **{check-circle}** Yes | +| [GitLab Exporter for Omnibus](#gitlab-exporter) | **{dotted-circle}** No | **{check-circle}** Yes | +| [GitLab Pages Logs](#pages-logs) | **{check-circle}** Yes | **{check-circle}** Yes | +| GitLab Rails | **{check-circle}** Yes | **{dotted-circle}** No | +| [GitLab Shell Logs](#gitlab-shelllog) | **{check-circle}** Yes | **{dotted-circle}** No | +| [Grafana Logs](#grafana-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [LogRotate Logs](#logrotate-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Mailroom](#mail_room_jsonlog-default) | **{check-circle}** Yes | **{check-circle}** Yes | +| [NGINX](#nginx-logs) | **{check-circle}** Yes | **{check-circle}** Yes | +| [PostgreSQL Logs](#postgresql-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Praefect Logs](#praefect-logs) | **{dotted-circle}** Yes | **{check-circle}** Yes | +| [Prometheus Logs](#prometheus-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Puma](#puma-logs) | **{check-circle}** Yes | **{check-circle}** Yes | +| [Redis Logs](#redis-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Registry Logs](#registry-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Workhorse Logs](#workhorse-logs) | **{check-circle}** Yes | **{check-circle}** Yes | ## `production_json.log` diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md index 2d17062e955..50c0f0ecc63 100644 --- a/doc/administration/maintenance_mode/index.md +++ b/doc/administration/maintenance_mode/index.md @@ -193,7 +193,8 @@ Replication and verification continues to work but proxied Git pushes to primary ### Secure features -Features that depend on creating issues or creating or approving Merge Requests, do not work. +Features that depend on creating issues or creating or approving merge requests, +do not work. Exporting a vulnerability list from a Vulnerability Report page does not work. diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index d6b9fa2b8d3..01576eb4abf 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -1,14 +1,11 @@ --- 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" -type: reference +info: To 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 diffs storage **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52568) in GitLab 11.8. - Merge request diffs are size-limited copies of diffs associated with merge requests. When viewing a merge request, diffs are sourced from these copies wherever possible as a performance optimization. @@ -17,7 +14,8 @@ By default, merge request diffs are stored in the database, in a table named `merge_request_diff_files`. Larger installations may find this table grows too large, in which case, switching to external storage is recommended. -Merge request diffs can be stored on disk, or in object storage. In general, it +Merge request diffs can be stored [on disk](#using-external-storage), or in +[object storage](#using-object-storage). In general, it is better to store the diffs in the database than on disk. A compromise is available that only [stores outdated diffs](#alternative-in-database-storage) outside of database. @@ -41,6 +39,7 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d ``` 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. + GitLab then migrates your existing merge request diffs to external storage. **In installations from source:** @@ -64,6 +63,7 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d ``` 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. + GitLab then migrates your existing merge request diffs to external storage. ## Using object storage @@ -84,6 +84,7 @@ be configured already. 1. Set [object storage settings](#object-storage-settings). 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. + GitLab then migrates your existing merge request diffs to external storage. **In installations from source:** @@ -97,6 +98,7 @@ be configured already. 1. Set [object storage settings](#object-storage-settings). 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. + GitLab then migrates your existing merge request diffs to external storage. [Read more about using object storage with GitLab](object_storage.md). diff --git a/doc/administration/monitoring/github_imports.md b/doc/administration/monitoring/github_imports.md index cd35b8b3f9e..e91483eb79d 100644 --- a/doc/administration/monitoring/github_imports.md +++ b/doc/administration/monitoring/github_imports.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Monitoring GitHub imports **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14731) in GitLab 10.2. - The GitHub importer exposes various Prometheus metrics that you can use to monitor the health and progress of the importer. diff --git a/doc/administration/monitoring/ip_whitelist.md b/doc/administration/monitoring/ip_whitelist.md index b6df176ea87..75b09f8a366 100644 --- a/doc/administration/monitoring/ip_whitelist.md +++ b/doc/administration/monitoring/ip_whitelist.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # IP whitelist **(FREE SELF)** -> Introduced in GitLab 9.4. - NOTE: We intend to [rename IP whitelist as `IP allowlist`](https://gitlab.com/groups/gitlab-org/-/epics/3478). diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 4a504b07a1b..c5b87afd94b 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -22,10 +22,8 @@ GitLab monitors its own internal service metrics, and makes them available at th `/-/metrics` endpoint. Unlike other [Prometheus](https://prometheus.io) exporters, to access the metrics, the client IP address must be [explicitly allowed](../ip_whitelist.md). -For [Omnibus GitLab](https://docs.gitlab.com/omnibus/) and Chart installations, -these metrics are enabled and collected as of -[GitLab 9.4](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1702). -For source installations, these metrics must be enabled +These metrics are enabled and collected for [Omnibus GitLab](https://docs.gitlab.com/omnibus/) +and Chart installations. For source installations, these metrics must be enabled manually and collected by a Prometheus server. For enabling and viewing metrics from Sidekiq nodes, see [Sidekiq metrics](#sidekiq-metrics). @@ -107,7 +105,7 @@ The following metrics are available: | `pipelines_created_total` | Counter | 9.4 | Counter of pipelines created | | | `rack_uncaught_errors_total` | Counter | 9.4 | Rack connections handling uncaught errors count | | | `user_session_logins_total` | Counter | 9.4 | Counter of how many users have logged in since GitLab was started or restarted | | -| `upload_file_does_not_exist` | Counter | 10.7 | Number of times an upload record could not find its file. Made available in all tiers in GitLab 11.5. | | +| `upload_file_does_not_exist` | Counter | 10.7 | Number of times an upload record could not find its file. | | | `failed_login_captcha_total` | Gauge | 11.0 | Counter of failed CAPTCHA attempts during login | | | `successful_login_captcha_total` | Gauge | 11.0 | Counter of successful CAPTCHA attempts during login | | | `auto_devops_pipelines_completed_total` | Counter | 12.7 | Counter of completed Auto DevOps pipelines, labeled by status | | @@ -288,7 +286,7 @@ configuration option in `gitlab.yml`. These metrics are served from the | `geo_uploads_verified` | Gauge | 14.6 | Number of uploads verified on secondary | `url` | | `geo_uploads_verification_failed` | Gauge | 14.6 | Number of uploads verifications failed on secondary | `url` | | `gitlab_sli:rails_request_apdex:total` | Counter | 14.4 | The number of request-apdex measurements, [more information the development documentation](../../../development/application_slis/rails_request_apdex.md) | `endpoint_id`, `feature_category`, `request_urgency` | -| `gitlab_sli:rails_request_apdex:success_total` | Counter | 14.4 | The number of succesful requests that met the target duration for their urgency. Devide by `gitlab_sli:rails_requests_apdex:total` to get a success ratio | `endpoint_id`, `feature_category`, `request_urgency` | +| `gitlab_sli:rails_request_apdex:success_total` | Counter | 14.4 | The number of successful requests that met the target duration for their urgency. Divide by `gitlab_sli:rails_requests_apdex:total` to get a success ratio | `endpoint_id`, `feature_category`, `request_urgency` | ## Database load balancing metrics **(PREMIUM SELF)** diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 3268c0fc14c..acdcdb41dca 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -1,6 +1,6 @@ --- -stage: Monitor -group: Monitor +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 --- @@ -59,8 +59,8 @@ 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 server. Proceed at your own risk. -To access Prometheus from outside the GitLab server, set an FQDN or IP in -`prometheus['listen_address']`. To change the address/port that Prometheus +To access Prometheus from outside the GitLab server, +change the address/port that Prometheus listens on: 1. Edit `/etc/gitlab/gitlab.rb` diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md index d42c471ac71..aba1561500a 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # PgBouncer exporter **(FREE SELF)** -> Introduced in [Omnibus GitLab 11.0](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2493). - The [PgBouncer exporter](https://github.com/prometheus-community/pgbouncer_exporter) enables you to measure various [PgBouncer](https://www.pgbouncer.org/) metrics. diff --git a/doc/administration/monitoring/prometheus/registry_exporter.md b/doc/administration/monitoring/prometheus/registry_exporter.md index 87b51aaed08..3a2acd47338 100644 --- a/doc/administration/monitoring/prometheus/registry_exporter.md +++ b/doc/administration/monitoring/prometheus/registry_exporter.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Registry exporter **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/2884) in GitLab 11.9. - The Registry exporter allows you to measure various Registry metrics. To enable it: diff --git a/doc/administration/nfs.md b/doc/administration/nfs.md index a0170e6c4ef..87a10a0ec04 100644 --- a/doc/administration/nfs.md +++ b/doc/administration/nfs.md @@ -12,6 +12,8 @@ recommended for performance reasons. For data objects such as LFS, Uploads, Artifacts, and so on, an [Object Storage service](object_storage.md) is recommended over NFS where possible, due to better performance. +When eliminating the usage of NFS, there are [additional steps you need to take](object_storage.md#other-alternatives-to-file-system-storage) +in addition to moving to Object Storage. File system performance can impact overall GitLab performance, especially for actions that read or write to Git repositories. For steps you can use to test diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index c6490e365a5..0976fc3684e 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -48,6 +48,9 @@ There are two ways of specifying object storage configuration in GitLab: For more information on the differences and to transition from one form to another, see [Transition to consolidated form](#transition-to-consolidated-form). +If you are currently storing data locally, see +[Migrate to object storage](#migrate-to-object-storage) for migration details. + ### Consolidated object storage configuration > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4368) in GitLab 13.2. @@ -485,9 +488,9 @@ This is the list of valid `objects` that can be used: | `uploads` | [User uploads](uploads.md) | | `lfs` | [Git Large File Storage objects](lfs/index.md) | | `packages` | [Project packages (for example, PyPI, Maven, or NuGet)](packages/index.md) | -| `dependency_proxy` | [GitLab Dependency Proxy](packages/dependency_proxy.md) | +| `dependency_proxy` | [Dependency Proxy](packages/dependency_proxy.md) | | `terraform_state` | [Terraform state files](terraform_state.md) | -| `pages` | [GitLab Pages](pages/index.md) | +| `pages` | [Pages](pages/index.md) | Within each object type, three parameters can be defined: @@ -514,6 +517,19 @@ no bucket is needed if CI artifacts are disabled with this setting: gitlab_rails['artifacts_enabled'] = false ``` +### Migrate to object storage + +To migrate existing local data to object storage see the following guides: + +- [Job artifacts](job_artifacts.md#migrating-to-object-storage) including archived job logs +- [LFS objects](lfs/index.md#migrating-to-object-storage) +- [Uploads](raketasks/uploads/migrate.md#migrate-to-object-storage) +- [Merge request diffs](merge_request_diffs.md#using-object-storage) +- [Packages](packages/index.md#migrating-local-packages-to-object-storage) (optional feature) +- Dependency Proxy - [migration not yet supported](https://gitlab.com/gitlab-org/gitlab/-/issues/343064) +- [Terraform state files](terraform_state.md#migrate-to-object-storage) +- [Pages content](pages/index.md#migrate-pages-deployments-to-object-storage) + ### Transition to consolidated form Prior to GitLab 13.2: @@ -565,11 +581,11 @@ supported by consolidated configuration form, refer to the following guides: | [Merge request diffs](merge_request_diffs.md#using-object-storage) | **{check-circle}** Yes | | [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| **{dotted-circle}** No | | [Packages](packages/index.md#using-object-storage) (optional feature) | **{check-circle}** Yes | -| [Dependency Proxy](packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM SELF)** | **{check-circle}** Yes | +| [Dependency Proxy](packages/dependency_proxy.md#using-object-storage) (optional feature) | **{check-circle}** Yes | | [Pseudonymizer](pseudonymizer.md) (optional feature) | **{dotted-circle}** No | | [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | **{dotted-circle}** No | | [Terraform state files](terraform_state.md#using-object-storage) | **{check-circle}** Yes | -| [GitLab Pages content](pages/index.md#using-object-storage) | **{check-circle}** Yes | +| [Pages content](pages/index.md#using-object-storage) | **{check-circle}** Yes | ### Other alternatives to file system storage @@ -585,6 +601,12 @@ See the following additional guides: ## Warnings, limitations, and known issues +### Objects are not included in GitLab backups + +As noted in [our backup documentation](../raketasks/backup_restore.md), +objects are not included in GitLab backups. You can enable backups with +your object storage provider instead. + ### Use separate buckets Using separate buckets for each data type is the recommended approach for GitLab. diff --git a/doc/administration/operations/cleaning_up_redis_sessions.md b/doc/administration/operations/cleaning_up_redis_sessions.md deleted file mode 100644 index ed5014b65e1..00000000000 --- a/doc/administration/operations/cleaning_up_redis_sessions.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2021-12-10' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after 2021-12-10. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index c99f94589d7..ddedb3fe76a 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -27,13 +27,13 @@ lookup of authorized SSH keys. WARNING: OpenSSH version 6.9+ is required because `AuthorizedKeysCommand` must be -able to accept a fingerprint. Check the version of OpenSSH on your server. +able to accept a fingerprint. Check the version of OpenSSH on your server with `sshd -V`. ## Fast lookup is required for Geo **(PREMIUM)** By default, GitLab manages an `authorized_keys` file that is located in the `git` user's home directory. For most installations, this will be located under -`/var/opt/gitlab/.ssh/authorized_keys`, but you can use the following command to locate the `authorized_keys` on your system.: +`/var/opt/gitlab/.ssh/authorized_keys`, but you can use the following command to locate the `authorized_keys` on your system: ```shell getent passwd git | cut -d: -f6 | awk '{print $1"/.ssh/authorized_keys"}' @@ -77,9 +77,13 @@ sudo service sshd reload ``` Confirm that SSH is working by commenting out your user's key in the `authorized_keys` -file (start the line with a `#` to comment it), and attempting to pull a repository. +file (start the line with a `#` to comment it), and from your local machine, attempt to pull a repository or run: -A successful pull would mean that GitLab was able to find the key in the database, +```shell +ssh -T git@gitlab.example.com +``` + +A successful pull or [welcome message](../../ssh/index.md#verify-that-you-can-connect) would mean that GitLab was able to find the key in the database, since it is not present in the file anymore. NOTE: @@ -114,7 +118,7 @@ adding a new one, and attempting to pull a repository. Then you can backup and delete your `authorized_keys` file for best performance. The current users' keys are already present in the database, so there is no need for migration -or for asking users to re-add their keys. +or for users to re-add their keys. ## How to go back to using the `authorized_keys` file diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 84e6dca1f2b..f0eb5792a96 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -184,8 +184,8 @@ Each of the approaches we list can or does overwrite data in the target director ### Recommended approach in all cases -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 +For either Gitaly or Gitaly Cluster targets, 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`. - From GitLab 13.3, backup performance can be improved by @@ -193,13 +193,15 @@ can result from directly accessing and copying Gitaly's files using tools like ` - Backups can be created of just the repositories using the [skip feature](../../raketasks/backup_restore.md#excluding-specific-directories-from-the-backup). +No other method works for Gitaly Cluster targets. + ### Target directory is empty: use a `tar` pipe -If the target directory `/mnt/gitlab/repositories` is empty the -simplest thing to do is to use a `tar` pipe. This method has low -overhead and `tar` is almost always already installed on your system. -However, it is not possible to resume an interrupted `tar` pipe: if -that happens then all data must be copied again. +For Gitaly targets (use [recommended approach](#recommended-approach-in-all-cases) for Gitaly Cluster targets), if the +target directory `/mnt/gitlab/repositories` is empty the simplest thing to do is to use a `tar` pipe. This method has +low overhead and `tar` is almost always already installed on your system. + +However, it is not possible to resume an interrupted `tar` pipe; if that happens then all data must be copied again. ```shell sudo -u git sh -c 'tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ @@ -210,9 +212,9 @@ If you want to see progress, replace `-xf` with `-xvf`. #### `tar` pipe to another server -You can also use a `tar` pipe to copy data to another server. If your -`git` user has SSH access to the new server as `git@newserver`, you -can pipe the data through SSH. +For Gitaly targets (use [recommended approach](#recommended-approach-in-all-cases) for Gitaly Cluster targets), you can +also use a `tar` pipe to copy data to another server. If your `git` user has SSH access to the new server as +`git@newserver`, you can pipe the data through SSH. ```shell sudo -u git sh -c 'tar -C /var/opt/gitlab/git-data/repositories -cf - -- . |\ @@ -228,11 +230,11 @@ WARNING: Using `rsync` to migrate Git data can cause data loss and repository corruption. [These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). -If the target directory already contains a partial / outdated copy -of the repositories it may be wasteful to copy all the data again -with `tar`. In this scenario it is better to use `rsync`. This utility -is either already installed on your system, or installable -by using `apt` or `yum`. +If the target directory already contains a partial or outdated copy of the repositories it may be wasteful to copy all +the data again with `tar`. In this scenario it is better to use `rsync` for Gitaly targets (use +[recommended approach](#recommended-approach-in-all-cases) for Gitaly Cluster targets). + +This utility is either already installed on your system, or installable using `apt` or `yum`. ```shell sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ @@ -249,8 +251,9 @@ WARNING: Using `rsync` to migrate Git data can cause data loss and repository corruption. [These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422). -If the `git` user on your source system has SSH access to the target -server you can send the repositories over the network with `rsync`. +For Gitaly targets (use [recommended approach](#recommended-approach-in-all-cases) for Gitaly Cluster targets), if the +`git` user on your source system has SSH access to the target server you can send the repositories over the network with +`rsync`. ```shell sudo -u git sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \ @@ -269,17 +272,18 @@ Every time you start an `rsync` job it must: - Inspect all files in the target directory. - Decide whether or not to copy files. -If the source or target directory -has many contents, this startup phase of `rsync` can become a burden -for your GitLab server. You can reduce the workload of `rsync` by dividing its -work in smaller pieces, and sync one repository at a time. +If the source or target directory has many contents, this startup phase of `rsync` can become a burden for your GitLab +server. You can reduce the workload of `rsync` by dividing its work into smaller pieces, and sync one repository at a +time. In addition to `rsync` we use [GNU Parallel](http://www.gnu.org/software/parallel/). This utility is not included in GitLab, so you must install it yourself with `apt` or `yum`. -This process does not clean up repositories at the target location that no -longer exist at the source. +This process: + +- Doesn't clean up repositories at the target location that no longer exist at the source. +- Only works for Gitaly targets. Use [recommended approach](#recommended-approach-in-all-cases) for Gitaly Cluster targets. #### Parallel `rsync` for all repositories known to GitLab diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md index 8c366e311b8..a93365c08b2 100644 --- a/doc/administration/operations/rails_console.md +++ b/doc/administration/operations/rails_console.md @@ -35,7 +35,7 @@ sudo -u git -H bundle exec rails console -e production **For Kubernetes deployments** -The console is in the task-runner pod. Refer to our [Kubernetes cheat sheet](../troubleshooting/kubernetes_cheat_sheet.md#gitlab-specific-kubernetes-information) for details. +The console is in the toolbox pod. Refer to our [Kubernetes cheat sheet](../troubleshooting/kubernetes_cheat_sheet.md#gitlab-specific-kubernetes-information) for details. To exit the console, type: `quit`. diff --git a/doc/administration/package_information/defaults.md b/doc/administration/package_information/defaults.md index 95d6135c28c..54e68392aa5 100644 --- a/doc/administration/package_information/defaults.md +++ b/doc/administration/package_information/defaults.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 --- # Package defaults **(FREE SELF)** @@ -14,42 +14,43 @@ the package will assume the defaults as noted below. See the table below for the list of ports that the Omnibus GitLab assigns by default: -| Component | On by default | Communicates via | Alternative | Connection port | -|:-------------------:|:-------------:|:----------------:|:-----------:|:------------------------------------------:| -| GitLab Rails | Yes | Port | X | 80 or 443 | -| GitLab Shell | Yes | Port | X | 22 | -| PostgreSQL | Yes | Socket | Port (5432) | X | -| Redis | Yes | Socket | Port (6379) | X | -| Puma | Yes | Socket | Port (8080) | X | -| GitLab Workhorse | Yes | Socket | Port (8181) | X | -| NGINX status | Yes | Port | X | 8060 | -| Prometheus | Yes | Port | X | 9090 | -| Node exporter | Yes | Port | X | 9100 | -| Redis exporter | Yes | Port | X | 9121 | -| PostgreSQL exporter | Yes | Port | X | 9187 | -| PgBouncer exporter | No | Port | X | 9188 | -| GitLab Exporter | Yes | Port | X | 9168 | -| Sidekiq exporter | Yes | Port | X | 8082 | -| Puma exporter | No | Port | X | 8083 | -| Geo PostgreSQL | No | Socket | Port (5431) | X | -| Redis Sentinel | No | Port | X | 26379 | -| Incoming email | No | Port | X | 143 | -| Elastic search | No | Port | X | 9200 | -| GitLab Pages | No | Port | X | 80 or 443 | -| GitLab Registry | No* | Port | X | 80, 443 or 5050 | -| GitLab Registry | No | Port | X | 5000 | -| LDAP | No | Port | X | Depends on the component configuration | -| Kerberos | No | Port | X | 8443 or 8088 | -| OmniAuth | Yes | Port | X | Depends on the component configuration | -| SMTP | No | Port | X | 465 | -| Remote syslog | No | Port | X | 514 | -| Mattermost | No | Port | X | 8065 | -| Mattermost | No | Port | X | 80 or 443 | -| PgBouncer | No | Port | X | 6432 | -| Consul | No | Port | X | 8300, 8301(UDP), 8500, 8600[^Consul-notes] | -| Patroni | No | Port | X | 8008 | -| GitLab KAS | No | Port | X | 8150 | -| Gitaly | No | Port | X | 8075 | +| Component | On by default | Communicates via | Alternative | Connection port | +|:--------------------:|:-------------:|:----------------:|:-----------:|:------------------------------------------:| +| GitLab Rails | Yes | Port | X | 80 or 443 | +| GitLab Shell | Yes | Port | X | 22 | +| PostgreSQL | Yes | Socket | Port (5432) | X | +| Redis | Yes | Socket | Port (6379) | X | +| Puma | Yes | Socket | Port (8080) | X | +| GitLab Workhorse | Yes | Socket | Port (8181) | X | +| NGINX status | Yes | Port | X | 8060 | +| Prometheus | Yes | Port | X | 9090 | +| Node exporter | Yes | Port | X | 9100 | +| Redis exporter | Yes | Port | X | 9121 | +| PostgreSQL exporter | Yes | Port | X | 9187 | +| PgBouncer exporter | No | Port | X | 9188 | +| GitLab Exporter | Yes | Port | X | 9168 | +| Sidekiq exporter | Yes | Port | X | 8082 | +| Sidekiq health check | No | Port | X | 8092[^Sidekiq-health] | +| Puma exporter | No | Port | X | 8083 | +| Geo PostgreSQL | No | Socket | Port (5431) | X | +| Redis Sentinel | No | Port | X | 26379 | +| Incoming email | No | Port | X | 143 | +| Elastic search | No | Port | X | 9200 | +| GitLab Pages | No | Port | X | 80 or 443 | +| GitLab Registry | No* | Port | X | 80, 443 or 5050 | +| GitLab Registry | No | Port | X | 5000 | +| LDAP | No | Port | X | Depends on the component configuration | +| Kerberos | No | Port | X | 8443 or 8088 | +| OmniAuth | Yes | Port | X | Depends on the component configuration | +| SMTP | No | Port | X | 465 | +| Remote syslog | No | Port | X | 514 | +| Mattermost | No | Port | X | 8065 | +| Mattermost | No | Port | X | 80 or 443 | +| PgBouncer | No | Port | X | 6432 | +| Consul | No | Port | X | 8300, 8301(UDP), 8500, 8600[^Consul-notes] | +| Patroni | No | Port | X | 8008 | +| GitLab KAS | No | Port | X | 8150 | +| Gitaly | No | Port | X | 8075 | Legend: @@ -70,3 +71,5 @@ NOTE: In some cases, the GitLab Registry will be automatically enabled by default. Please see [our documentation](../packages/container_registry.md) for more details [^Consul-notes]: If using additional Consul functionality, more ports may need to be opened. See the [official documentation](https://www.consul.io/docs/install/ports#ports-table) for the list. + + [^Sidekiq-health]: If Sidekiq health check settings are not set, they will default to the Sidekiq metrics exporter settings. This default is deprecated and is set to be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/347509). diff --git a/doc/administration/package_information/deprecation_policy.md b/doc/administration/package_information/deprecation_policy.md index 905de387dcb..7298bce6c95 100644 --- a/doc/administration/package_information/deprecation_policy.md +++ b/doc/administration/package_information/deprecation_policy.md @@ -38,7 +38,7 @@ We can differentiate two different types of configuration: - Sensitive: Configuration that can cause major service outage (like data integrity, installation integrity, or preventing users from reaching the installation) - Regular: Configuration that can make a feature unavailable but still makes the - installation useable (like a change in default project/group settings, or + installation usable (like a change in default project/group settings, or miscommunication with other components) We also need to differentiate deprecation and removal procedure. diff --git a/doc/administration/package_information/index.md b/doc/administration/package_information/index.md index ab4b1edfa30..2781f789409 100644 --- a/doc/administration/package_information/index.md +++ b/doc/administration/package_information/index.md @@ -76,7 +76,7 @@ characters on each line. ## Init system detection -Omnibus GitLab attempts to query the underlaying system in order to +Omnibus GitLab attempts to query the underlying system in order to check which init system it uses. This manifests itself as a `WARNING` during the `sudo gitlab-ctl reconfigure` run. diff --git a/doc/administration/package_information/postgresql_versions.md b/doc/administration/package_information/postgresql_versions.md index 252e0cad76d..97a35fb29ed 100644 --- a/doc/administration/package_information/postgresql_versions.md +++ b/doc/administration/package_information/postgresql_versions.md @@ -26,7 +26,7 @@ Read more about update policies and warnings in the PostgreSQL | GitLab version | PostgreSQL versions | Default version for fresh installs | Default version for upgrades | Notes | | -------------- | --------------------- | ---------------------------------- | ---------------------------- | ----- | -| 14.1 | 12.6, 13.3 | 12.6 | 12.6 | PostgreSQL 13 available for fresh installations if not using Geo or High Availability. | +| 14.1 | 12.6, 13.3 | 12.6 | 12.6 | PostgreSQL 13 available for fresh installations if not using [Geo](../geo/index.md#requirements-for-running-geo) or [Patroni](../postgresql/index.md#postgresql-replication-and-failover-with-omnibus-gitlab). | 14.0 | 12.6 | 12.6 | 12.6 | HA installations with repmgr are no longer supported and will be prevented from upgrading to Omnibus GitLab 14.0 | | 13.8 | 11.9, 12.4 | 12.4 | 12.4 | Package upgrades automatically performed PostgreSQL upgrade for nodes that are not part of a Geo or HA cluster.). | | 13.7 | 11.9, 12.4 | 12.4 | 11.9 | For upgrades users can manually upgrade to 12.4 following the [upgrade docs](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-133-and-later). | diff --git a/doc/administration/package_information/supported_os.md b/doc/administration/package_information/supported_os.md index fcc2fef3e63..78f496a3998 100644 --- a/doc/administration/package_information/supported_os.md +++ b/doc/administration/package_information/supported_os.md @@ -17,6 +17,7 @@ The following lists the currently supported OSs and their possible EOL dates. | OS Version | First supported GitLab version | Arch | OS EOL | Details | | ---------------- | ------------------------------ | --------------- | ------------- | ------------------------------------------------------------ | +| AlmaLinux 8 | GitLab CE / GitLab EE 14.5.0 | x86_64, aarch64 | 2029 | <https://almalinux.org/> | | CentOS 7 | GitLab CE / GitLab EE 7.10.0 | x86_64 | June 2024 | <https://wiki.centos.org/About/Product> | | CentOS 8 | GitLab CE / GitLab EE 12.8.1 | x86_64, aarch64 | Dec 2021 | <https://wiki.centos.org/About/Product> | | Debian 9 | GitLab CE / GitLab EE 9.3.0 | amd64 | 2022 | <https://wiki.debian.org/LTS> | diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index 0877fe510de..43293385ed9 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -694,7 +694,7 @@ project, you can [disable it from your project's settings](../../user/project/se ## Use an external container registry with GitLab as an auth endpoint If you use an external container registry, some features associated with the -container registry may be unavailable or have [inherent risks](../../user/packages/container_registry/index.md#use-with-external-container-registries). +container registry may be unavailable or have [inherent risks](../../user/packages/container_registry/reduce_container_registry_storage.md#use-with-external-container-registries). For the integration to work, the external registry must be configured to use a JSON Web Token to authenticate with GitLab. The @@ -883,7 +883,7 @@ project.container_repositories.find_each do |repo| end ``` -You can also [run cleanup on a schedule](../../user/packages/container_registry/index.md#cleanup-policy). +You can also [run cleanup on a schedule](../../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy). ## Container Registry garbage collection @@ -965,8 +965,6 @@ understand the implications. ### Removing untagged manifests and unreferenced layers -> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3097) in Omnibus GitLab 11.10. - WARNING: This is a destructive operation. @@ -1341,7 +1339,10 @@ Start with a value between `25000000` (25MB) and `50000000` (50MB). ### Supporting older Docker clients -As of GitLab 11.9, we began shipping version 2.7.1 of the Docker container registry, which disables the schema1 manifest by default. If you are still using older Docker clients (1.9 or older), you may experience an error pushing images. See [omnibus-4145](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4145) for more details. +The Docker container registry shipped with GitLab disables the schema1 manifest +by default. If you are still using older Docker clients (1.9 or older), you may +experience an error pushing images. See +[omnibus-4145](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4145) for more details. You can add a configuration option for backwards compatibility. diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index a394a32fc18..b3dc6ffc2b2 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -14,68 +14,84 @@ GitLab can be used as a dependency proxy for a variety of common package manager This is the administration documentation. If you want to learn how to use the dependency proxies, see the [user guide](../../user/packages/dependency_proxy/index.md). -## Enabling the Dependency Proxy feature +The GitLab Dependency Proxy: -NOTE: -Dependency proxy requires the Puma web server to be enabled. +- Is turned on by default. +- Can be turned off by an administrator. +- Requires the [Puma web server](../operations/puma.md) + to be enabled. Puma is enabled by default in GitLab 13.0 and later. -To enable the dependency proxy feature: +## Turn off the Dependency Proxy -**Omnibus GitLab installations** +The Dependency Proxy is enabled by default. If you are an administrator, you +can turn off the Dependency Proxy. To turn off the Dependency Proxy, follow the instructions that +correspond to your GitLab installation: + +- [Omnibus GitLab installations](#omnibus-gitlab-installations) +- [Helm chart installations](#helm-chart-installations) +- [Installations from source](#installations-from-source) + +### Omnibus GitLab installations 1. Edit `/etc/gitlab/gitlab.rb` and add the following line: ```ruby - gitlab_rails['dependency_proxy_enabled'] = true + gitlab_rails['dependency_proxy_enabled'] = false ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -1. Enable the [Puma web server](../operations/puma.md). +1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) + for the changes to take effect. -**Helm chart installations** +### Helm chart installations -1. After the installation is complete, update the global `appConfig` to enable the feature: +After the installation is complete, update the global `appConfig` to turn off the Dependency Proxy: - ```yaml - global: - appConfig: - dependencyProxy: - enabled: true - bucket: gitlab-dependency-proxy - connection: {} - secret: - key: - ``` +```yaml +global: + appConfig: + dependencyProxy: + enabled: false + bucket: gitlab-dependency-proxy + connection: {} + secret: + key: +``` For more information, see [Configure Charts using Globals](https://docs.gitlab.com/charts/charts/globals.html#configure-appconfig-settings). -**Installations from source** +### Installations from source -1. After the installation is complete, configure the `dependency_proxy` - section in `config/gitlab.yml`. Set to `true` to enable it: +1. After the installation is complete, configure the `dependency_proxy` section in + `config/gitlab.yml`. Set `enabled` to `false` to turn off the Dependency Proxy: ```yaml dependency_proxy: - enabled: true + enabled: false ``` -1. [Restart GitLab](../restart_gitlab.md#installations-from-source "How to restart GitLab") for the changes to take effect. +1. [Restart GitLab](../restart_gitlab.md#installations-from-source "How to restart GitLab") + for the changes to take effect. + +### Multi-node GitLab installations -Since Puma is already the default web server for installations from source as of GitLab 12.9, -no further changes are needed. +Follow the steps for [Omnibus GitLab installations](#omnibus-gitlab-installations) +for each Web and Sidekiq node. -**Multi-node GitLab installations** +## Turn on the Dependency Proxy -Follow the steps for **Omnibus GitLab installation** for each Web and Sidekiq nodes. +The Dependency Proxy is turned on by default, but can be turned off by an +administrator. To turn on the Dependency Proxy, follow the instructions in +[Turn off the Dependency Proxy](#turn-off-the-dependency-proxy), +but set the `enabled` fields to `true`. ## Changing the storage path -By default, the dependency proxy files are stored locally, but you can change the default +By default, the Dependency Proxy files are stored locally, but you can change the default local location or even use object storage. ### Changing the local storage path -The dependency proxy files for Omnibus GitLab installations are stored under +The Dependency Proxy files for Omnibus GitLab installations are stored under `/var/opt/gitlab/gitlab-rails/shared/dependency_proxy/` and for source installations under `shared/dependency_proxy/` (relative to the Git home directory). To change the local storage path: @@ -105,7 +121,7 @@ To change the local storage path: ### Using object storage Instead of relying on the local storage, you can use an object storage to -store the blobs of the dependency proxy. +store the blobs of the Dependency Proxy. [Read more about using object storage with GitLab](../object_storage.md). @@ -199,5 +215,3 @@ 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/pages/index.md b/doc/administration/pages/index.md index f3ad474771c..53510688794 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -192,6 +192,33 @@ to use the HTTPS protocol. WARNING: Multiple wildcards for one instance is not supported. Only one wildcard per instance can be assigned. +### Wildcard domains with TLS-terminating Load Balancer + +**Requirements:** + +- [Wildcard DNS setup](#dns-configuration) +- [TLS-terminating load balancer](../../install/aws/manual_install_aws.md#load-balancer) + +--- + +URL scheme: `https://<namespace>.example.io/<project_slug>` + +This setup is primarily intended to be used when [installing a GitLab POC on Amazon Web Services](../../install/aws/manual_install_aws.md). This includes a TLS-terminating [classic load balancer](../../install/aws/manual_install_aws.md#load-balancer) that listens for HTTPS connections, manages TLS certificates, and forwards HTTP traffic to the instance. + +1. In `/etc/gitlab/gitlab.rb` specify the following configuration: + + ```ruby + external_url "https://gitlab.example.com" # external_url here is only for reference + pages_external_url "https://pages.example.com" # not a subdomain of external_url + + pages_nginx['enable'] = true + pages_nginx['listen_port'] = 80 + pages_nginx['listen_https'] = false + pages_nginx['redirect_http_to_https'] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + ### Global settings Below is a table of all configuration settings known to Pages in Omnibus GitLab, @@ -262,6 +289,8 @@ control over how the Pages daemon runs and serves content in your environment. | `use_legacy_storage` | Temporarily-introduced parameter allowing to use legacy domain configuration source and storage. [Removed in 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166). | | `rate_limit_source_ip` | Rate limit per source IP in number of requests per second. Set to `0` to disable this feature. | | `rate_limit_source_ip_burst` | Rate limit per source IP maximum burst allowed per second. | +| `rate_limit_domain` | Rate limit per domain in number of requests per second. Set to `0` to disable this feature. | +| `rate_limit_domain_burst` | Rate limit per domain maximum burst allowed per second. | ## Advanced configuration @@ -518,6 +547,14 @@ After an archive reaches `zip_cache_expiration`, it's marked as expired and remo  +### HTTP Strict Transport Security (HSTS) support + +HTTP Strict Transport Security (HSTS) can be enabled through the `gitlab_pages['headers']` configuration option. HSTS informs browsers that the website they are visiting should always provide its content over HTTPS to ensure that attackers cannot force subsequent connections to happen unencrypted. It can also improve loading speed of pages as it prevents browsers from attempting to connect over an unencrypted HTTP channel before being redirected to HTTPS. + +```ruby +gitlab_pages['headers'] = ['Strict-Transport-Security: max-age=63072000'] +``` + ## Activate verbose logging for daemon Follow the steps below to configure verbose logging of GitLab Pages daemon. @@ -695,6 +732,9 @@ database encryption. Proceed with caution. pages_external_url "http://<pages_server_URL>" gitlab_pages['gitlab_server'] = 'http://<gitlab_server_IP_or_URL>' + + ## If access control was enabled on step 3 + gitlab_pages['access_control'] = true ``` 1. If you have custom UID/GID settings on the **GitLab server**, add them to the **Pages server** `/etc/gitlab/gitlab.rb` as well, @@ -717,7 +757,7 @@ database encryption. Proceed with caution. mv /var/opt/gitlab/gitlab-rails/shared/pages/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json ``` -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Reconfigure the **Pages server**](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. 1. On the **GitLab server**, make the following changes to `/etc/gitlab/gitlab.rb`: @@ -727,7 +767,7 @@ database encryption. Proceed with caution. pages_nginx['enable'] = false ``` -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. [Reconfigure the **GitLab server**](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. It's possible to run GitLab Pages on multiple servers if you wish to distribute the load. You can do this through standard load balancing practices such as @@ -925,7 +965,7 @@ However, some projects may fail to be migrated for different reasons. To verify that all projects have been migrated successfully, you can manually run the migration: ```shell -gitlab-rake gitlab:pages:migrate_legacy_storage +sudo gitlab-rake gitlab:pages:migrate_legacy_storage ``` It's safe to interrupt this task and run it multiple times. @@ -1039,15 +1079,22 @@ than GitLab to prevent XSS attacks. > [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/631) in GitLab 14.5. -You can enforce source-IP rate limits to help minimize the risk of a Denial of Service (DoS) attack. GitLab Pages +You can enforce rate limits to help minimize the risk of a Denial of Service (DoS) attack. GitLab Pages uses a [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) to enforce rate limiting. By default, requests that exceed the specified limits are reported but not rejected. -Source-IP rate limits are enforced using the following: +GitLab Pages supports the following types of rate limiting: + +- Per `source_ip`. It limits how many requests are allowed from the single client IP address. +- Per `domain`. It limits how many requests are allowed per domain hosted on GitLab Pages. It can be a custom domain like `example.com`, or group domain like `group.gitlab.io`. -- `rate_limit_source_ip`: Set the maximum threshold in number of requests per second. Set to 0 to disable this feature. -- `rate_limit_source_ip_burst`: Sets the maximum threshold of number of requests allowed in an initial outburst of requests. +Rate limits are enforced using the following: + +- `rate_limit_source_ip`: Set the maximum threshold in number of requests per client IP per second. Set to 0 to disable this feature. +- `rate_limit_source_ip_burst`: Sets the maximum threshold of number of requests allowed in an initial outburst of requests per client IP. For example, when you load a web page that loads a number of resources at the same time. +- `rate_limit_domain_ip`: Set the maximum threshold in number of requests per hosted pages domain per second. Set to 0 to disable this feature. +- `rate_limit_domain_burst`: Sets the maximum threshold of number of requests allowed in an initial outburst of requests per hosted pages domain. #### Enable source-IP rate limits @@ -1067,6 +1114,24 @@ Source-IP rate limits are enforced using the following: 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +#### Enable domain rate limits + +1. Set rate limits in `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['rate_limit_domain'] = 1000 + gitlab_pages['rate_limit_domain_burst'] = 5000 + ``` + +1. To reject requests that exceed the specified limits, enable the `FF_ENFORCE_DOMAIN_RATE_LIMITS` feature flag in + `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['env'] = {'FF_ENFORCE_DOMAIN_RATE_LIMITS' => 'true'} + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues @@ -1282,6 +1347,15 @@ This can happen if your `gitlab-secrets.json` file is out of date between GitLab Pages. Follow steps 8-10 of [Running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), in all of your GitLab Pages instances. +### Intermittent 502 errors when using an AWS Network Load Balancer and GitLab Pages is running on multiple application servers + +Connections will time out when using a Network Load Balancer with client IP preservation enabled and [the request is looped back to the source server](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-troubleshooting.html#loopback-timeout). +This can happen to GitLab instances with multiple servers +running both the core GitLab application and GitLab Pages. + +AWS [recommends using an IP target type](https://aws.amazon.com/premiumsupport/knowledge-center/target-connection-fails-load-balancer/) +to resolve this issue. + ### 500 error with `securecookie: failed to generate random iv` and `Failed to save the session` This problem most likely results from an [out-dated operating system](../package_information/supported_os.md#os-versions-that-are-no-longer-supported). @@ -1332,8 +1406,11 @@ Once added, reconfigure with `sudo gitlab-ctl reconfigure` and restart GitLab wi ### `The redirect URI included is not valid.` when using Pages Access Control -Verify that the **Callback URL**/Redirect URI in the GitLab Pages [System OAuth application](../../integration/oauth_provider.md#instance-wide-applications) +You may see this error if `pages_external_url` was updated at some point of time. Verify the following: + +1. The **Callback URL**/Redirect URI in the GitLab Pages [System OAuth application](../../integration/oauth_provider.md#instance-wide-applications) is using the protocol (HTTP or HTTPS) that `pages_external_url` is configured to use. +1. The domain and path components of `Redirect URI` are valid: they should look like `projects.<pages_external_url>/auth`. ### 500 error `cannot serve from disk` diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 45e9dadd1cf..c4b1756d8a1 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -35,16 +35,17 @@ In the case of [custom domains](#custom-domains) (but not ports `80` and/or `443`. For that reason, there is some flexibility in the way which you can set it up: -1. Run the Pages daemon in the same server as GitLab, listening on a secondary IP. -1. Run the Pages daemon in a separate server. In that case, the - [Pages path](#change-storage-path) must also be present in the server that - the Pages daemon is installed, so you must share it through the network. -1. Run the Pages daemon in the same server as GitLab, listening on the same IP - but on different ports. In that case, you must proxy the traffic with - a load balancer. If you choose that route, you should use TCP load - balancing for HTTPS. If you use TLS-termination (HTTPS-load balancing), the - pages aren't able to be served with user-provided certificates. For - HTTP, it's OK to use HTTP or TCP load balancing. +- Run the Pages daemon in the same server as GitLab, listening on a secondary + IP. +- Run the Pages daemon in a separate server. In that case, the + [Pages path](#change-storage-path) must also be present in the server that + the Pages daemon is installed, so you must share it through the network. +- Run the Pages daemon in the same server as GitLab, listening on the same IP + but on different ports. In that case, you must proxy the traffic with a load + balancer. If you choose that route, you should use TCP load balancing for + HTTPS. If you use TLS-termination (HTTPS-load balancing), the pages aren't + able to be served with user-provided certificates. For HTTP, you can use HTTP + or TCP load balancing. In this document, we proceed assuming the first option. If you aren't supporting custom domains, a secondary IP isn't needed. @@ -53,16 +54,16 @@ supporting custom domains, a secondary IP isn't needed. Before proceeding with the Pages configuration, make sure that: -1. You have a separate domain to serve GitLab Pages from. In - this document we assume that to be `example.io`. -1. You have configured a **wildcard DNS record** for that domain. -1. You have installed the `zip` and `unzip` packages in the same server that - GitLab is installed since they are needed to compress and decompress the - Pages artifacts. -1. Optional. You have a **wildcard certificate** for the Pages domain if you - decide to serve Pages (`*.example.io`) under HTTPS. -1. Optional but recommended. You have configured and enabled the [shared runners](../../ci/runners/index.md) - so that your users don't have to bring their own. +- You have a separate domain to serve GitLab Pages from. In this document we + assume that to be `example.io`. +- You have configured a **wildcard DNS record** for that domain. +- You have installed the `zip` and `unzip` packages in the same server that + GitLab is installed since they are needed to compress and decompress the + Pages artifacts. +- Optional. You have a **wildcard certificate** for the Pages domain if you + decide to serve Pages (`*.example.io`) under HTTPS. +- Optional but recommended. You have configured and enabled the [shared runners](../../ci/runners/index.md) + so your users don't have to bring their own. ### DNS configuration @@ -417,8 +418,6 @@ server_name ~^.*\.pages\.example\.io$; ## Access control -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. - GitLab Pages access control can be configured per-project, and allows access to a Pages site to be controlled based on a user's membership to that project. diff --git a/doc/administration/pseudonymizer.md b/doc/administration/pseudonymizer.md index bd6982bea12..24d9792dcb0 100644 --- a/doc/administration/pseudonymizer.md +++ b/doc/administration/pseudonymizer.md @@ -4,7 +4,12 @@ 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)** +# Pseudonymizer (DEPRECATED) **(ULTIMATE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/219952) in GitLab 14.7. + +WARNING: +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/219952) in GitLab 14.7. Your GitLab database contains sensitive information. To protect sensitive information when you run analytics on your database, you can use the Pseudonymizer service, which: diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index 1d60b8c6f50..fba151fefe1 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -7,6 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Integrity check Rake task **(FREE SELF)** GitLab provides Rake tasks to check the integrity of various components. +See also the [check GitLab configuration Rake task](maintenance.md#check-gitlab-configuration). ## Repository integrity @@ -118,9 +119,9 @@ and these checks verify them against current files. Integrity checks are supported for the following types of file: -- CI artifacts (Available from version 10.7.0) -- LFS objects (Available from version 10.6.0) -- User uploads (Available from version 10.6.0) +- CI artifacts (introduced in GitLab 10.7.0) +- LFS objects (introduced in GitLab 10.6.0) +- User uploads (introduced in GitLab 10.6.0) **Omnibus Installation** @@ -200,6 +201,84 @@ The LDAP check Rake task tests the bind DN and password credentials executed as part of the `gitlab:check` task, but can run independently. See [LDAP Rake Tasks - LDAP Check](ldap.md#check) for details. +## Verify database values can be decrypted using the current secrets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20069) in GitLab 13.1. + +This task runs through all possible encrypted values in the +database, verifying that they are decryptable using the current +secrets file (`gitlab-secrets.json`). + +Automatic resolution is not yet implemented. If you have values that +cannot be decrypted, you can follow steps to reset them, see our +docs on what to do [when the secrets file is lost](../../raketasks/backup_restore.md#when-the-secrets-file-is-lost). + +This can take a very long time, depending on the size of your +database, as it checks all rows in all tables. + +**Omnibus Installation** + +```shell +sudo gitlab-rake gitlab:doctor:secrets +``` + +**Source Installation** + +```shell +bundle exec rake gitlab:doctor:secrets RAILS_ENV=production +``` + +**Example output** + +```plaintext +I, [2020-06-11T17:17:54.951815 #27148] INFO -- : Checking encrypted values in the database +I, [2020-06-11T17:18:12.677708 #27148] INFO -- : - ApplicationSetting failures: 0 +I, [2020-06-11T17:18:12.823692 #27148] INFO -- : - User failures: 0 +[...] other models possibly containing encrypted data +I, [2020-06-11T17:18:14.938335 #27148] INFO -- : - Group failures: 1 +I, [2020-06-11T17:18:15.559162 #27148] INFO -- : - Operations::FeatureFlagsClient failures: 0 +I, [2020-06-11T17:18:15.575533 #27148] INFO -- : - ScimOauthAccessToken failures: 0 +I, [2020-06-11T17:18:15.575678 #27148] INFO -- : Total: 1 row(s) affected +I, [2020-06-11T17:18:15.575711 #27148] INFO -- : Done! +``` + +### Verbose mode + +To get more detailed information about which rows and columns can't be +decrypted, you can pass a `VERBOSE` environment variable: + +**Omnibus Installation** + +```shell +sudo gitlab-rake gitlab:doctor:secrets VERBOSE=1 +``` + +**Source Installation** + +```shell +bundle exec rake gitlab:doctor:secrets RAILS_ENV=production VERBOSE=1 +``` + +**Example verbose output** + +<!-- vale gitlab.SentenceSpacing = NO --> + +```plaintext +I, [2020-06-11T17:17:54.951815 #27148] INFO -- : Checking encrypted values in the database +I, [2020-06-11T17:18:12.677708 #27148] INFO -- : - ApplicationSetting failures: 0 +I, [2020-06-11T17:18:12.823692 #27148] INFO -- : - User failures: 0 +[...] other models possibly containing encrypted data +D, [2020-06-11T17:19:53.224344 #27351] DEBUG -- : > Something went wrong for Group[10].runners_token: Validation failed: Route can't be blank +I, [2020-06-11T17:19:53.225178 #27351] INFO -- : - Group failures: 1 +D, [2020-06-11T17:19:53.225267 #27351] DEBUG -- : - Group[10]: runners_token +I, [2020-06-11T17:18:15.559162 #27148] INFO -- : - Operations::FeatureFlagsClient failures: 0 +I, [2020-06-11T17:18:15.575533 #27148] INFO -- : - ScimOauthAccessToken failures: 0 +I, [2020-06-11T17:18:15.575678 #27148] INFO -- : Total: 1 row(s) affected +I, [2020-06-11T17:18:15.575711 #27148] INFO -- : Done! +``` + +<!-- vale gitlab.SentenceSpacing = YES --> + ## Troubleshooting The following are solutions to problems you might discover using the Rake tasks documented diff --git a/doc/administration/raketasks/doctor.md b/doc/administration/raketasks/doctor.md index 02d1557b6a4..bed3cdcbcfe 100644 --- a/doc/administration/raketasks/doctor.md +++ b/doc/administration/raketasks/doctor.md @@ -1,88 +1,9 @@ --- -stage: Enablement -group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'check.md#verify-database-values-can-be-decrypted-using-the-current-secrets' +remove_date: '2022-03-04' --- -# Doctor Rake tasks **(FREE SELF)** +This document was moved to [another location](check.md#verify-database-values-can-be-decrypted-using-the-current-secrets). -This is a collection of tasks to help investigate and repair -problems caused by data integrity issues. - -## Verify database values can be decrypted using the current secrets - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20069) in GitLab 13.1. - -This task runs through all possible encrypted values in the -database, verifying that they are decryptable using the current -secrets file (`gitlab-secrets.json`). - -Automatic resolution is not yet implemented. If you have values that -cannot be decrypted, you can follow steps to reset them, see our -docs on what to do [when the secrets file is lost](../../raketasks/backup_restore.md#when-the-secrets-file-is-lost). - -This can take a very long time, depending on the size of your -database, as it checks all rows in all tables. - -**Omnibus Installation** - -```shell -sudo gitlab-rake gitlab:doctor:secrets -``` - -**Source Installation** - -```shell -bundle exec rake gitlab:doctor:secrets RAILS_ENV=production -``` - -**Example output** - -```plaintext -I, [2020-06-11T17:17:54.951815 #27148] INFO -- : Checking encrypted values in the database -I, [2020-06-11T17:18:12.677708 #27148] INFO -- : - ApplicationSetting failures: 0 -I, [2020-06-11T17:18:12.823692 #27148] INFO -- : - User failures: 0 -[...] other models possibly containing encrypted data -I, [2020-06-11T17:18:14.938335 #27148] INFO -- : - Group failures: 1 -I, [2020-06-11T17:18:15.559162 #27148] INFO -- : - Operations::FeatureFlagsClient failures: 0 -I, [2020-06-11T17:18:15.575533 #27148] INFO -- : - ScimOauthAccessToken failures: 0 -I, [2020-06-11T17:18:15.575678 #27148] INFO -- : Total: 1 row(s) affected -I, [2020-06-11T17:18:15.575711 #27148] INFO -- : Done! -``` - -### Verbose mode - -To get more detailed information about which rows and columns can't be -decrypted, you can pass a `VERBOSE` environment variable: - -**Omnibus Installation** - -```shell -sudo gitlab-rake gitlab:doctor:secrets VERBOSE=1 -``` - -**Source Installation** - -```shell -bundle exec rake gitlab:doctor:secrets RAILS_ENV=production VERBOSE=1 -``` - -**Example verbose output** - -<!-- vale gitlab.SentenceSpacing = NO --> - -```plaintext -I, [2020-06-11T17:17:54.951815 #27148] INFO -- : Checking encrypted values in the database -I, [2020-06-11T17:18:12.677708 #27148] INFO -- : - ApplicationSetting failures: 0 -I, [2020-06-11T17:18:12.823692 #27148] INFO -- : - User failures: 0 -[...] other models possibly containing encrypted data -D, [2020-06-11T17:19:53.224344 #27351] DEBUG -- : > Something went wrong for Group[10].runners_token: Validation failed: Route can't be blank -I, [2020-06-11T17:19:53.225178 #27351] INFO -- : - Group failures: 1 -D, [2020-06-11T17:19:53.225267 #27351] DEBUG -- : - Group[10]: runners_token -I, [2020-06-11T17:18:15.559162 #27148] INFO -- : - Operations::FeatureFlagsClient failures: 0 -I, [2020-06-11T17:18:15.575533 #27148] INFO -- : - ScimOauthAccessToken failures: 0 -I, [2020-06-11T17:18:15.575678 #27148] INFO -- : Total: 1 row(s) affected -I, [2020-06-11T17:18:15.575711 #27148] INFO -- : Done! -``` - -<!-- vale gitlab.SentenceSpacing = YES --> +<!-- This redirect file can be deleted after 2022-03-04. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/administration/raketasks/geo.md b/doc/administration/raketasks/geo.md index 3112e5f61b1..6306e54bdc6 100644 --- a/doc/administration/raketasks/geo.md +++ b/doc/administration/raketasks/geo.md @@ -7,6 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Geo Rake Tasks **(PREMIUM SELF)** The following Rake tasks are for [Geo installations](../geo/index.md). +See also [troubleshooting Geo](../geo/replication/troubleshooting.md) for additional Geo Rake tasks. ## Git housekeeping diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index 62ddd9be2b3..e6adb98a92a 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 950b508ab0c..d66f3b1ed35 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -106,17 +106,22 @@ The `gitlab:check` Rake task runs the following Rake tasks: - `gitlab:gitlab_shell:check` - `gitlab:gitaly:check` - `gitlab:sidekiq:check` +- `gitlab:incoming_email:check` +- `gitlab:ldap:check` - `gitlab:app:check` 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/configure_gitaly.md#run-gitaly-on-its-own-server). +If you're running Geo, see also the [Geo Health check Rake task](../geo/replication/troubleshooting.md#health-check-rake-task). You may also have a look at our troubleshooting guides for: - [GitLab](../index.md#troubleshooting) - [Omnibus GitLab](https://docs.gitlab.com/omnibus/index.html#troubleshooting) +Additionally you should also [verify database values can be decrypted using the current secrets](check.md#verify-database-values-can-be-decrypted-using-the-current-secrets). + To run `gitlab:check`, run: **Omnibus Installation** diff --git a/doc/administration/redis/replication_and_failover.md b/doc/administration/redis/replication_and_failover.md index db652a80780..086057d80b4 100644 --- a/doc/administration/redis/replication_and_failover.md +++ b/doc/administration/redis/replication_and_failover.md @@ -648,6 +648,7 @@ persistence classes. | `actioncable` | Pub/Sub queue backend for ActionCable. | | `trace_chunks` | Store [CI trace chunks](../job_logs.md#enable-or-disable-incremental-logging) data. | | `rate_limiting` | Store [rate limiting](../../user/admin_area/settings/user_and_ip_rate_limits.md) state. | +| `sessions` | Store [sessions](../../../ee/development/session.md#gitlabsession). | To make this work with Sentinel: @@ -661,6 +662,7 @@ To make this work with Sentinel: gitlab_rails['redis_actioncable_instance'] = REDIS_ACTIONCABLE_URL gitlab_rails['redis_trace_chunks_instance'] = REDIS_TRACE_CHUNKS_URL gitlab_rails['redis_rate_limiting_instance'] = REDIS_RATE_LIMITING_URL + gitlab_rails['redis_sessions_instance'] = REDIS_SESSIONS_URL # Configure the Sentinels gitlab_rails['redis_cache_sentinels'] = [ @@ -687,6 +689,10 @@ To make this work with Sentinel: { host: RATE_LIMITING_SENTINEL_HOST, port: 26379 }, { host: RATE_LIMITING_SENTINEL_HOST2, port: 26379 } ] + gitlab_rails['redis_sessions_sentinels'] = [ + { host: SESSIONS_SENTINEL_HOST, port: 26379 }, + { host: SESSIONS_SENTINEL_HOST2, port: 26379 } + ] ``` - Redis URLs should be in the format: `redis://:PASSWORD@SENTINEL_PRIMARY_NAME`, where: diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index fa8dfdf667b..a5c60af47b1 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -1833,7 +1833,7 @@ On each node perform the following: external_url 'https://gitlab.example.com' # git_data_dirs get configured for the Praefect virtual storage - # Address is Interal Load Balancer for Praefect + # Address is Internal Load Balancer for Praefect # Token is praefect_external_token git_data_dirs({ "default" => { @@ -2228,17 +2228,16 @@ use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. -| Service | Nodes<sup>1</sup> | Configuration | GCP | Allocatable CPUs and Memory | -|-------------------------------------------------------|-------------------|-------------------------|------------------|-----------------------------| -| Webservice | 4 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | 127.5 vCPU, 118 GB memory | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | 15.5 vCPU, 50 GB memory | -| Supporting services such as NGINX, Prometheus | 2 | 4 vCPU, 15 GB memory | `n1-standard-4` | 7.75 vCPU, 25 GB memory | +| Service | Nodes | Configuration | GCP | Allocatable CPUs and Memory | +|-------------------------------------------------------|-------|-------------------------|------------------|-----------------------------| +| Webservice | 4 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | 127.5 vCPU, 118 GB memory | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | 15.5 vCPU, 50 GB memory | +| Supporting services such as NGINX, Prometheus | 2 | 4 vCPU, 15 GB memory | `n1-standard-4` | 7.75 vCPU, 25 GB memory | -<!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> -<!-- markdownlint-disable MD029 --> -1. Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. - In production deployments there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -<!-- markdownlint-enable MD029 --> +- For this setup, we **recommend** and regularly [test](index.md#testing-process-and-results) +[Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) and [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/). Other Kubernetes services may also work, but your mileage may vary. +- Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. + - In production deployments, there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. Next are the backend components that run on static compute VMs via Omnibus (or External PaaS services where applicable): diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 24b3350bd75..8cc355db951 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -26,7 +26,7 @@ full list of reference architectures, see | PgBouncer<sup>1</sup> | 3 | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | | Internal load balancing node<sup>3</sup> | 1 | 4 vCPU, 3.6GB memory | `n1-highcpu-4` | `c5.large` | `F2s v2` | | Redis/Sentinel - Cache<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | -| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.large` | `D4s v3` | +| Redis/Sentinel - Persistent<sup>2</sup> | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | `m5.xlarge` | `D4s v3` | | Gitaly<sup>5</sup> | 3 | 32 vCPU, 120 GB memory | `n1-standard-32` | `m5.8xlarge` | `D32s v3` | | Praefect<sup>5</sup> | 3 | 4 vCPU, 3.6 GB memory | `n1-highcpu-4` | `c5.xlarge` | `F4s v2` | | Praefect PostgreSQL<sup>1</sup> | 1+ | 2 vCPU, 1.8 GB memory | `n1-highcpu-2` | `c5.large` | `F2s v2` | @@ -2226,17 +2226,16 @@ use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. -| Service | Nodes<sup>1</sup> | Configuration | GCP | Allocatable CPUs and Memory | -|-------------------------------------------------------|-------------------|-------------------------|------------------|-----------------------------| -| Webservice | 7 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | 223 vCPU, 206.5 GB memory | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | 15.5 vCPU, 50 GB memory | -| Supporting services such as NGINX, Prometheus | 2 | 4 vCPU, 15 GB memory | `n1-standard-4` | 7.75 vCPU, 25 GB memory | +| Service | Nodes | Configuration | GCP | Allocatable CPUs and Memory | +|-------------------------------------------------------|-------|-------------------------|------------------|-----------------------------| +| Webservice | 7 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | 223 vCPU, 206.5 GB memory | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | 15.5 vCPU, 50 GB memory | +| Supporting services such as NGINX, Prometheus | 2 | 4 vCPU, 15 GB memory | `n1-standard-4` | 7.75 vCPU, 25 GB memory | -<!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> -<!-- markdownlint-disable MD029 --> -1. Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. - In production deployments there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -<!-- markdownlint-enable MD029 --> +- For this setup, we **recommend** and regularly [test](index.md#testing-process-and-results) +[Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) and [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/). Other Kubernetes services may also work, but your mileage may vary. +- Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. + - In production deployments, there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. Next are the backend components that run on static compute VMs via Omnibus (or External PaaS services where applicable): diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index f72c0877ddb..467c64b8279 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -1016,17 +1016,16 @@ use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. -| Service | Nodes<sup>1</sup> | Configuration | GCP | Allocatable CPUs and Memory | -|-------------------------------------------------------|-------------------|------------------------|-----------------|-----------------------------| -| Webservice | 3 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | 23.7 vCPU, 16.9 GB memory | -| Sidekiq | 2 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | 3.9 vCPU, 11.8 GB memory | -| Supporting services such as NGINX, Prometheus | 2 | 1 vCPU, 3.75 GB memory | `n1-standard-1` | 1.9 vCPU, 5.5 GB memory | - -<!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> -<!-- markdownlint-disable MD029 --> -1. Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. - In production deployments there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -<!-- markdownlint-enable MD029 --> +| Service | Nodes | Configuration | GCP | Allocatable CPUs and Memory | +|-------------------------------------------------------|-------|------------------------|-----------------|-----------------------------| +| Webservice | 3 | 8 vCPU, 7.2 GB memory | `n1-highcpu-8` | 23.7 vCPU, 16.9 GB memory | +| Sidekiq | 2 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | 3.9 vCPU, 11.8 GB memory | +| Supporting services such as NGINX, Prometheus | 2 | 1 vCPU, 3.75 GB memory | `n1-standard-1` | 1.9 vCPU, 5.5 GB memory | + +- For this setup, we **recommend** and regularly [test](index.md#testing-process-and-results) +[Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) and [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/). Other Kubernetes services may also work, but your mileage may vary. +- Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. + - In production deployments, there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. Next are the backend components that run on static compute VMs via Omnibus (or External PaaS services where applicable): diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index c788a73753b..01d9987739b 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -1794,7 +1794,7 @@ On each node perform the following: external_url 'https://gitlab.example.com' # git_data_dirs get configured for the Praefect virtual storage - # Address is Interal Load Balancer for Praefect + # Address is Internal Load Balancer for Praefect # Token is praefect_external_token git_data_dirs({ "default" => { @@ -2185,17 +2185,16 @@ use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. -| Service | Nodes<sup>1</sup> | Configuration | GCP | Allocatable CPUs and Memory | -|-------------------------------------------------------|-------------------|-------------------------|------------------|-----------------------------| -| Webservice | 2 | 16 vCPU, 14.4 GB memory | `n1-highcpu-16` | 31.8 vCPU, 24.8 GB memory | -| Sidekiq | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | 11.8 vCPU, 38.9 GB memory | -| Supporting services such as NGINX, Prometheus | 2 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | 3.9 vCPU, 11.8 GB memory | +| Service | Nodes | Configuration | GCP | Allocatable CPUs and Memory | +|-------------------------------------------------------|-------|-------------------------|------------------|-----------------------------| +| Webservice | 2 | 16 vCPU, 14.4 GB memory | `n1-highcpu-16` | 31.8 vCPU, 24.8 GB memory | +| Sidekiq | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | 11.8 vCPU, 38.9 GB memory | +| Supporting services such as NGINX, Prometheus | 2 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | 3.9 vCPU, 11.8 GB memory | -<!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> -<!-- markdownlint-disable MD029 --> -1. Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. - In production deployments there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -<!-- markdownlint-enable MD029 --> +- For this setup, we **recommend** and regularly [test](index.md#testing-process-and-results) +[Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) and [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/). Other Kubernetes services may also work, but your mileage may vary. +- Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. + - In production deployments, there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. Next are the backend components that run on static compute VMs via Omnibus (or External PaaS services where applicable): diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index 4f576fc1c19..d5bb9c4ad64 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -1855,7 +1855,7 @@ On each node perform the following: external_url 'https://gitlab.example.com' # git_data_dirs get configured for the Praefect virtual storage - # Address is Interal Load Balancer for Praefect + # Address is Internal Load Balancer for Praefect # Token is praefect_external_token git_data_dirs({ "default" => { @@ -2242,17 +2242,16 @@ use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. -| Service | Nodes<sup>1</sup> | Configuration | GCP | Allocatable CPUs and Memory | -|-------------------------------------------------------|-------------------|-------------------------|------------------|-----------------------------| -| Webservice | 16 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | 510 vCPU, 472 GB memory | -| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | 15.5 vCPU, 50 GB memory | -| Supporting services such as NGINX, Prometheus | 2 | 4 vCPU, 15 GB memory | `n1-standard-4` | 7.75 vCPU, 25 GB memory | +| Service | Nodes | Configuration | GCP | Allocatable CPUs and Memory | +|-------------------------------------------------------|-------|-------------------------|------------------|-----------------------------| +| Webservice | 16 | 32 vCPU, 28.8 GB memory | `n1-highcpu-32` | 510 vCPU, 472 GB memory | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | `n1-standard-4` | 15.5 vCPU, 50 GB memory | +| Supporting services such as NGINX, Prometheus | 2 | 4 vCPU, 15 GB memory | `n1-standard-4` | 7.75 vCPU, 25 GB memory | -<!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> -<!-- markdownlint-disable MD029 --> -1. Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. - In production deployments there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -<!-- markdownlint-enable MD029 --> +- For this setup, we **recommend** and regularly [test](index.md#testing-process-and-results) +[Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) and [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/). Other Kubernetes services may also work, but your mileage may vary. +- Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. + - In production deployments, there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. Next are the backend components that run on static compute VMs via Omnibus (or External PaaS services where applicable): diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 92950806cfb..33ca4e4899f 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -1791,7 +1791,7 @@ On each node perform the following: external_url 'https://gitlab.example.com' # git_data_dirs get configured for the Praefect virtual storage - # Address is Interal Load Balancer for Praefect + # Address is Internal Load Balancer for Praefect # Token is praefect_external_token git_data_dirs({ "default" => { @@ -2161,17 +2161,16 @@ use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. -| Service | Nodes<sup>1</sup> | Configuration | GCP | Allocatable CPUs and Memory | -|-------------------------------------------------------|-------------------|-------------------------|------------------|-----------------------------| -| Webservice | 5 | 16 vCPU, 14.4 GB memory | `n1-highcpu-16` | 79.5 vCPU, 62 GB memory | -| Sidekiq | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | 11.8 vCPU, 38.9 GB memory | -| Supporting services such as NGINX, Prometheus | 2 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | 3.9 vCPU, 11.8 GB memory | +| Service | Nodes | Configuration | GCP | Allocatable CPUs and Memory | +|-------------------------------------------------------|-------|-------------------------|------------------|-----------------------------| +| Webservice | 5 | 16 vCPU, 14.4 GB memory | `n1-highcpu-16` | 79.5 vCPU, 62 GB memory | +| Sidekiq | 3 | 4 vCPU, 15 GB memory | `n1-standard-4` | 11.8 vCPU, 38.9 GB memory | +| Supporting services such as NGINX, Prometheus | 2 | 2 vCPU, 7.5 GB memory | `n1-standard-2` | 3.9 vCPU, 11.8 GB memory | -<!-- Disable ordered list rule https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix --> -<!-- markdownlint-disable MD029 --> -1. Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. - In production deployments there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. -<!-- markdownlint-enable MD029 --> +- For this setup, we **recommend** and regularly [test](index.md#testing-process-and-results) +[Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine) and [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/). Other Kubernetes services may also work, but your mileage may vary. +- Nodes configuration is shown as it is forced to ensure pod vcpu / memory ratios and avoid scaling during **performance testing**. + - In production deployments, there is no need to assign pods to nodes. A minimum of three nodes in three different availability zones is strongly recommended to align with resilient cloud architecture practices. Next are the backend components that run on static compute VMs via Omnibus (or External PaaS services where applicable): diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 6bf35ba6e22..bd796600564 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -208,19 +208,16 @@ Note the following about the testing process: - We aim to have a "test smart" approach where architectures tested have a good range that can also apply to others. Testing focuses on 10k Omnibus on GCP as the testing has shown this is a good bellwether for the other architectures and cloud providers as well as Cloud Native Hybrids. - Testing is done publicly and all results are shared. -Τhe following table details the testing done against the reference architectures along with the frequency and results. - -| Reference Architecture | Tests Run<sup>1</sup> | -|------------------------|----------------------------------------------------------------------------------------------------------------------| -| 1k | [Omnibus - Daily (GCP)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/1k)<sup>2</sup> | -| 2k | [Omnibus - Daily (GCP)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/2k)<sup>2</sup> | -| 3k | [Omnibus - Weekly (GCP)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/3k)<sup>2</sup> | -| 5k | [Omnibus - Weekly (GCP)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/5k)<sup>2</sup> | -| 10k | [Omnibus - Daily (GCP)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/10k)<sup>2</sup><br/>[Omnibus - Ad-Hoc (GCP, AWS, Azure)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/10k)<br/><br/>[Cloud Native Hybrid - Ad-Hoc (GCP, AWS)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/10k-Cloud-Native-Hybrid) | -| 25k | [Omnibus - Weekly (GCP)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/25k)<sup>2</sup><br/>[Omnibus - Ad-Hoc (Azure)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/25k) | -| 50k | [Omnibus - Weekly (GCP)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/50k)<sup>2</sup><br/>[Omnibus - Ad-Hoc (AWS)](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/50k) | - -Note that: - -1. The list above is non exhaustive. Additional testing is continuously evaluated and iterated on, and the table is updated regularly. -1. The Omnibus reference architectures are VM-based only and testing has shown that they perform similarly on equivalently specced hardware regardless of Cloud Provider or if run on premises. +Τhe following table details the testing done against the reference architectures along with the frequency and results. Note that this list above is non exhaustive. Additional testing is continuously evaluated and iterated on, and the table is updated accordingly. + +| Reference<br/>Architecture<br/>Size | Bare-Metal | GCP | AWS | Azure | +|-----------------------------|------------|-----|-----|-------| +| 1k | <i>Refer to GCP<sup>1</sup></i> | [Standard - Weekly](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/1k)<sup>1</sup> | - | - | +| 2k | <i>Refer to GCP<sup>1</sup></i> | [Standard - Weekly](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/2k)<sup>1</sup> | - | - | +| 3k | <i>Refer to GCP<sup>1</sup></i> | [Standard - Weekly](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/3k)<sup>1</sup> | - | - | +| 5k | <i>Refer to GCP<sup>1</sup></i> | [Standard - Weekly](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/5k)<sup>1</sup> | - | - | +| 10k | <i>Refer to GCP<sup>1</sup></i> | [Standard - Daily](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/10k)<sup>1</sup> <br/> [Standard (inc Cloud Services) - Ad-Hoc](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/10k) <br/> [Cloud Native Hybrid - Ad-Hoc](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/10k-Cloud-Native-Hybrid) | [Standard (inc Cloud Services) - Ad-Hoc](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/10k) <br/> [Cloud Native Hybrid - Ad-Hoc](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/10k-Cloud-Native-Hybrid) | [Standard - Ad-Hoc](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/10k) | +| 25k | <i>Refer to GCP<sup>1</sup></i> | [Standard - Weekly](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/25k)<sup>1</sup> | - | [Standard - Ad-Hoc](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/25k) | +| 50k | <i>Refer to GCP<sup>1</sup></i> | [Standard - Weekly](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Benchmarks/Latest/50k)<sup>1</sup> | [Standard (inc Cloud Services) - Ad-Hoc](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Past-Results/50k) | - | + +1. The Standard Reference Architectures are designed to be platform agnostic, with everything being run on VMs via [Omnibus GitLab](https://docs.gitlab.com/omnibus/). While testing occurs primarily on GCP, ad-hoc testing has shown that they perform similarly on equivalently specced hardware on other Cloud Providers or if run on premises (bare-metal). diff --git a/doc/administration/sidekiq.md b/doc/administration/sidekiq.md index 8f1119f6868..989a024d6ab 100644 --- a/doc/administration/sidekiq.md +++ b/doc/administration/sidekiq.md @@ -2,7 +2,6 @@ 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 --- # Configuring Sidekiq **(FREE SELF)** @@ -21,8 +20,6 @@ you want using steps 1 and 2 from the GitLab downloads page. 1. Generate the Sidekiq configuration: ```ruby - sidekiq['listen_address'] = "10.10.1.48" - ## Optional: Enable extra Sidekiq processes sidekiq_cluster['enable'] = true sidekiq['queue_groups'] = [ @@ -128,6 +125,34 @@ you want using steps 1 and 2 from the GitLab downloads page. external_url 'https://gitlab.example.com' ``` +1. (Optional) If you want to collect Sidekiq metrics, enable the Sidekiq metrics server. + To make metrics available from `localhost:8082/metrics`, set the following values: + + ```ruby + sidekiq['metrics_enabled'] = true + sidekiq['listen_address'] = "localhost" + sidekiq['listen_port'] = "8082" + + # Optionally log all the metrics server logs to log/sidekiq_exporter.log + sidekiq['exporter_log_enabled'] = true + ``` + +1. (Optional) If you use health check probes to observe Sidekiq, + set a separate port for health checks. + Configuring health checks is only necessary if there is something that actually probes them. + For more information about health checks, see the [Sidekiq health check page](sidekiq_health_check.md). + Enable health checks for Sidekiq: + + ```ruby + sidekiq['health_checks_enabled'] = true + sidekiq['health_checks_listen_address'] = "localhost" + sidekiq['health_checks_listen_port'] = "8092" + ``` + + NOTE: + If health check settings are not set, they will default to the metrics exporter settings. + This default is deprecated and is set to be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/347509). + 1. Run `gitlab-ctl reconfigure`. You will need to restart the Sidekiq nodes after an update has occurred and database @@ -196,7 +221,13 @@ gitlab_rails['auto_migrate'] = false ####################################### ### Sidekiq configuration ### ####################################### -sidekiq['listen_address'] = "10.10.1.48" +sidekiq['metrics_enabled'] = true +sidekiq['exporter_log_enabled'] = false +sidekiq['listen_port'] = "8082" + +sidekiq['health_checks_enabled'] = true +sidekiq['health_checks_listen_address'] = "localhost" +sidekiq['health_checks_listen_port'] = "8092" ####################################### ### Monitoring configuration ### @@ -230,3 +261,4 @@ Related Sidekiq configuration: 1. [Extra Sidekiq processes](operations/extra_sidekiq_processes.md) 1. [Extra Sidekiq routing](operations/extra_sidekiq_routing.md) 1. [Using the GitLab-Sidekiq chart](https://docs.gitlab.com/charts/charts/gitlab/sidekiq/) +1. [Sidekiq health checks](sidekiq_health_check.md) diff --git a/doc/administration/sidekiq_health_check.md b/doc/administration/sidekiq_health_check.md new file mode 100644 index 00000000000..2ed736bac2c --- /dev/null +++ b/doc/administration/sidekiq_health_check.md @@ -0,0 +1,60 @@ +--- +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 +--- + +# Sidekiq Health Check **(FREE SELF)** + +GitLab provides liveness and readiness probes to indicate service health and +reachability to the Sidekiq cluster. These endpoints +[can be provided to schedulers like Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) +to hold traffic until the system is ready or restart the container as needed. + +The health check server can be set up when [configuring Sidekiq](sidekiq.md). + +## Readiness + +The readiness probe checks whether the Sidekiq workers are ready to process jobs. + +```plaintext +GET /readiness +``` + +Assuming you set up Sidekiq's address and port to be `localhost` and `8092` respectively, +here's an example request: + +```shell +curl "http://localhost:8092/readiness" +``` + +On success, the endpoint returns a `200` HTTP status code, and a response like the following: + +```json +{ + "status": "ok" +} +``` + +## Liveness + +Checks whether the Sidekiq cluster is running. + +```plaintext +GET /liveness +``` + +Assuming you set up Sidekiq's address and port to be `localhost` and `8092` respectively, +here's an example request: + +```shell +curl "http://localhost:8092/liveness" +``` + +On success, the endpoint returns a `200` HTTP status code, and a response like the following: + +```json +{ + "status": "ok" +} +``` diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index 582ffc9dc9c..d1113125c4e 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -101,6 +101,11 @@ The following settings are: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247042) in GitLab 13.9. +WARNING: +It's not possible to migrate Terraform state files from object storage back to local storage, +so proceed with caution. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/350187) +to change this behavior. + To migrate Terraform state files to object storage, follow the instructions below. - For Omnibus package installations: diff --git a/doc/administration/troubleshooting/defcon.md b/doc/administration/troubleshooting/defcon.md index 1b263f70b46..a7cc47f8547 100644 --- a/doc/administration/troubleshooting/defcon.md +++ b/doc/administration/troubleshooting/defcon.md @@ -23,7 +23,7 @@ Side effects: ## `ci_queueing_disaster_recovery_disable_quota` -This feature flag, if temporarily enabled, disables enforcing CI minutes quota +This feature flag, if temporarily enabled, disables enforcing CI/CD minutes quota on shared runners. This can help to reduce system resource usage on the `jobs/request` endpoint by significantly reducing the computations being performed. diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index ccfa93d9bc8..33a81c12811 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -2,7 +2,6 @@ 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 --- # GitLab Rails Console Cheat Sheet **(FREE SELF)** @@ -526,7 +525,7 @@ master f05321a5b5728bd8a89b7bf530aa44043c951dce...7d02e575fd790e76 ### Find mirrors with "bad decrypt" errors -This content has been converted to a Rake task, see the [Doctor Rake tasks docs](../raketasks/doctor.md). +This content has been converted to a Rake task, see [verify database values can be decrypted using the current secrets](../raketasks/check.md#verify-database-values-can-be-decrypted-using-the-current-secrets). ### Transfer mirror users and tokens to a single service account @@ -909,6 +908,14 @@ end Gitlab::CurrentSettings.current_application_settings.runners_registration_token ``` +### Seed runners registration token + +```ruby +appSetting = Gitlab::CurrentSettings.current_application_settings +appSetting.set_runners_registration_token('<new-runners-registration-token>') +appSetting.save! +``` + ### Run pipeline schedules manually You can run pipeline schedules manually through the Rails console to reveal any errors that are usually not visible. @@ -979,7 +986,7 @@ This is needed for example in a known edge-case with ### Remove licenses -To clean up the [License History table](../../user/admin_area/license.md#license-history): +To clean up the [License History table](../../user/admin_area/license.md#view-license-details-and-history): ```ruby TYPE = :trial? @@ -1065,7 +1072,7 @@ area on disk. It remains to be seen exactly how or whether the deletion is usefu ### Bad Decrypt Script (for encrypted variables) -This content has been converted to a Rake task, see the [Doctor Rake tasks docs](../raketasks/doctor.md). +This content has been converted to a Rake task, see [verify database values can be decrypted using the current secrets](../raketasks/check.md#verify-database-values-can-be-decrypted-using-the-current-secrets). As an example of repairing, if `ProjectImportData Bad count:` is detected and the decision is made to delete the encrypted credentials to allow manual reentry: @@ -1108,7 +1115,7 @@ gitlab-rails runner /tmp/encrypted-tokens.rb ### Decrypt Script for encrypted tokens -This content has been converted to a Rake task, see the [Doctor Rake tasks docs](../raketasks/doctor.md). +This content has been converted to a Rake task, see [verify database values can be decrypted using the current secrets](../raketasks/check.md#verify-database-values-can-be-decrypted-using-the-current-secrets). ## Geo @@ -1262,10 +1269,20 @@ registry = Geo::SnippetRepositoryRegistry.find(registry_id) registry.replicator.send(:sync_repository) ``` +## Gitaly + +### Find available and used space + +A Gitaly storage resource can be polled through Rails to determine the available and used space. + +```ruby +Gitlab::GitalyClient::ServerService.new("default").storage_disk_statistics +``` + ## Generate Service Ping -The [Service Ping Guide](../../development/service_ping/index.md) in our developer documentation -has more information about Service Ping. +The [Service Ping Guide](../../development/service_ping/index.md) in our developer documentation +has more information about Service Ping. ### Generate or get the cached Service Ping @@ -1291,7 +1308,7 @@ rake gitlab:usage_data:generate Generates Service Ping data in YAML format: -```shell +```shell rake gitlab:usage_data:dump_sql_in_yaml ``` diff --git a/doc/administration/troubleshooting/group_saml_scim.md b/doc/administration/troubleshooting/group_saml_scim.md index d052688363c..8ec6b35ec39 100644 --- a/doc/administration/troubleshooting/group_saml_scim.md +++ b/doc/administration/troubleshooting/group_saml_scim.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/administration/troubleshooting/img/okta_setting_username.png b/doc/administration/troubleshooting/img/okta_setting_username.png Binary files differindex c413b9d3a27..5f87d14bb8b 100644 --- a/doc/administration/troubleshooting/img/okta_setting_username.png +++ b/doc/administration/troubleshooting/img/okta_setting_username.png diff --git a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md index 64a6979c016..290d6d9f21d 100644 --- a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md +++ b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md @@ -118,15 +118,18 @@ and they will assist you with any issues you are having. kubectl get events -w --namespace=gitlab ``` -- Most of the useful GitLab tools (console, Rake tasks, etc) are found in the task-runner - pod. You may enter it and run commands inside or run them from the outside: +- Most of the useful GitLab tools (console, Rake tasks, etc) are found in the toolbox + pod. You may enter it and run commands inside or run them from the outside. + + NOTE: + The `task-runner` pod was renamed to `toolbox` in GitLab 14.2 (charts 5.2). ```shell # find the pod - kubectl get pods | grep task-runner + kubectl --namespace gitlab get pods -lapp=toolbox # enter it - kubectl exec -it <task-runner-pod-name> -- bash + kubectl exec -it <toolbox-pod-name> -- bash # open rails console # rails console can be also called from other GitLab pods @@ -139,10 +142,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 <toolbox-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 <toolbox-pod-name> -- /usr/local/bin/gitlab-rake db:migrate:status ``` You can also use `gitlab-rake`, instead of `/usr/local/bin/gitlab-rake`. @@ -163,12 +166,15 @@ and they will assist you with any issues you are having. kubectl get secret <secret-name> -ojsonpath={.data.password} | base64 --decode ; echo ``` -- How to connect to a GitLab PostgreSQL database: +- How to connect to a GitLab PostgreSQL database. + + NOTE: + The `task-runner` pod was renamed to `toolbox` in GitLab 14.2 (charts 5.2). In GitLab 14.2 (chart 5.2) and later: ```shell - kubectl exec -it <task-runner-pod-name> -- /srv/gitlab/bin/rails dbconsole --include-password --database main + kubectl exec -it <toolbox-pod-name> -- /srv/gitlab/bin/rails dbconsole --include-password --database main ``` In GitLab 14.1 (chart 5.1) and earlier: @@ -215,9 +221,9 @@ all Kubernetes resources and dependent charts: helm get manifest <release name> ``` -## Installation of minimal GitLab configuration 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) +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 to those documents for details. @@ -227,13 +233,13 @@ to those documents for details. brew install kubernetes-cli ``` -- Install Minikube via Homebrew: +- Install minikube via Homebrew: ```shell brew cask install minikube ``` -- Start Minikube and configure it. If Minikube cannot start, try running `minikube delete && minikube start` +- Start minikube and configure it. If minikube cannot start, try running `minikube delete && minikube start` and repeat the steps: ```shell @@ -247,7 +253,7 @@ to those documents for details. brew install helm ``` -- Copy the [Minikube minimum values YAML file](https://gitlab.com/gitlab-org/charts/gitlab/raw/master/examples/values-minikube-minimum.yaml) +- Copy the [minikube minimum values YAML file](https://gitlab.com/gitlab-org/charts/gitlab/raw/master/examples/values-minikube-minimum.yaml) to your workstation: ```shell diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index f8cb45dd00d..e4d1696ea93 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -179,3 +179,43 @@ Once saved, [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure 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. + +### Temporarily changing the statement timeout + +WARNING: +The following advice does not apply in case +[PgBouncer](../postgresql/pgbouncer.md) is enabled, +because the changed timeout might affect more transactions than intended. + +In some situations, it may be desirable to set a different statement timeout +without having to [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure), +which in this case would restart Puma and Sidekiq. + +For example, a backup may fail with the following errors in the output of the +[backup command](../../raketasks/backup_restore.md#back-up-gitlab) +because the statement timeout was too short: + +```plaintext +pg_dump: error: Error message from server: server closed the connection unexpectedly +``` + +You may also see errors in the [PostgreSQL logs](../logs.md#postgresql-logs): + +```plaintext +canceling statement due to statement timeout +``` + +To temporarily change the statement timeout: + +1. Open `/var/opt/gitlab/gitlab-rails/etc/database.yml` in an editor +1. Set the value of `statement_timeout` to `0`, which sets an unlimited statement timeout. +1. [Confirm in a new Rails console session](../operations/rails_console.md#using-the-rails-runner) + that this value is used: + + ```shell + sudo gitlab-rails runner "ActiveRecord::Base.connection_config[:variables]" + ``` + +1. Perform the action for which you need a different timeout + (for example the backup or the Rails command). +1. Revert the edit in `/var/opt/gitlab/gitlab-rails/etc/database.yml`. diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index a606a3712ba..62ea3bcfa3c 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.md @@ -387,7 +387,7 @@ blocking all jobs on that worker from proceeding. If Rugged calls performed by S background task processing. By default, Rugged is used when Git repository data is stored on local storage or on an NFS mount. -[Using Rugged is recommened when using NFS](../nfs.md#improving-nfs-performance-with-gitlab), but if +[Using Rugged is recommended when using NFS](../nfs.md#improving-nfs-performance-with-gitlab), but if you are using local storage, disabling Rugged can improve Sidekiq performance: ```shell diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md index 01a4c4af65b..83df9ba19ff 100644 --- a/doc/administration/troubleshooting/ssl.md +++ b/doc/administration/troubleshooting/ssl.md @@ -18,7 +18,7 @@ main SSL docs available here: ## 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 by using various CLI tools. You may see experience the +not be able to access it by using various CLI tools. You may experience the following issues: - `curl` fails: diff --git a/doc/administration/user_settings.md b/doc/administration/user_settings.md index 891c11afaf4..2c1bb781882 100644 --- a/doc/administration/user_settings.md +++ b/doc/administration/user_settings.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index df830a1607d..9c217a98c3d 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index f489cb780ef..783823f80fb 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -25,7 +25,7 @@ The following API resources are available in the project context: | Resource | Available endpoints | |:------------------------------------------------------------------------|:--------------------| | [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) | -| [Access tokens](resource_access_tokens.md) | `/projects/:id/access_tokens` | +| [Access tokens](resource_access_tokens.md) | `/projects/:id/access_tokens` (also available for groups) | | [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | | [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` | | [Commits](commits.md) | `/projects/:id/repository/commits`, `/projects/:id/statuses` | @@ -34,6 +34,7 @@ The following API resources are available in the project context: | [Debian distributions](packages/debian_project_distributions.md) | `/projects/:id/debian_distributions` (also available for groups) | | [Dependencies](dependencies.md) **(ULTIMATE)** | `/projects/:id/dependencies` | | [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | +| [Deploy tokens](deploy_tokens.md) | `/projects/:id/deploy_tokens` (also available for groups and standalone) | | [Deployments](deployments.md) | `/projects/:id/deployments` | | [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) | | [Environments](environments.md) | `/projects/:id/environments` | @@ -99,8 +100,10 @@ The following API resources are available in the group context: | Resource | Available endpoints | |:-----------------------------------------------------------------|:--------------------| | [Access requests](access_requests.md) | `/groups/:id/access_requests/` (also available for projects) | +| [Access tokens](group_access_tokens.md) | `/groups/:id/access_tokens` (also available for projects) | | [Custom attributes](custom_attributes.md) | `/groups/:id/custom_attributes` (also available for projects and users) | | [Debian distributions](packages/debian_group_distributions.md) | `/groups/:id/-/packages/debian` (also available for projects) | +| [Deploy tokens](deploy_tokens.md) | `/groups/:id/deploy_tokens` (also available for projects and standalone) | | [Discussions](discussions.md) (threaded comments) **(ULTIMATE)** | `/groups/:id/epics/.../discussions` (also available for projects) | | [Epic issues](epic_issues.md) **(ULTIMATE)** | `/groups/:id/epics/.../issues` | | [Epic links](epic_links.md) **(ULTIMATE)** | `/groups/:id/epics/.../epics` | @@ -137,6 +140,7 @@ The following API resources are available outside of project and group contexts | [Code snippets](snippets.md) | `/snippets` | | [Custom attributes](custom_attributes.md) | `/users/:id/custom_attributes` (also available for groups and projects) | | [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | +| [Deploy tokens](deploy_tokens.md) | `/deploy_tokens` (also available for projects and groups) | | [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) | | [Feature flags](features.md) | `/features` | | [Geo Nodes](geo_nodes.md) **(PREMIUM SELF)** | `/geo_nodes` | diff --git a/doc/api/appearance.md b/doc/api/appearance.md index 5689cacd9ce..5e7ffbff25c 100644 --- a/doc/api/appearance.md +++ b/doc/api/appearance.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/applications.md b/doc/api/applications.md index 22d858bd68a..bbf12438f28 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/avatar.md b/doc/api/avatar.md index 200d7524b7f..5db8c30cb9a 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/commits.md b/doc/api/commits.md index 94d1ced181c..6347af451a2 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/#assignments" +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Commits API **(FREE)** @@ -502,9 +502,8 @@ Example response: Adds a comment to a commit. -In order to post a comment in a particular line of a particular file, you must -specify the full commit SHA, the `path`, the `line` and `line_type` should be -`new`. +To post a comment in a particular line of a particular file, you must specify +the full commit SHA, the `path`, the `line`, and `line_type` should be `new`. The comment is added at the end of the last commit if at least one of the cases below is valid: diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 1b9778a01b3..68d339837b2 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Container Registry API **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55978) in GitLab 11.8. -> - The use of `CI_JOB_TOKEN` scoped to the current project was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49750) in GitLab 13.12. +> The use of `CI_JOB_TOKEN` scoped to the current project was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49750) in GitLab 13.12. This is the API documentation of the [GitLab Container Registry](../user/packages/container_registry/index.md). @@ -395,7 +394,7 @@ The number of tags deleted by this API is limited on GitLab.com because of the scale of the Container Registry there. If your Container Registry has a large number of tags to delete, only some of them will be deleted, and you might need to call this API multiple times. -To schedule tags for automatic deletion, use a [cleanup policy](../user/packages/container_registry/index.md#cleanup-policy) instead. +To schedule tags for automatic deletion, use a [cleanup policy](../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy) instead. NOTE: In GitLab 12.4 and later, individual tags are deleted. diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 1ecb78aa26d..6fb99d11f4f 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -16,7 +16,7 @@ across GitLab releases. Every call to this endpoint requires authentication. To perform this call, user should be authorized to read repository. To see vulnerabilities in response, user should be authorized to read -[Project Security Dashboard](../user/application_security/security_dashboard/index.md#project-security-dashboard). +[Project Security Dashboard](../user/application_security/security_dashboard/index.md). ## List project dependencies diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 253bc76737b..70b3e76c3dd 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -375,3 +375,38 @@ It supports the same parameters as the [Merge Requests API](merge_requests.md#li ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42/merge_requests" ``` + +## Approve or reject a blocked deployment **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `deployment_approvals`. Disabled by default. This feature is not ready for production use. + +```plaintext +POST /projects/:id/deployments/:deployment_id/approval +``` + +| Attribute | Type | Required | Description | +|-----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `deployment_id` | integer | yes | The ID of the deployment. | +| `status` | string | yes | The status of the approval (either `approved` or `rejected`). | + +```shell +curl --data "status=approved" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/1/approval" +``` + +Example response: + +```json +{ + "user": { + "name": "Administrator", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://localhost:3000/root" + }, + "status": "approved" +} +``` diff --git a/doc/api/epics.md b/doc/api/epics.md index 6d572303460..f3137559220 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -64,6 +64,7 @@ GET /groups/:id/epics?state=opened | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `author_id` | integer | no | Return epics created by the given user `id` | +| `author_username` | string | no | Return epics created by the user with the given `username`. Available in [GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/348257) and later | | `labels` | string | no | Return epics matching a comma-separated list of labels names. Label names from the epic group or a parent group can be used | | `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Available in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) and later | | `order_by` | string | no | Return epics ordered by `created_at`, `updated_at`, or `title` fields. Default is `created_at` | @@ -77,7 +78,7 @@ GET /groups/:id/epics?state=opened | `include_ancestor_groups` | boolean | no | Include epics from the requested group's ancestors. Default is `false` | | `include_descendant_groups` | boolean | no | Include epics from the requested group's descendants. Default is `true` | | `my_reaction_emoji` | string | no | Return epics reacted by the authenticated user by the given emoji. `None` returns epics not given a reaction. `Any` returns epics given at least one reaction. Available in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31479) and later | -| `not` | Hash | no | Return epics that do not match the parameters supplied. Accepts: `author_id` and `labels`. Available in [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/347525) and later | +| `not` | Hash | no | Return epics that do not match the parameters supplied. Accepts: `author_id`, `author_username` ([GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/348257) and later) and `labels`. Available in [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/347525) and later | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics" @@ -366,21 +367,22 @@ PUT /groups/:id/epics/:epic_iid | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `epic_iid` | integer/string | yes | The internal ID of the epic | -| `title` | string | no | The title of an epic | -| `description` | string | no | The description of an epic. Limited to 1,048,576 characters. | +| `add_labels` | string | no | Comma-separated label names to add to an issue. | | `confidential` | boolean | no | Whether the epic should be confidential | +| `description` | string | no | The description of an epic. Limited to 1,048,576 characters. | +| `due_date_fixed` | string | no | The fixed due date of an epic (in GitLab 11.3 and later) | +| `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (in GitLab 11.3 and later) | | `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | -| `add_labels` | string | no | Comma-separated label names to add to an issue. | +| `parent_id` | integer/string | no | The ID of a parent epic. Available in [GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/issues/348123) and later | | `remove_labels` | string | no | Comma-separated label names to remove from an issue. | -| `updated_at` | string | no | When the epic was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([available](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5 and later) | -| `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (in GitLab 11.3 and later) | | `start_date_fixed` | string | no | The fixed start date of an epic (in GitLab 11.3 and later) | -| `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (in GitLab 11.3 and later) | -| `due_date_fixed` | string | no | The fixed due date of an epic (in GitLab 11.3 and later) | +| `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (in GitLab 11.3 and later) | | `state_event` | string | no | State event for an epic. Set `close` to close the epic and `reopen` to reopen it (in GitLab 11.4 and later) | +| `title` | string | no | The title of an epic | +| `updated_at` | string | no | When the epic was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([available](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5 and later) | ```shell -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title" +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title&parent_id=29" ``` Example response: @@ -390,8 +392,8 @@ Example response: "id": 33, "iid": 6, "group_id": 7, - "parent_id": null, - "parent_iid": null, + "parent_id": 29, + "parent_iid": 4, "title": "New Title", "description": "Epic description", "state": "opened", diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 3952a87e698..fe1674649b6 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -62,7 +62,7 @@ Example response: "container_repositories_max_capacity": 10, "sync_object_storage": false, "clone_protocol": "http", - "web_edit_url": "https://primary.example.com/admin/geo/nodes/3/edit", + "web_edit_url": "https://primary.example.com/admin/geo/sites/3/edit", "web_geo_projects_url": "http://secondary.example.com/admin/geo/projects", "_links": { "self": "https://primary.example.com/api/v4/geo_nodes/3", @@ -103,7 +103,7 @@ Example response: "selective_sync_namespace_ids": [1, 25], "minimum_reverification_interval": 7, "clone_protocol": "http", - "web_edit_url": "https://primary.example.com/admin/geo/nodes/1/edit", + "web_edit_url": "https://primary.example.com/admin/geo/sites/1/edit", "_links": { "self": "https://primary.example.com/api/v4/geo_nodes/1", "status":"https://primary.example.com/api/v4/geo_nodes/1/status", @@ -128,7 +128,7 @@ Example response: "minimum_reverification_interval": 7, "sync_object_storage": true, "clone_protocol": "http", - "web_edit_url": "https://primary.example.com/admin/geo/nodes/2/edit", + "web_edit_url": "https://primary.example.com/admin/geo/sites/2/edit", "web_geo_projects_url": "https://secondary.example.com/admin/geo/projects", "_links": { "self":"https://primary.example.com/api/v4/geo_nodes/2", @@ -169,7 +169,7 @@ Example response: "selective_sync_namespace_ids": [1, 25], "minimum_reverification_interval": 7, "clone_protocol": "http", - "web_edit_url": "https://primary.example.com/admin/geo/nodes/1/edit", + "web_edit_url": "https://primary.example.com/admin/geo/sites/1/edit", "_links": { "self": "https://primary.example.com/api/v4/geo_nodes/1", "status":"https://primary.example.com/api/v4/geo_nodes/1/status", @@ -226,7 +226,7 @@ Example response: "minimum_reverification_interval": 7, "sync_object_storage": true, "clone_protocol": "http", - "web_edit_url": "https://primary.example.com/admin/geo/nodes/2/edit", + "web_edit_url": "https://primary.example.com/admin/geo/sites/2/edit", "web_geo_projects_url": "https://secondary.example.com/admin/geo/projects", "_links": { "self":"https://primary.example.com/api/v4/geo_nodes/2", @@ -277,7 +277,7 @@ Example response: "container_repositories_max_capacity": 10, "verification_max_capacity": 100, "clone_protocol": "http", - "web_edit_url": "https://primary.example.com/admin/geo/nodes/1/edit", + "web_edit_url": "https://primary.example.com/admin/geo/sites/1/edit", "_links": { "self": "https://primary.example.com/api/v4/geo_nodes/1", "status":"https://primary.example.com/api/v4/geo_nodes/1/status", diff --git a/doc/api/graphql/getting_started.md b/doc/api/graphql/getting_started.md index e3cf81148c2..258f781528b 100644 --- a/doc/api/graphql/getting_started.md +++ b/doc/api/graphql/getting_started.md @@ -44,8 +44,7 @@ you to explore the schema and types. 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. +- Can be run directly against GitLab. - 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). @@ -60,7 +59,7 @@ either: Refer to [running GraphiQL](index.md#graphiql) for more information. NOTE: -If you are running GitLab 11.0 to 12.0, enable the `graphql` +If you are running GitLab 12.0, enable the `graphql` [feature flag](../features.md#set-or-create-a-feature). ## Queries and mutations diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index bcaa5930faf..14512286ade 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GraphQL API **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19008) in GitLab 11.0 [with a flag](../../administration/feature_flags.md) named `graphql`. -> - [Enabled](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. +> [Generally available](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. [Feature flag `graphql`](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) removed. [GraphQL](https://graphql.org/) is a query language for APIs. You can use it to request the exact data you need, and therefore limit the number of requests you need. diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 123e65162d8..3148fd1a6df 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -73,7 +73,7 @@ Returns [`CiConfig`](#ciconfig). ### `Query.ciMinutesUsage` -Monthly CI minutes usage data for the current user. +CI/CD minutes usage data for a namespace. Returns [`CiMinutesNamespaceMonthlyUsageConnection`](#ciminutesnamespacemonthlyusageconnection). @@ -81,6 +81,12 @@ This field returns a [connection](#connections). It accepts the four standard [pagination arguments](#connection-pagination-arguments): `before: String`, `after: String`, `first: Int`, `last: Int`. +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="queryciminutesusagenamespaceid"></a>`namespaceId` | [`NamespaceID`](#namespaceid) | Global ID of the Namespace for the monthly CI/CD minutes usage. | + ### `Query.containerRepository` Find a container repository. @@ -948,6 +954,10 @@ Input type: `ClusterAgentTokenCreateInput` ### `Mutation.clusterAgentTokenDelete` +WARNING: +**Deprecated** in 14.7. +Tokens must be revoked with ClusterAgentTokenRevoke. + Input type: `ClusterAgentTokenDeleteInput` #### Arguments @@ -964,6 +974,24 @@ Input type: `ClusterAgentTokenDeleteInput` | <a id="mutationclusteragenttokendeleteclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationclusteragenttokendeleteerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.clusterAgentTokenRevoke` + +Input type: `ClusterAgentTokenRevokeInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationclusteragenttokenrevokeclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationclusteragenttokenrevokeid"></a>`id` | [`ClustersAgentTokenID!`](#clustersagenttokenid) | Global ID of the agent token that will be revoked. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationclusteragenttokenrevokeclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationclusteragenttokenrevokeerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.commitCreate` Input type: `CommitCreateInput` @@ -2913,6 +2941,48 @@ Input type: `IssueSetEpicInput` | <a id="mutationissuesetepicerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationissuesetepicissue"></a>`issue` | [`Issue`](#issue) | Issue after mutation. | +### `Mutation.issueSetEscalationPolicy` + +Input type: `IssueSetEscalationPolicyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuesetescalationpolicyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuesetescalationpolicyescalationpolicyid"></a>`escalationPolicyId` | [`IncidentManagementEscalationPolicyID`](#incidentmanagementescalationpolicyid) | Global ID of the escalation policy to assign to the issue. Policy will be removed if absent or set to null. | +| <a id="mutationissuesetescalationpolicyiid"></a>`iid` | [`String!`](#string) | IID of the issue to mutate. | +| <a id="mutationissuesetescalationpolicyprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the issue to mutate is in. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuesetescalationpolicyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuesetescalationpolicyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationissuesetescalationpolicyissue"></a>`issue` | [`Issue`](#issue) | Issue after mutation. | + +### `Mutation.issueSetEscalationStatus` + +Input type: `IssueSetEscalationStatusInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuesetescalationstatusclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuesetescalationstatusiid"></a>`iid` | [`String!`](#string) | IID of the issue to mutate. | +| <a id="mutationissuesetescalationstatusprojectpath"></a>`projectPath` | [`ID!`](#id) | Project the issue to mutate is in. | +| <a id="mutationissuesetescalationstatusstatus"></a>`status` | [`IssueEscalationStatus!`](#issueescalationstatus) | Set the escalation status. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationissuesetescalationstatusclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationissuesetescalationstatuserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationissuesetescalationstatusissue"></a>`issue` | [`Issue`](#issue) | Issue after mutation. | + ### `Mutation.issueSetIteration` Input type: `IssueSetIterationInput` @@ -4266,6 +4336,25 @@ Input type: `TerraformStateUnlockInput` | <a id="mutationterraformstateunlockclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationterraformstateunlockerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.timelineEventDestroy` + +Input type: `TimelineEventDestroyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationtimelineeventdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationtimelineeventdestroyid"></a>`id` | [`IncidentManagementTimelineEventID!`](#incidentmanagementtimelineeventid) | Timeline event ID to remove. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationtimelineeventdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationtimelineeventdestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationtimelineeventdestroytimelineevent"></a>`timelineEvent` | [`TimelineEventType`](#timelineeventtype) | Timeline event. | + ### `Mutation.todoCreate` Input type: `TodoCreateInput` @@ -4907,6 +4996,27 @@ Input type: `VulnerabilityExternalIssueLinkDestroyInput` | <a id="mutationvulnerabilityexternalissuelinkdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationvulnerabilityexternalissuelinkdestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.vulnerabilityFindingDismiss` + +Input type: `VulnerabilityFindingDismissInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationvulnerabilityfindingdismissclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationvulnerabilityfindingdismisscomment"></a>`comment` | [`String`](#string) | Comment why finding should be dismissed. | +| <a id="mutationvulnerabilityfindingdismissdismissalreason"></a>`dismissalReason` | [`VulnerabilityDismissalReason`](#vulnerabilitydismissalreason) | Reason why finding should be dismissed. | +| <a id="mutationvulnerabilityfindingdismissid"></a>`id` | [`VulnerabilitiesFindingID!`](#vulnerabilitiesfindingid) | ID of the finding to be dismissed. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationvulnerabilityfindingdismissclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationvulnerabilityfindingdismisserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationvulnerabilityfindingdismissfinding"></a>`finding` | [`PipelineSecurityReportFinding`](#pipelinesecurityreportfinding) | Finding after dismissal. | + ### `Mutation.vulnerabilityResolve` Input type: `VulnerabilityResolveInput` @@ -4945,6 +5055,30 @@ Input type: `VulnerabilityRevertToDetectedInput` | <a id="mutationvulnerabilityreverttodetectederrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationvulnerabilityreverttodetectedvulnerability"></a>`vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after revert. | +### `Mutation.workItemCreate` + +Available only when feature flag `work_items` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. + +Input type: `WorkItemCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationworkitemcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationworkitemcreatedescription"></a>`description` | [`String`](#string) | Description of the work item. | +| <a id="mutationworkitemcreateprojectpath"></a>`projectPath` | [`ID!`](#id) | Full path of the project the work item is associated with. | +| <a id="mutationworkitemcreatetitle"></a>`title` | [`String!`](#string) | Title of the work item. | +| <a id="mutationworkitemcreateworkitemtypeid"></a>`workItemTypeId` | [`WorkItemsTypeID!`](#workitemstypeid) | Global ID of a work item type. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationworkitemcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationworkitemcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationworkitemcreateworkitem"></a>`workItem` | [`WorkItem`](#workitem) | Created work item. | + ## Connections Some types in our schema are `Connection` types - they represent a paginated @@ -5430,6 +5564,7 @@ The connection type for [`CiRunner`](#cirunner). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="cirunnerconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="cirunnerconnectionedges"></a>`edges` | [`[CiRunnerEdge]`](#cirunneredge) | A list of edges. | | <a id="cirunnerconnectionnodes"></a>`nodes` | [`[CiRunner]`](#cirunner) | A list of nodes. | | <a id="cirunnerconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | @@ -7439,6 +7574,29 @@ The edge type for [`ScanExecutionPolicy`](#scanexecutionpolicy). | <a id="scanexecutionpolicyedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="scanexecutionpolicyedgenode"></a>`node` | [`ScanExecutionPolicy`](#scanexecutionpolicy) | The item at the end of the edge. | +#### `ScanResultPolicyConnection` + +The connection type for [`ScanResultPolicy`](#scanresultpolicy). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="scanresultpolicyconnectionedges"></a>`edges` | [`[ScanResultPolicyEdge]`](#scanresultpolicyedge) | A list of edges. | +| <a id="scanresultpolicyconnectionnodes"></a>`nodes` | [`[ScanResultPolicy]`](#scanresultpolicy) | A list of nodes. | +| <a id="scanresultpolicyconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ScanResultPolicyEdge` + +The edge type for [`ScanResultPolicy`](#scanresultpolicy). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="scanresultpolicyedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="scanresultpolicyedgenode"></a>`node` | [`ScanResultPolicy`](#scanresultpolicy) | The item at the end of the edge. | + #### `ScannedResourceConnection` The connection type for [`ScannedResource`](#scannedresource). @@ -7741,6 +7899,29 @@ The edge type for [`TestSuiteSummary`](#testsuitesummary). | <a id="testsuitesummaryedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="testsuitesummaryedgenode"></a>`node` | [`TestSuiteSummary`](#testsuitesummary) | The item at the end of the edge. | +#### `TimelineEventTypeConnection` + +The connection type for [`TimelineEventType`](#timelineeventtype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="timelineeventtypeconnectionedges"></a>`edges` | [`[TimelineEventTypeEdge]`](#timelineeventtypeedge) | A list of edges. | +| <a id="timelineeventtypeconnectionnodes"></a>`nodes` | [`[TimelineEventType]`](#timelineeventtype) | A list of nodes. | +| <a id="timelineeventtypeconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `TimelineEventTypeEdge` + +The edge type for [`TimelineEventType`](#timelineeventtype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="timelineeventtypeedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="timelineeventtypeedgenode"></a>`node` | [`TimelineEventType`](#timelineeventtype) | The item at the end of the edge. | + #### `TimelogConnection` The connection type for [`Timelog`](#timelog). @@ -8063,6 +8244,29 @@ The edge type for [`VulnerabilityScanner`](#vulnerabilityscanner). | <a id="vulnerabilityscanneredgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="vulnerabilityscanneredgenode"></a>`node` | [`VulnerabilityScanner`](#vulnerabilityscanner) | The item at the end of the edge. | +#### `WorkItemTypeConnection` + +The connection type for [`WorkItemType`](#workitemtype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemtypeconnectionedges"></a>`edges` | [`[WorkItemTypeEdge]`](#workitemtypeedge) | A list of edges. | +| <a id="workitemtypeconnectionnodes"></a>`nodes` | [`[WorkItemType]`](#workitemtype) | A list of nodes. | +| <a id="workitemtypeconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `WorkItemTypeEdge` + +The edge type for [`WorkItemType`](#workitemtype). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemtypeedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="workitemtypeedgenode"></a>`node` | [`WorkItemType`](#workitemtype) | The item at the end of the edge. | + ## Object types Object types represent the resources that the GitLab GraphQL API can return. @@ -8655,6 +8859,7 @@ Represents the total number of issues and their weights for a particular day. | <a id="ciconfigmergedyaml"></a>`mergedYaml` | [`String`](#string) | Merged CI configuration YAML. | | <a id="ciconfigstages"></a>`stages` | [`CiConfigStageConnection`](#ciconfigstageconnection) | Stages of the pipeline. (see [Connections](#connections)) | | <a id="ciconfigstatus"></a>`status` | [`CiConfigStatus`](#ciconfigstatus) | Status of linting, can be either valid or invalid. | +| <a id="ciconfigwarnings"></a>`warnings` | [`[String!]`](#string) | Linting warnings. | ### `CiConfigGroup` @@ -8738,6 +8943,7 @@ Represents the total number of issues and their weights for a particular day. | <a id="cijobcreatedat"></a>`createdAt` | [`Time!`](#time) | When the job was created. | | <a id="cijobcreatedbytag"></a>`createdByTag` | [`Boolean!`](#boolean) | Whether the job was created by a tag. | | <a id="cijobdetailedstatus"></a>`detailedStatus` | [`DetailedStatus`](#detailedstatus) | Detailed status of the job. | +| <a id="cijobdownstreampipeline"></a>`downstreamPipeline` | [`Pipeline`](#pipeline) | Downstream pipeline for a bridge. | | <a id="cijobduration"></a>`duration` | [`Int`](#int) | Duration of the job in seconds. | | <a id="cijobfinishedat"></a>`finishedAt` | [`Time`](#time) | When a job has finished running. | | <a id="cijobid"></a>`id` | [`JobID`](#jobid) | ID of the job. | @@ -8789,6 +8995,7 @@ Represents the total number of issues and their weights for a particular day. | ---- | ---- | ----------- | | <a id="ciminutesnamespacemonthlyusageminutes"></a>`minutes` | [`Int`](#int) | Total number of minutes used by all projects in the namespace. | | <a id="ciminutesnamespacemonthlyusagemonth"></a>`month` | [`String`](#string) | Month related to the usage data. | +| <a id="ciminutesnamespacemonthlyusagemonthiso8601"></a>`monthIso8601` | [`ISO8601Date`](#iso8601date) | Month related to the usage data in ISO 8601 date format. | | <a id="ciminutesnamespacemonthlyusageprojects"></a>`projects` | [`CiMinutesProjectMonthlyUsageConnection`](#ciminutesprojectmonthlyusageconnection) | CI minutes usage data for projects in the namespace. (see [Connections](#connections)) | | <a id="ciminutesnamespacemonthlyusagesharedrunnersduration"></a>`sharedRunnersDuration` | [`Int`](#int) | Total numbers of minutes used by the shared runners in the namespace. | @@ -8810,8 +9017,11 @@ Represents the total number of issues and their weights for a particular day. | <a id="cirunneraccesslevel"></a>`accessLevel` | [`CiRunnerAccessLevel!`](#cirunneraccesslevel) | Access level of the runner. | | <a id="cirunneractive"></a>`active` | [`Boolean!`](#boolean) | Indicates the runner is allowed to receive jobs. | | <a id="cirunneradminurl"></a>`adminUrl` | [`String`](#string) | Admin URL of the runner. Only available for administrators. | -| <a id="cirunnercontactedat"></a>`contactedAt` | [`Time`](#time) | Last contact from the runner. | +| <a id="cirunnercontactedat"></a>`contactedAt` | [`Time`](#time) | Timestamp of last contact from this runner. | +| <a id="cirunnercreatedat"></a>`createdAt` | [`Time`](#time) | Timestamp of creation of this runner. | | <a id="cirunnerdescription"></a>`description` | [`String`](#string) | Description of the runner. | +| <a id="cirunnereditadminurl"></a>`editAdminUrl` | [`String`](#string) | Admin form URL of the runner. Only available for administrators. | +| <a id="cirunnerexecutorname"></a>`executorName` | [`String`](#string) | Executor last advertised by the runner. Available only when feature flag `graphql_ci_runner_executor` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | | <a id="cirunnerid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner. | | <a id="cirunneripaddress"></a>`ipAddress` | [`String`](#string) | IP address of the runner. | | <a id="cirunnerjobcount"></a>`jobCount` | [`Int`](#int) | Number of jobs processed by the runner (limited to 1000, plus one to indicate that more items exist). | @@ -8879,10 +9089,27 @@ GitLab CI/CD configuration template. | <a id="clusteragentid"></a>`id` | [`ID!`](#id) | ID of the cluster agent. | | <a id="clusteragentname"></a>`name` | [`String`](#string) | Name of the cluster agent. | | <a id="clusteragentproject"></a>`project` | [`Project`](#project) | Project this cluster agent is associated with. | -| <a id="clusteragenttokens"></a>`tokens` | [`ClusterAgentTokenConnection`](#clusteragenttokenconnection) | Tokens associated with the cluster agent. (see [Connections](#connections)) | | <a id="clusteragentupdatedat"></a>`updatedAt` | [`Time`](#time) | Timestamp the cluster agent was updated. | | <a id="clusteragentwebpath"></a>`webPath` | [`String`](#string) | Web path of the cluster agent. | +#### Fields with arguments + +##### `ClusterAgent.tokens` + +Tokens associated with the cluster agent. + +Returns [`ClusterAgentTokenConnection`](#clusteragenttokenconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="clusteragenttokensstatus"></a>`status` | [`AgentTokenStatus`](#agenttokenstatus) | Status of the token. | + ### `ClusterAgentActivityEvent` #### Fields @@ -8908,6 +9135,7 @@ GitLab CI/CD configuration template. | <a id="clusteragenttokenid"></a>`id` | [`ClustersAgentTokenID!`](#clustersagenttokenid) | Global ID of the token. | | <a id="clusteragenttokenlastusedat"></a>`lastUsedAt` | [`Time`](#time) | Timestamp the token was last used. | | <a id="clusteragenttokenname"></a>`name` | [`String`](#string) | Name given to the token. | +| <a id="clusteragenttokenstatus"></a>`status` | [`AgentTokenStatus`](#agenttokenstatus) | Current status of the token. | ### `CodeCoverageActivity` @@ -8955,6 +9183,7 @@ Represents a code quality degradation on the pipeline. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="commitauthor"></a>`author` | [`UserCore`](#usercore) | Author of the commit. | +| <a id="commitauthoremail"></a>`authorEmail` | [`String`](#string) | Commit author's email. | | <a id="commitauthorgravatar"></a>`authorGravatar` | [`String`](#string) | Commit authors gravatar. | | <a id="commitauthorname"></a>`authorName` | [`String`](#string) | Commit authors name. | | <a id="commitauthoreddate"></a>`authoredDate` | [`Time`](#time) | Timestamp of when the commit was authored. | @@ -8991,7 +9220,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="commitpipelinesref"></a>`ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | | <a id="commitpipelinesscope"></a>`scope` | [`PipelineScopeEnum`](#pipelinescopeenum) | Filter pipelines by scope. | | <a id="commitpipelinessha"></a>`sha` | [`String`](#string) | Filter pipelines by the sha of the commit they are run for. | -| <a id="commitpipelinessource"></a>`source` | [`String`](#string) | Filter pipelines by their source. Will be ignored if `dast_view_scans` feature flag is disabled. | +| <a id="commitpipelinessource"></a>`source` | [`String`](#string) | Filter pipelines by their source. | | <a id="commitpipelinesstatus"></a>`status` | [`PipelineStatusEnum`](#pipelinestatusenum) | Filter pipelines by their status. | ### `ComplianceFramework` @@ -10127,6 +10356,8 @@ Relationship between an epic and an issue. | <a id="epicissueemailsdisabled"></a>`emailsDisabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `true` if email notifications are disabled. | | <a id="epicissueepic"></a>`epic` | [`Epic`](#epic) | Epic to which this issue belongs. | | <a id="epicissueepicissueid"></a>`epicIssueId` | [`ID!`](#id) | ID of the epic-issue relation. | +| <a id="epicissueescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy associated with the issue. Available for issues which support escalation. | +| <a id="epicissueescalationstatus"></a>`escalationStatus` | [`IssueEscalationStatus`](#issueescalationstatus) | Escalation status of the issue. | | <a id="epicissuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Current health status. | | <a id="epicissuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. Will always return `null` if `ban_user_feature_flag` feature flag is disabled. | | <a id="epicissuehumantimeestimate"></a>`humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the issue. | @@ -10556,6 +10787,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupvisibility"></a>`visibility` | [`String`](#string) | Visibility of the namespace. | | <a id="groupvulnerabilityscanners"></a>`vulnerabilityScanners` | [`VulnerabilityScannerConnection`](#vulnerabilityscannerconnection) | Vulnerability scanners reported on the project vulnerabilities of the group and its subgroups. (see [Connections](#connections)) | | <a id="groupweburl"></a>`webUrl` | [`String!`](#string) | Web URL of the group. | +| <a id="groupworkitemtypes"></a>`workItemTypes` | [`WorkItemTypeConnection`](#workitemtypeconnection) | Work item types available to the group. Available only when feature flag `work_items` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) | #### Fields with arguments @@ -10882,6 +11114,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="groupmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="groupmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="groupmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="groupmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="groupmergerequestsincludesubgroups"></a>`includeSubgroups` | [`Boolean`](#boolean) | Include merge requests belonging to subgroups. | | <a id="groupmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | @@ -11308,6 +11541,8 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | <a id="issueduedate"></a>`dueDate` | [`Time`](#time) | Due date of the issue. | | <a id="issueemailsdisabled"></a>`emailsDisabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `true` if email notifications are disabled. | | <a id="issueepic"></a>`epic` | [`Epic`](#epic) | Epic to which this issue belongs. | +| <a id="issueescalationpolicy"></a>`escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy associated with the issue. Available for issues which support escalation. | +| <a id="issueescalationstatus"></a>`escalationStatus` | [`IssueEscalationStatus`](#issueescalationstatus) | Escalation status of the issue. | | <a id="issuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Current health status. | | <a id="issuehidden"></a>`hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. Will always return `null` if `ban_user_feature_flag` feature flag is disabled. | | <a id="issuehumantimeestimate"></a>`humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the issue. | @@ -11424,6 +11659,7 @@ Represents an iteration object. | <a id="iterationreport"></a>`report` | [`TimeboxReport`](#timeboxreport) | Historically accurate report about the timebox. | | <a id="iterationscopedpath"></a>`scopedPath` | [`String`](#string) | Web path of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts. | | <a id="iterationscopedurl"></a>`scopedUrl` | [`String`](#string) | Web URL of the iteration, scoped to the query parent. Only valid for Project parents. Returns null in other contexts. | +| <a id="iterationsequence"></a>`sequence` | [`Int!`](#int) | Sequence number for the iteration when you sort the containing cadence's iterations by the start and end date. The earliest starting and ending iteration is assigned 1. | | <a id="iterationstartdate"></a>`startDate` | [`Time`](#time) | Timestamp of the iteration start date. | | <a id="iterationstate"></a>`state` | [`IterationState!`](#iterationstate) | State of the iteration. | | <a id="iterationtitle"></a>`title` | [`String!`](#string) | Title of the iteration. | @@ -11620,6 +11856,7 @@ Maven metadata. | <a id="mergerequestautomergestrategy"></a>`autoMergeStrategy` | [`String`](#string) | Selected auto merge strategy. | | <a id="mergerequestavailableautomergestrategies"></a>`availableAutoMergeStrategies` | [`[String!]`](#string) | Array of available auto merge strategies. | | <a id="mergerequestcommitcount"></a>`commitCount` | [`Int`](#int) | Number of commits in the merge request. | +| <a id="mergerequestcommits"></a>`commits` | [`CommitConnection`](#commitconnection) | Merge request commits. (see [Connections](#connections)) | | <a id="mergerequestcommitswithoutmergecommits"></a>`commitsWithoutMergeCommits` | [`CommitConnection`](#commitconnection) | Merge request commits excluding merge commits. (see [Connections](#connections)) | | <a id="mergerequestconflicts"></a>`conflicts` | [`Boolean!`](#boolean) | Indicates if the merge request has conflicts. | | <a id="mergerequestcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the merge request was created. | @@ -11652,7 +11889,7 @@ Maven metadata. | <a id="mergerequestmergestatus"></a>`mergeStatus` **{warning-solid}** | [`String`](#string) | **Deprecated** in 14.0. This was renamed. Use: [`MergeRequest.mergeStatusEnum`](#mergerequestmergestatusenum). | | <a id="mergerequestmergestatusenum"></a>`mergeStatusEnum` | [`MergeStatus`](#mergestatus) | Merge status of the merge request. | | <a id="mergerequestmergetrainscount"></a>`mergeTrainsCount` | [`Int`](#int) | Number of merge requests in the merge train. | -| <a id="mergerequestmergeuser"></a>`mergeUser` | [`UserCore`](#usercore) | User who merged this merge request. | +| <a id="mergerequestmergeuser"></a>`mergeUser` | [`UserCore`](#usercore) | User who merged this merge request or set it to merge when pipeline succeeds. | | <a id="mergerequestmergewhenpipelinesucceeds"></a>`mergeWhenPipelineSucceeds` | [`Boolean`](#boolean) | Indicates if the merge has been set to be merged when its pipeline succeeds (MWPS). | | <a id="mergerequestmergeable"></a>`mergeable` | [`Boolean!`](#boolean) | Indicates if the merge request is mergeable. | | <a id="mergerequestmergeablediscussionsstate"></a>`mergeableDiscussionsState` | [`Boolean`](#boolean) | Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged. | @@ -11742,7 +11979,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestpipelinesref"></a>`ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | | <a id="mergerequestpipelinesscope"></a>`scope` | [`PipelineScopeEnum`](#pipelinescopeenum) | Filter pipelines by scope. | | <a id="mergerequestpipelinessha"></a>`sha` | [`String`](#string) | Filter pipelines by the sha of the commit they are run for. | -| <a id="mergerequestpipelinessource"></a>`source` | [`String`](#string) | Filter pipelines by their source. Will be ignored if `dast_view_scans` feature flag is disabled. | +| <a id="mergerequestpipelinessource"></a>`source` | [`String`](#string) | Filter pipelines by their source. | | <a id="mergerequestpipelinesstatus"></a>`status` | [`PipelineStatusEnum`](#pipelinestatusenum) | Filter pipelines by their status. | ##### `MergeRequest.reference` @@ -11815,6 +12052,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestassigneeassignedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="mergerequestassigneeassignedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="mergerequestassigneeassignedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="mergerequestassigneeassignedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="mergerequestassigneeassignedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="mergerequestassigneeassignedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="mergerequestassigneeassignedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -11846,6 +12084,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestassigneeauthoredmergerequestsassigneeusername"></a>`assigneeUsername` | [`String`](#string) | Username of the assignee. | | <a id="mergerequestassigneeauthoredmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="mergerequestassigneeauthoredmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="mergerequestassigneeauthoredmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="mergerequestassigneeauthoredmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="mergerequestassigneeauthoredmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="mergerequestassigneeauthoredmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -11862,7 +12101,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `MergeRequestAssignee.groups` -Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. +Groups where the user has access. Returns [`GroupConnection`](#groupconnection). @@ -11895,6 +12134,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestassigneereviewrequestedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="mergerequestassigneereviewrequestedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="mergerequestassigneereviewrequestedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="mergerequestassigneereviewrequestedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="mergerequestassigneereviewrequestedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="mergerequestassigneereviewrequestedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="mergerequestassigneereviewrequestedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -12067,6 +12307,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestreviewerassignedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="mergerequestreviewerassignedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="mergerequestreviewerassignedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="mergerequestreviewerassignedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="mergerequestreviewerassignedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="mergerequestreviewerassignedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="mergerequestreviewerassignedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -12098,6 +12339,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestreviewerauthoredmergerequestsassigneeusername"></a>`assigneeUsername` | [`String`](#string) | Username of the assignee. | | <a id="mergerequestreviewerauthoredmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="mergerequestreviewerauthoredmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="mergerequestreviewerauthoredmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="mergerequestreviewerauthoredmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="mergerequestreviewerauthoredmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="mergerequestreviewerauthoredmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -12114,7 +12356,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `MergeRequestReviewer.groups` -Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. +Groups where the user has access. Returns [`GroupConnection`](#groupconnection). @@ -12147,6 +12389,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="mergerequestreviewerreviewrequestedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="mergerequestreviewerreviewrequestedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="mergerequestreviewerreviewrequestedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="mergerequestreviewerreviewrequestedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="mergerequestreviewerreviewrequestedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="mergerequestreviewerreviewrequestedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="mergerequestreviewerreviewrequestedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -12577,15 +12820,23 @@ Represents a package details in the Package Registry. Note that this type is in | Name | Type | Description | | ---- | ---- | ----------- | | <a id="packagedetailstypecandestroy"></a>`canDestroy` | [`Boolean!`](#boolean) | Whether the user can destroy the package. | +| <a id="packagedetailstypecomposerconfigrepositoryurl"></a>`composerConfigRepositoryUrl` | [`String`](#string) | Url of the Composer setup endpoint. | +| <a id="packagedetailstypecomposerurl"></a>`composerUrl` | [`String`](#string) | Url of the Composer endpoint. | +| <a id="packagedetailstypeconanurl"></a>`conanUrl` | [`String`](#string) | Url of the Conan project endpoint. | | <a id="packagedetailstypecreatedat"></a>`createdAt` | [`Time!`](#time) | Date of creation. | | <a id="packagedetailstypedependencylinks"></a>`dependencyLinks` | [`PackageDependencyLinkConnection`](#packagedependencylinkconnection) | Dependency link. (see [Connections](#connections)) | | <a id="packagedetailstypeid"></a>`id` | [`PackagesPackageID!`](#packagespackageid) | ID of the package. | +| <a id="packagedetailstypemavenurl"></a>`mavenUrl` | [`String`](#string) | Url of the Maven project endpoint. | | <a id="packagedetailstypemetadata"></a>`metadata` | [`PackageMetadata`](#packagemetadata) | Package metadata. | | <a id="packagedetailstypename"></a>`name` | [`String!`](#string) | Name of the package. | +| <a id="packagedetailstypenpmurl"></a>`npmUrl` | [`String`](#string) | Url of the NPM project endpoint. | +| <a id="packagedetailstypenugeturl"></a>`nugetUrl` | [`String`](#string) | Url of the Nuget project endpoint. | | <a id="packagedetailstypepackagefiles"></a>`packageFiles` | [`PackageFileConnection`](#packagefileconnection) | Package files. (see [Connections](#connections)) | | <a id="packagedetailstypepackagetype"></a>`packageType` | [`PackageTypeEnum!`](#packagetypeenum) | Package type. | | <a id="packagedetailstypepipelines"></a>`pipelines` **{warning-solid}** | [`PipelineConnection`](#pipelineconnection) | **Deprecated** in 14.6. Due to scalability concerns, this field is going to be removed. | | <a id="packagedetailstypeproject"></a>`project` | [`Project!`](#project) | Project where the package is stored. | +| <a id="packagedetailstypepypisetupurl"></a>`pypiSetupUrl` | [`String`](#string) | Url of the PyPi project setup endpoint. | +| <a id="packagedetailstypepypiurl"></a>`pypiUrl` | [`String`](#string) | Url of the PyPi project endpoint. | | <a id="packagedetailstypestatus"></a>`status` | [`PackageStatus!`](#packagestatus) | Package status. | | <a id="packagedetailstypetags"></a>`tags` | [`PackageTagConnection`](#packagetagconnection) | Package tags. (see [Connections](#connections)) | | <a id="packagedetailstypeupdatedat"></a>`updatedAt` | [`Time!`](#time) | Date of most recent update. | @@ -12768,7 +13019,7 @@ Represents a file or directory in the project repository that has been locked. | <a id="pipelineconfigsource"></a>`configSource` | [`PipelineConfigSourceEnum`](#pipelineconfigsourceenum) | Configuration source of the pipeline (UNKNOWN_SOURCE, REPOSITORY_SOURCE, AUTO_DEVOPS_SOURCE, WEBIDE_SOURCE, REMOTE_SOURCE, EXTERNAL_PROJECT_SOURCE, BRIDGE_SOURCE, PARAMETER_SOURCE, COMPLIANCE_SOURCE). | | <a id="pipelinecoverage"></a>`coverage` | [`Float`](#float) | Coverage percentage. | | <a id="pipelinecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of the pipeline's creation. | -| <a id="pipelinedastprofile"></a>`dastProfile` | [`DastProfile`](#dastprofile) | DAST profile associated with the pipeline. Returns `null`if `dast_view_scans` feature flag is disabled. | +| <a id="pipelinedastprofile"></a>`dastProfile` | [`DastProfile`](#dastprofile) | DAST profile associated with the pipeline. | | <a id="pipelinedetailedstatus"></a>`detailedStatus` | [`DetailedStatus!`](#detailedstatus) | Detailed status of the pipeline. | | <a id="pipelinedownstream"></a>`downstream` | [`PipelineConnection`](#pipelineconnection) | Pipelines this pipeline will trigger. (see [Connections](#connections)) | | <a id="pipelineduration"></a>`duration` | [`Int`](#int) | Duration of the pipeline in seconds. | @@ -12780,9 +13031,9 @@ Represents a file or directory in the project repository that has been locked. | <a id="pipelineproject"></a>`project` | [`Project`](#project) | Project the pipeline belongs to. | | <a id="pipelinequeuedduration"></a>`queuedDuration` | [`Duration`](#duration) | How long the pipeline was queued before starting. | | <a id="pipelineref"></a>`ref` | [`String`](#string) | Reference to the branch from which the pipeline was triggered. | +| <a id="pipelinerefpath"></a>`refPath` | [`String`](#string) | Reference path to the branch from which the pipeline was triggered. | | <a id="pipelineretryable"></a>`retryable` | [`Boolean!`](#boolean) | Specifies if a pipeline can be retried. | | <a id="pipelinesecurityreportsummary"></a>`securityReportSummary` | [`SecurityReportSummary`](#securityreportsummary) | Vulnerability and scanned resource counts for each security scanner of the pipeline. | -| <a id="pipelinesha"></a>`sha` | [`String!`](#string) | SHA of the pipeline's commit. | | <a id="pipelinesourcejob"></a>`sourceJob` | [`CiJob`](#cijob) | Job where pipeline was triggered from. | | <a id="pipelinestages"></a>`stages` | [`CiStageConnection`](#cistageconnection) | Stages of the pipeline. (see [Connections](#connections)) | | <a id="pipelinestartedat"></a>`startedAt` | [`Time`](#time) | Timestamp when the pipeline was started. | @@ -12793,6 +13044,7 @@ Represents a file or directory in the project repository that has been locked. | <a id="pipelineuser"></a>`user` | [`UserCore`](#usercore) | Pipeline user. | | <a id="pipelineuserpermissions"></a>`userPermissions` | [`PipelinePermissions!`](#pipelinepermissions) | Permissions for the current user on the resource. | | <a id="pipelineusesneeds"></a>`usesNeeds` | [`Boolean`](#boolean) | Indicates if the pipeline has jobs with `needs` dependencies. | +| <a id="pipelinewarningmessages"></a>`warningMessages` | [`[PipelineMessage!]`](#pipelinemessage) | Pipeline warning messages. | | <a id="pipelinewarnings"></a>`warnings` | [`Boolean!`](#boolean) | Indicates if a pipeline has warnings. | #### Fields with arguments @@ -12846,6 +13098,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="pipelinesecurityreportfindingsseverity"></a>`severity` | [`[String!]`](#string) | Filter vulnerability findings by severity. | | <a id="pipelinesecurityreportfindingsstate"></a>`state` | [`[VulnerabilityState!]`](#vulnerabilitystate) | Filter vulnerability findings by state. | +##### `Pipeline.sha` + +SHA of the pipeline's commit. + +Returns [`String`](#string). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pipelineshaformat"></a>`format` | [`ShaFormat`](#shaformat) | Format of the SHA. | + ##### `Pipeline.testSuite` A specific test suite in a pipeline test report. @@ -12893,6 +13157,15 @@ Represents the Geo sync and verification state of a pipeline artifact. | <a id="pipelineartifactregistryretrycount"></a>`retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the PipelineArtifactRegistry. | | <a id="pipelineartifactregistrystate"></a>`state` | [`RegistryState`](#registrystate) | Sync state of the PipelineArtifactRegistry. | +### `PipelineMessage` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="pipelinemessagecontent"></a>`content` | [`String!`](#string) | Content of the pipeline message. | +| <a id="pipelinemessageid"></a>`id` | [`ID!`](#id) | ID of the pipeline message. | + ### `PipelinePermissions` #### Fields @@ -12989,6 +13262,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectrequestaccessenabled"></a>`requestAccessEnabled` | [`Boolean`](#boolean) | Indicates if users can request member access to the project. | | <a id="projectrequirementstatescount"></a>`requirementStatesCount` | [`RequirementStatesCount`](#requirementstatescount) | Number of requirements for the project by their state. | | <a id="projectsastciconfiguration"></a>`sastCiConfiguration` | [`SastCiConfiguration`](#sastciconfiguration) | SAST CI configuration for the project. | +| <a id="projectscanresultpolicies"></a>`scanResultPolicies` | [`ScanResultPolicyConnection`](#scanresultpolicyconnection) | Scan Result Policies of the project. (see [Connections](#connections)) | | <a id="projectsecuritydashboardpath"></a>`securityDashboardPath` | [`String`](#string) | Path to project's security dashboard. | | <a id="projectsecurityscanners"></a>`securityScanners` | [`SecurityScanners`](#securityscanners) | Information about security analyzers used in the project. | | <a id="projectsentryerrors"></a>`sentryErrors` | [`SentryErrorCollection`](#sentryerrorcollection) | Paginated collection of Sentry errors on the project. | @@ -13010,6 +13284,7 @@ Represents vulnerability finding of a security report on the pipeline. | <a id="projectvulnerabilityscanners"></a>`vulnerabilityScanners` | [`VulnerabilityScannerConnection`](#vulnerabilityscannerconnection) | Vulnerability scanners reported on the project vulnerabilities. (see [Connections](#connections)) | | <a id="projectweburl"></a>`webUrl` | [`String`](#string) | Web URL of the project. | | <a id="projectwikienabled"></a>`wikiEnabled` | [`Boolean`](#boolean) | Indicates if Wikis are enabled for the current user. | +| <a id="projectworkitemtypes"></a>`workItemTypes` | [`WorkItemTypeConnection`](#workitemtypeconnection) | Work item types available to the project. Available only when feature flag `work_items` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) | #### Fields with arguments @@ -13187,7 +13462,7 @@ Returns [`DastProfile`](#dastprofile). | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectdastprofilehasdastprofileschedule"></a>`hasDastProfileSchedule` | [`Boolean`](#boolean) | Filter DAST Profiles by whether or not they have a schedule. Will be ignored if `dast_view_scans` feature flag is disabled. | +| <a id="projectdastprofilehasdastprofileschedule"></a>`hasDastProfileSchedule` | [`Boolean`](#boolean) | Filter DAST Profiles by whether or not they have a schedule. | | <a id="projectdastprofileid"></a>`id` | [`DastProfileID!`](#dastprofileid) | ID of the DAST Profile. | ##### `Project.dastProfiles` @@ -13204,7 +13479,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="projectdastprofileshasdastprofileschedule"></a>`hasDastProfileSchedule` | [`Boolean`](#boolean) | Filter DAST Profiles by whether or not they have a schedule. Will be ignored if `dast_view_scans` feature flag is disabled. | +| <a id="projectdastprofileshasdastprofileschedule"></a>`hasDastProfileSchedule` | [`Boolean`](#boolean) | Filter DAST Profiles by whether or not they have a schedule. | ##### `Project.dastSiteProfile` @@ -13295,6 +13570,35 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="projectincidentmanagementoncallschedulesiids"></a>`iids` | [`[ID!]`](#id) | IIDs of on-call schedules. | +##### `Project.incidentManagementTimelineEvent` + +Incident Management Timeline event associated with the incident. + +Returns [`TimelineEventType`](#timelineeventtype). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectincidentmanagementtimelineeventid"></a>`id` | [`IncidentManagementTimelineEventID!`](#incidentmanagementtimelineeventid) | ID of the timeline event. | +| <a id="projectincidentmanagementtimelineeventincidentid"></a>`incidentId` | [`IssueID!`](#issueid) | ID of the incident. | + +##### `Project.incidentManagementTimelineEvents` + +Incident Management Timeline events associated with the incident. + +Returns [`TimelineEventTypeConnection`](#timelineeventtypeconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectincidentmanagementtimelineeventsincidentid"></a>`incidentId` | [`IssueID!`](#issueid) | ID of the incident. | + ##### `Project.issue` A single issue of the project. @@ -13532,6 +13836,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="projectmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="projectmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="projectmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="projectmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="projectmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="projectmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -13635,7 +13940,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectpipelinesref"></a>`ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | | <a id="projectpipelinesscope"></a>`scope` | [`PipelineScopeEnum`](#pipelinescopeenum) | Filter pipelines by scope. | | <a id="projectpipelinessha"></a>`sha` | [`String`](#string) | Filter pipelines by the sha of the commit they are run for. | -| <a id="projectpipelinessource"></a>`source` | [`String`](#string) | Filter pipelines by their source. Will be ignored if `dast_view_scans` feature flag is disabled. | +| <a id="projectpipelinessource"></a>`source` | [`String`](#string) | Filter pipelines by their source. | | <a id="projectpipelinesstatus"></a>`status` | [`PipelineStatusEnum`](#pipelinestatusenum) | Filter pipelines by their status. | ##### `Project.projectMembers` @@ -13739,6 +14044,18 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="projectscanexecutionpoliciesactionscantypes"></a>`actionScanTypes` | [`[SecurityReportTypeEnum!]`](#securityreporttypeenum) | Filters policies by the action scan type. Only these scan types are supported: `dast`, `secret_detection`, `cluster_image_scanning`, `container_scanning`, `sast`. | +##### `Project.securityTrainingProviders` + +List of security training providers for the project. + +Returns [`[ProjectSecurityTraining!]`](#projectsecuritytraining). + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectsecuritytrainingprovidersonlyenabled"></a>`onlyEnabled` | [`Boolean`](#boolean) | Filter the list by only enabled security trainings. | + ##### `Project.sentryDetailedError` Detailed version of a Sentry error on the project. @@ -13962,6 +14279,20 @@ Represents a Project Membership. | <a id="projectpermissionsupdatewiki"></a>`updateWiki` | [`Boolean!`](#boolean) | Indicates the user can perform `update_wiki` on this resource. | | <a id="projectpermissionsuploadfile"></a>`uploadFile` | [`Boolean!`](#boolean) | Indicates the user can perform `upload_file` on this resource. | +### `ProjectSecurityTraining` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="projectsecuritytrainingdescription"></a>`description` | [`String`](#string) | Description of the training provider. | +| <a id="projectsecuritytrainingid"></a>`id` | [`GlobalID!`](#globalid) | ID of the training provider. | +| <a id="projectsecuritytrainingisenabled"></a>`isEnabled` | [`Boolean!`](#boolean) | Represents whether the provider is enabled or not. | +| <a id="projectsecuritytrainingisprimary"></a>`isPrimary` | [`Boolean!`](#boolean) | Represents whether the provider is set as primary or not. | +| <a id="projectsecuritytraininglogourl"></a>`logoUrl` | [`String`](#string) | Logo URL of the provider. | +| <a id="projectsecuritytrainingname"></a>`name` | [`String!`](#string) | Name of the training provider. | +| <a id="projectsecuritytrainingurl"></a>`url` | [`String!`](#string) | URL of the provider. | + ### `ProjectStatistics` #### Fields @@ -14202,13 +14533,18 @@ Returns [`Tree`](#tree). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="repositoryblobarchived"></a>`archived` | [`Boolean`](#boolean) | Whether the current project is archived. | +| <a id="repositoryblobblamepath"></a>`blamePath` | [`String`](#string) | Web path to blob blame page. | | <a id="repositoryblobcancurrentuserpushtobranch"></a>`canCurrentUserPushToBranch` | [`Boolean`](#boolean) | Whether the current user can push to the branch. | | <a id="repositoryblobcanmodifyblob"></a>`canModifyBlob` | [`Boolean`](#boolean) | Whether the current user can modify the blob. | | <a id="repositoryblobcodeowners"></a>`codeOwners` | [`[UserCore!]`](#usercore) | List of code owners for the blob. | | <a id="repositoryblobeditblobpath"></a>`editBlobPath` | [`String`](#string) | Web path to edit the blob in the old-style editor. | +| <a id="repositoryblobexternalstorage"></a>`externalStorage` | [`String`](#string) | External storage being used, if enabled (for instance, 'LFS'). | | <a id="repositoryblobexternalstorageurl"></a>`externalStorageUrl` | [`String`](#string) | Web path to download the raw blob via external storage, if enabled. | | <a id="repositoryblobfiletype"></a>`fileType` | [`String`](#string) | Expected format of the blob based on the extension. | +| <a id="repositoryblobfindfilepath"></a>`findFilePath` | [`String`](#string) | Web path to find file. | | <a id="repositoryblobforkandeditpath"></a>`forkAndEditPath` | [`String`](#string) | Web path to edit this blob using a forked project. | +| <a id="repositoryblobhistorypath"></a>`historyPath` | [`String`](#string) | Web path to blob history page. | | <a id="repositoryblobid"></a>`id` | [`ID!`](#id) | ID of the blob. | | <a id="repositoryblobideeditpath"></a>`ideEditPath` | [`String`](#string) | Web path to edit this blob in the Web IDE. | | <a id="repositoryblobideforkandeditpath"></a>`ideForkAndEditPath` | [`String`](#string) | Web path to edit this blob in the Web IDE using a forked project. | @@ -14217,6 +14553,7 @@ Returns [`Tree`](#tree). | <a id="repositoryblobname"></a>`name` | [`String`](#string) | Blob name. | | <a id="repositorybloboid"></a>`oid` | [`String!`](#string) | OID of the blob. | | <a id="repositoryblobpath"></a>`path` | [`String!`](#string) | Path of the blob. | +| <a id="repositoryblobpermalinkpath"></a>`permalinkPath` | [`String`](#string) | Web path to blob permalink. | | <a id="repositoryblobpipelineeditorpath"></a>`pipelineEditorPath` | [`String`](#string) | Web path to edit .gitlab-ci.yml file. | | <a id="repositoryblobplaindata"></a>`plainData` | [`String`](#string) | Blob plain highlighted data. | | <a id="repositoryblobrawblob"></a>`rawBlob` | [`String`](#string) | Raw content of the blob. | @@ -14429,6 +14766,20 @@ Represents the scan execution policy. | <a id="scanexecutionpolicyupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the policy YAML was last updated. | | <a id="scanexecutionpolicyyaml"></a>`yaml` | [`String!`](#string) | YAML definition of the policy. | +### `ScanResultPolicy` + +Represents the scan result policy. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="scanresultpolicydescription"></a>`description` | [`String!`](#string) | Description of the policy. | +| <a id="scanresultpolicyenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether this policy is enabled. | +| <a id="scanresultpolicyname"></a>`name` | [`String!`](#string) | Name of the policy. | +| <a id="scanresultpolicyupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the policy YAML was last updated. | +| <a id="scanresultpolicyyaml"></a>`yaml` | [`String!`](#string) | YAML definition of the policy. | + ### `ScannedResource` Represents a resource scanned by a security scan. @@ -14999,6 +15350,27 @@ Represents a historically accurate report about the timebox. | <a id="timeboxreportburnuptimeseries"></a>`burnupTimeSeries` | [`[BurnupChartDailyTotals!]`](#burnupchartdailytotals) | Daily scope and completed totals for burnup charts. | | <a id="timeboxreportstats"></a>`stats` | [`TimeReportStats`](#timereportstats) | Represents the time report stats for the timebox. | +### `TimelineEventType` + +Describes an incident management timeline event. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="timelineeventtypeaction"></a>`action` | [`String!`](#string) | Indicates the timeline event icon. | +| <a id="timelineeventtypeauthor"></a>`author` | [`UserCore`](#usercore) | User that created the timeline event. | +| <a id="timelineeventtypecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp when the event created. | +| <a id="timelineeventtypeeditable"></a>`editable` | [`Boolean!`](#boolean) | Indicates the timeline event is editable. | +| <a id="timelineeventtypeid"></a>`id` | [`IncidentManagementTimelineEventID!`](#incidentmanagementtimelineeventid) | ID of the timeline event. | +| <a id="timelineeventtypeincident"></a>`incident` | [`Issue!`](#issue) | Incident of the timeline event. | +| <a id="timelineeventtypenote"></a>`note` | [`String`](#string) | Text note of the timeline event. | +| <a id="timelineeventtypenotehtml"></a>`noteHtml` | [`String`](#string) | HTML note of the timeline event. | +| <a id="timelineeventtypeoccurredat"></a>`occurredAt` | [`Time!`](#time) | Timestamp when the event occurred. | +| <a id="timelineeventtypepromotedfromnote"></a>`promotedFromNote` | [`Note`](#note) | Note from which the timeline event was created. | +| <a id="timelineeventtypeupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp when the event updated. | +| <a id="timelineeventtypeupdatedbyuser"></a>`updatedByUser` | [`UserCore`](#usercore) | User that updated the timeline event. | + ### `Timelog` #### Fields @@ -15155,6 +15527,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usercoreassignedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="usercoreassignedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="usercoreassignedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="usercoreassignedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="usercoreassignedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="usercoreassignedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="usercoreassignedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -15186,6 +15559,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usercoreauthoredmergerequestsassigneeusername"></a>`assigneeUsername` | [`String`](#string) | Username of the assignee. | | <a id="usercoreauthoredmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="usercoreauthoredmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="usercoreauthoredmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="usercoreauthoredmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="usercoreauthoredmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="usercoreauthoredmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -15202,7 +15576,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `UserCore.groups` -Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. +Groups where the user has access. Returns [`GroupConnection`](#groupconnection). @@ -15235,6 +15609,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="usercorereviewrequestedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="usercorereviewrequestedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="usercorereviewrequestedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="usercorereviewrequestedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="usercorereviewrequestedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="usercorereviewrequestedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="usercorereviewrequestedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -15861,6 +16236,30 @@ Represents vulnerability letter grades with associated projects. | <a id="vulnerableprojectsbygradegrade"></a>`grade` | [`VulnerabilityGrade!`](#vulnerabilitygrade) | Grade based on the highest severity vulnerability present. | | <a id="vulnerableprojectsbygradeprojects"></a>`projects` | [`ProjectConnection!`](#projectconnection) | Projects within this grade. (see [Connections](#connections)) | +### `WorkItem` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemdescription"></a>`description` | [`String`](#string) | Description of the work item. | +| <a id="workitemdescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | +| <a id="workitemid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | +| <a id="workitemiid"></a>`iid` | [`ID!`](#id) | Internal ID of the work item. | +| <a id="workitemtitle"></a>`title` | [`String!`](#string) | Title of the work item. | +| <a id="workitemtitlehtml"></a>`titleHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `title`. | +| <a id="workitemworkitemtype"></a>`workItemType` | [`WorkItemType!`](#workitemtype) | Type assigned to the work item. | + +### `WorkItemType` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="workitemtypeiconname"></a>`iconName` | [`String`](#string) | Icon name of the work item type. | +| <a id="workitemtypeid"></a>`id` | [`WorkItemsTypeID!`](#workitemstypeid) | Global ID of the work item type. | +| <a id="workitemtypename"></a>`name` | [`String!`](#string) | Name of the work item type. | + ## Enumeration types Also called _Enums_, enumeration types are a special kind of scalar that @@ -15884,6 +16283,15 @@ Access level to a resource. | <a id="accesslevelenumowner"></a>`OWNER` | Owner access. | | <a id="accesslevelenumreporter"></a>`REPORTER` | Reporter access. | +### `AgentTokenStatus` + +Agent token statuses. + +| Value | Description | +| ----- | ----------- | +| <a id="agenttokenstatusactive"></a>`ACTIVE` | Active agent token. | +| <a id="agenttokenstatusrevoked"></a>`REVOKED` | Revoked agent token. | + ### `AlertManagementAlertSort` Values for sorting alerts. @@ -16444,6 +16852,7 @@ Group member relation. | <a id="groupmemberrelationdescendants"></a>`DESCENDANTS` | Members in the group's subgroups. | | <a id="groupmemberrelationdirect"></a>`DIRECT` | Members in the group itself. | | <a id="groupmemberrelationinherited"></a>`INHERITED` | Members in the group's ancestor groups. | +| <a id="groupmemberrelationshared_from_groups"></a>`SHARED_FROM_GROUPS` | Invited group's members. | ### `GroupPermission` @@ -16503,6 +16912,17 @@ Iteration ID wildcard values for issue creation. | ----- | ----------- | | <a id="issuecreationiterationwildcardidcurrent"></a>`CURRENT` | Current iteration. | +### `IssueEscalationStatus` + +Issue escalation status values. + +| Value | Description | +| ----- | ----------- | +| <a id="issueescalationstatusacknowledged"></a>`ACKNOWLEDGED` | Someone is actively investigating the problem. | +| <a id="issueescalationstatusignored"></a>`IGNORED` | No action will be taken. | +| <a id="issueescalationstatusresolved"></a>`RESOLVED` | The problem has been addressed. | +| <a id="issueescalationstatustriggered"></a>`TRIGGERED` | Investigation has not started. | + ### `IssueSort` Values for sorting issues. @@ -17114,6 +17534,15 @@ State of a Sentry error. | <a id="servicetypeyoutrack_service"></a>`YOUTRACK_SERVICE` | YoutrackService type. | | <a id="servicetypezentao_service"></a>`ZENTAO_SERVICE` | ZentaoService type. | +### `ShaFormat` + +How to format SHA strings. + +| Value | Description | +| ----- | ----------- | +| <a id="shaformatlong"></a>`LONG` | Unabbreviated format. | +| <a id="shaformatshort"></a>`SHORT` | Abbreviated format. Short SHAs are typically eight characters long. | + ### `SharedRunnersSetting` | Value | Description | @@ -17214,6 +17643,7 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumactive_user_count_threshold"></a>`ACTIVE_USER_COUNT_THRESHOLD` | Callout feature name for active_user_count_threshold. | | <a id="usercalloutfeaturenameenumbuy_pipeline_minutes_notification_dot"></a>`BUY_PIPELINE_MINUTES_NOTIFICATION_DOT` | Callout feature name for buy_pipeline_minutes_notification_dot. | | <a id="usercalloutfeaturenameenumcanary_deployment"></a>`CANARY_DEPLOYMENT` | Callout feature name for canary_deployment. | +| <a id="usercalloutfeaturenameenumci_deprecation_warning_for_types_keyword"></a>`CI_DEPRECATION_WARNING_FOR_TYPES_KEYWORD` | Callout feature name for ci_deprecation_warning_for_types_keyword. | | <a id="usercalloutfeaturenameenumcloud_licensing_subscription_activation_banner"></a>`CLOUD_LICENSING_SUBSCRIPTION_ACTIVATION_BANNER` | Callout feature name for cloud_licensing_subscription_activation_banner. | | <a id="usercalloutfeaturenameenumcluster_security_warning"></a>`CLUSTER_SECURITY_WARNING` | Callout feature name for cluster_security_warning. | | <a id="usercalloutfeaturenameenumeoa_bronze_plan_banner"></a>`EOA_BRONZE_PLAN_BANNER` | Callout feature name for eoa_bronze_plan_banner. | @@ -17387,10 +17817,10 @@ The state of the vulnerability. | Value | Description | | ----- | ----------- | -| <a id="vulnerabilitystateconfirmed"></a>`CONFIRMED` | Confirmed vulnerability. | -| <a id="vulnerabilitystatedetected"></a>`DETECTED` | Detected vulnerability. | -| <a id="vulnerabilitystatedismissed"></a>`DISMISSED` | Dismissed vulnerability. | -| <a id="vulnerabilitystateresolved"></a>`RESOLVED` | Resolved vulnerability. | +| <a id="vulnerabilitystateconfirmed"></a>`CONFIRMED` | For details, see [vulnerability status values](https://docs.gitlab.com/ee/user/application_security/vulnerabilities/index.html#vulnerability-status-values). | +| <a id="vulnerabilitystatedetected"></a>`DETECTED` | For details, see [vulnerability status values](https://docs.gitlab.com/ee/user/application_security/vulnerabilities/index.html#vulnerability-status-values). | +| <a id="vulnerabilitystatedismissed"></a>`DISMISSED` | For details, see [vulnerability status values](https://docs.gitlab.com/ee/user/application_security/vulnerabilities/index.html#vulnerability-status-values). | +| <a id="vulnerabilitystateresolved"></a>`RESOLVED` | For details, see [vulnerability status values](https://docs.gitlab.com/ee/user/application_security/vulnerabilities/index.html#vulnerability-status-values). | ### `WeightWildcardId` @@ -17691,6 +18121,12 @@ A `IncidentManagementOncallRotationID` is a global ID. It is encoded as a string An example `IncidentManagementOncallRotationID` is: `"gid://gitlab/IncidentManagement::OncallRotation/1"`. +### `IncidentManagementTimelineEventID` + +A `IncidentManagementTimelineEventID` is a global ID. It is encoded as a string. + +An example `IncidentManagementTimelineEventID` is: `"gid://gitlab/IncidentManagement::TimelineEvent/1"`. + ### `Int` Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1. @@ -17925,6 +18361,12 @@ A `VulnerabilitiesExternalIssueLinkID` is a global ID. It is encoded as a string An example `VulnerabilitiesExternalIssueLinkID` is: `"gid://gitlab/Vulnerabilities::ExternalIssueLink/1"`. +### `VulnerabilitiesFindingID` + +A `VulnerabilitiesFindingID` is a global ID. It is encoded as a string. + +An example `VulnerabilitiesFindingID` is: `"gid://gitlab/Vulnerabilities::Finding/1"`. + ### `VulnerabilitiesScannerID` A `VulnerabilitiesScannerID` is a global ID. It is encoded as a string. @@ -17937,6 +18379,18 @@ A `VulnerabilityID` is a global ID. It is encoded as a string. An example `VulnerabilityID` is: `"gid://gitlab/Vulnerability/1"`. +### `WorkItemID` + +A `WorkItemID` is a global ID. It is encoded as a string. + +An example `WorkItemID` is: `"gid://gitlab/WorkItem/1"`. + +### `WorkItemsTypeID` + +A `WorkItemsTypeID` is a global ID. It is encoded as a string. + +An example `WorkItemsTypeID` is: `"gid://gitlab/WorkItems::Type/1"`. + ## Abstract types Abstract types (unions and interfaces) are ways the schema can represent @@ -18180,6 +18634,23 @@ Implementations: | <a id="noteableinterfacediscussions"></a>`discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | <a id="noteableinterfacenotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | +#### `OrchestrationPolicy` + +Implementations: + +- [`ScanExecutionPolicy`](#scanexecutionpolicy) +- [`ScanResultPolicy`](#scanresultpolicy) + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="orchestrationpolicydescription"></a>`description` | [`String!`](#string) | Description of the policy. | +| <a id="orchestrationpolicyenabled"></a>`enabled` | [`Boolean!`](#boolean) | Indicates whether this policy is enabled. | +| <a id="orchestrationpolicyname"></a>`name` | [`String!`](#string) | Name of the policy. | +| <a id="orchestrationpolicyupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp of when the policy YAML was last updated. | +| <a id="orchestrationpolicyyaml"></a>`yaml` | [`String!`](#string) | YAML definition of the policy. | + #### `PackageFileMetadata` Represents metadata associated with a Package file. @@ -18291,6 +18762,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="userassignedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="userassignedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="userassignedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="userassignedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="userassignedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="userassignedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="userassignedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -18322,6 +18794,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="userauthoredmergerequestsassigneeusername"></a>`assigneeUsername` | [`String`](#string) | Username of the assignee. | | <a id="userauthoredmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="userauthoredmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="userauthoredmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="userauthoredmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="userauthoredmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="userauthoredmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | @@ -18338,7 +18811,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ###### `User.groups` -Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. +Groups where the user has access. Returns [`GroupConnection`](#groupconnection). @@ -18371,6 +18844,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="userreviewrequestedmergerequestsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author. | | <a id="userreviewrequestedmergerequestscreatedafter"></a>`createdAfter` | [`Time`](#time) | Merge requests created after this timestamp. | | <a id="userreviewrequestedmergerequestscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Merge requests created before this timestamp. | +| <a id="userreviewrequestedmergerequestsdraft"></a>`draft` | [`Boolean`](#boolean) | Limit result to draft merge requests. | | <a id="userreviewrequestedmergerequestsiids"></a>`iids` | [`[String!]`](#string) | Array of IIDs of merge requests, for example `[1, 2]`. | | <a id="userreviewrequestedmergerequestslabels"></a>`labels` | [`[String!]`](#string) | Array of label names. All resolved merge requests will have all of these labels. | | <a id="userreviewrequestedmergerequestsmergedafter"></a>`mergedAfter` | [`Time`](#time) | Merge requests merged after this date. | diff --git a/doc/api/group_access_tokens.md b/doc/api/group_access_tokens.md new file mode 100644 index 00000000000..37471b9d89d --- /dev/null +++ b/doc/api/group_access_tokens.md @@ -0,0 +1,112 @@ +--- +stage: Manage +group: Authentication & Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Group access tokens API **(FREE)** + +You can read more about [group access tokens](../user/group/settings/group_access_tokens.md). + +## List group access tokens + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77236) in GitLab 14.7. + +Get a list of [group access tokens](../user/group/settings/group_access_tokens.md). + +```plaintext +GET groups/:id/access_tokens +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens" +``` + +```json +[ + { + "user_id" : 141, + "scopes" : [ + "api" + ], + "name" : "token", + "expires_at" : "2021-01-31", + "id" : 42, + "active" : true, + "created_at" : "2021-01-20T22:11:48.151Z", + "revoked" : false, + "access_level": 40 + } +] +``` + +## Create a group access token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77236) in GitLab 14.7. + +Create a [group access token](../user/group/settings/group_access_tokens.md). + +```plaintext +POST groups/:id/access_tokens +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `name` | String | yes | The name of the group access token | +| `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#scopes-for-a-project-access-token) | +| `access_level` | Integer | no | A valid access level. Default value is 40 (Maintainer). Other allowed values are 10 (Guest), 20 (Reporter), and 30 (Developer). | +| `expires_at` | Date | no | The token expires at midnight UTC on that date | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +--header "Content-Type:application/json" \ +--data '{ "name":"test_token", "scopes":["api", "read_repository"], "expires_at":"2021-01-31", "access_level": 30 }' \ +"https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens" +``` + +```json +{ + "scopes" : [ + "api", + "read_repository" + ], + "active" : true, + "name" : "test", + "revoked" : false, + "created_at" : "2021-01-21T19:35:37.921Z", + "user_id" : 166, + "id" : 58, + "expires_at" : "2021-01-31", + "token" : "D4y...Wzr", + "access_level": 30 +} +``` + +## Revoke a group access token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77236) in GitLab 14.7. + +Revoke a [group access token](../user/group/settings/group_access_tokens.md). + +```plaintext +DELETE groups/:id/access_tokens/:token_id +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | +| `token_id` | integer or string | yes | The ID of the group access token | + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/<group_id>/access_tokens/<token_id>" +``` + +### Responses + +- `204: No Content` if successfully revoked. +- `400 Bad Request` or `404 Not Found` if not revoked successfully. diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 1e830237b50..ecb73aa8a5e 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md index af27b558dfe..7f663515fee 100644 --- a/doc/api/group_iterations.md +++ b/doc/api/group_iterations.md @@ -43,6 +43,7 @@ Example response: { "id": 53, "iid": 13, + "sequence": 1, "group_id": 5, "title": "Iteration II", "description": "Ipsum Lorem ipsum", diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index 0e1cd149c51..6ce4e1791b0 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -48,12 +48,13 @@ Example response: "name":"production", "deploy_access_levels":[ { - "access_level":40, - "access_level_description":"Maintainers", - "user_id":null, - "group_id":null + "access_level": 40, + "access_level_description": "Maintainers", + "user_id": null, + "group_id": null } - ] + ], + "required_approval_count": 0 } ] ``` @@ -87,7 +88,8 @@ Example response: "user_id":null, "group_id":null } - ] + ], + "required_approval_count": 0 } ``` @@ -104,6 +106,7 @@ POST /groups/:id/protected_environments | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) maintained by the authenticated user. | | `name` | string | yes | The deployment tier of the protected environment. One of `production`, `staging`, `testing`, `development`, or `other`. Read more about [deployment tiers](../ci/environments/index.md#deployment-tier-of-environments).| | `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. One of `user_id`, `group_id` or `access_level`. They take the form of `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}` respectively. | +| `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. This is part of Deployment Approvals, which isn't yet available for use. For details, see [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/343864). | The assignable `user_id` are the users who belong to the given group with the Maintainer role (or above). The assignable `group_id` are the sub-groups under the given group. @@ -119,12 +122,13 @@ Example response: "name":"production", "deploy_access_levels":[ { - "access_level":40, - "access_level_description":"protected-access-group", - "user_id":null, - "group_id":9899826 + "access_level": 40, + "access_level_description": "protected-access-group", + "user_id": null, + "group_id": 9899826 } - ] + ], + "required_approval_count": 0 } ``` diff --git a/doc/api/groups.md b/doc/api/groups.md index 13dea42f3c6..d7b4f0c8b54 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -802,9 +802,9 @@ Parameters: | `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | | `request_access_enabled` | boolean | no | Allow users to request member access. | | `parent_id` | integer | no | The parent group ID for creating nested group. | -| `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). Default to the global level default branch protection setting. | -| `shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | -| `extra_shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). Default to the global level default branch protection setting. | +| `shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | +| `extra_shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | ### Options for `default_branch_protection` @@ -905,8 +905,8 @@ PUT /groups/:id | `request_access_enabled` | boolean | no | Allow users to request member access. | | `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). | | `file_template_project_id` **(PREMIUM)** | integer | no | The ID of a project to load custom file templates from. | -| `shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | -| `extra_shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| `shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | +| `extra_shared_runners_minutes_limit` **(PREMIUM)** | integer | no | Can be set by administrators only. Additional CI/CD minutes for this group. | | `prevent_forking_outside_group` **(PREMIUM)** | boolean | no | When enabled, users can **not** fork projects from this group to external namespaces | `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | | `prevent_sharing_groups_outside_hierarchy` | boolean | no | See [Prevent group sharing outside the group hierarchy](../user/group/index.md#prevent-group-sharing-outside-the-group-hierarchy). This attribute is only available on top-level groups. [Introduced in GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/333721) | diff --git a/doc/api/index.md b/doc/api/index.md index a4e7a893618..69db971f58c 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -64,8 +64,7 @@ For the changes between v3 and v4, see the [v3 to v4 documentation](v3_to_v4.md) ### Current status -Only API version v4 is available. Version v3 was removed in -[GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819). +Only API version v4 is available. ## How to use the API @@ -170,24 +169,24 @@ for examples requesting a new access token using a refresh token. A default refresh setting of two hours is tracked in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336598). -### Personal/project access tokens +### Personal/project/group access tokens You can use access tokens to authenticate with the API by passing it in either the `private_token` parameter or the `PRIVATE-TOKEN` header. -Example of using the personal or project access token in a parameter: +Example of using the personal, project, or group access token in a parameter: ```shell curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>" ``` -Example of using the personal or project access token in a header: +Example of using the personal, project, or group access token in a header: ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects" ``` -You can also use personal or project access tokens with OAuth-compliant headers: +You can also use personal, project, or group access tokens with OAuth-compliant headers: ```shell curl --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/projects" @@ -224,8 +223,6 @@ header. #### Disable impersonation -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/40385) in GitLab 11.6. - By default, impersonation is enabled. To disable impersonation: **For Omnibus installations** diff --git a/doc/api/integrations.md b/doc/api/integrations.md index 8f57e915b4e..dd5a8c568fb 100644 --- a/doc/api/integrations.md +++ b/doc/api/integrations.md @@ -314,13 +314,15 @@ PUT /projects/:id/integrations/datadog Parameters: -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `api_key` | string | true | API key used for authentication with Datadog | -| `api_url` | string | false | (Advanced) Define the full URL for your Datadog site directly | -| `datadog_site` | string | false | Choose the Datadog site to send data to. Set to `datadoghq.eu` to send data to the EU site | -| `datadog_service` | string | false | Name of this GitLab instance that all data will be tagged with | -| `datadog_env` | string | false | The environment tag that traces will be tagged with | +| Parameter | Type | Required | Description | +| ---------------------- | ------- | -------- | ----------- | +| `api_key` | string | true | API key used for authentication with Datadog | +| `api_url` | string | false | (Advanced) The full URL for your Datadog site | +<!-- | `archive_trace_events` | boolean | false | When enabled, job logs are collected by Datadog and displayed along with pipeline execution traces ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346339) in GitLab 14.7) | --> +<!-- TODO: uncomment the archive_trace_events field once :datadog_integration_logs_collection is rolled out. Rollout issue: https://gitlab.com/gitlab-org/gitlab/-/issues/346339 --> +| `datadog_env` | string | false | For self-managed deployments, set the env% tag for all the data sent to Datadog. | +| `datadog_service` | string | false | Tag all data from this GitLab instance in Datadog. Useful when managing several self-managed deployments | +| `datadog_site` | string | false | The Datadog site to send data to. To send data to the EU site, use `datadoghq.eu` | ### Disable Datadog integration diff --git a/doc/api/issues.md b/doc/api/issues.md index 204d75e9ee4..5d22952a876 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -54,14 +54,15 @@ GET /issues?state=opened | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `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, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `author_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`. | | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | +| `epic_id` **(PREMIUM)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | @@ -70,11 +71,11 @@ GET /issues?state=opened | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. Using `None` or `Any` will be [deprecated in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/336044). Please use `milestone_id` attribute instead. `milestone` and `milestone_id` are mutually exclusive. | | `milestone_id` | string | no | Returns issues assigned to milestones with a given timebox value (`None`, `Any`, `Upcoming`, and `Started`). `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. `Upcoming` lists all issues assigned to milestones due in the future. `Started` lists all issues assigned to open, started milestones. `milestone` and `milestone_id` are mutually exclusive. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335939) in GitLab 14.3)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | +| `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. | | `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197170) in GitLab 13.0)_ | | `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, `milestone_id` and `weight`. | | `order_by` | string | no | Return issues ordered by `created_at`, `due_date`, `label_priority`, `milestone_due`, `popularity`, `priority`, `relative_position`, `title`, `updated_at`, or `weight` fields. Default is `created_at`. | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | +| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | | `search` | string | no | Search issues against their `title` and `description` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `state` | string | no | Return `all` issues or just those that are `opened` or `closed` | @@ -228,11 +229,6 @@ WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. -This value is only present for issues closed after GitLab 10.6 and if the user account -that closed the issue still exists. - ## List group issues > The `weight` property moved to GitLab Premium in 13.9. @@ -261,14 +257,15 @@ GET /groups/:id/issues?state=opened | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `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. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `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, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `author_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`. | | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | +| `epic_id` **(PREMIUM)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | @@ -276,11 +273,11 @@ GET /groups/:id/issues?state=opened | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | +| `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. | | `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785) in GitLab 12.8)_ | | `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | | `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | +| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. | | `search` | string | no | Search group issues against their `title` and `description` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | @@ -432,11 +429,6 @@ WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. -This value is only present for issues closed after GitLab 10.6 and if the user account that closed -the issue still exists. - ## List project issues > The `weight` property moved to GitLab Premium in 13.9. @@ -465,14 +457,15 @@ GET /projects/:id/issues?state=opened | Attribute | Type | Required | Description | | ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `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. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `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, the `assignee_username` array should only contain a single value. Otherwise, an invalid parameter error is returned. | -| `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5)_ | +| `author_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`. | | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | +| `epic_id` **(PREMIUM)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | @@ -480,10 +473,10 @@ GET /projects/:id/issues?state=opened | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | +| `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. | | `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | | `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | -| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | +| `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `all`. | | `search` | string | no | Search project issues against their `title` and `description` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | @@ -642,10 +635,6 @@ WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed -the issue still exists. - ## Single issue Only for administrators. Get a single issue. @@ -807,11 +796,6 @@ WARNING: The `epic_iid` attribute is deprecated, and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. -This value is only present for issues closed after GitLab 10.6 and if the user account -that closed the issue still exists. - ## Single project issue Get a single project issue. @@ -968,10 +952,6 @@ WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed -the issue still exists. - ## New issue > The `weight` property moved to GitLab Premium in 13.9. @@ -1118,10 +1098,6 @@ WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed -the issue still exists. - ## Rate limits To help avoid abuse, users can be limited to a specific number of `Create` requests per minute. @@ -1289,10 +1265,6 @@ Issues created by users on GitLab Ultimate include the `health_status` property: ] ``` -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed -the issue still exists. - WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. @@ -1483,10 +1455,6 @@ WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed -the issue still exists. - ## Clone an issue Clone the issue to given project. If the user has insufficient permissions, @@ -1735,10 +1703,6 @@ WARNING: The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed -the issue still exists. - ## Unsubscribe from an issue Unsubscribes the authenticated user from the issue to not receive notifications @@ -1929,10 +1893,6 @@ Example response: WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. -NOTE: -The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. 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` diff --git a/doc/api/issues_statistics.md b/doc/api/issues_statistics.md index 11f24d94763..7687124fb3a 100644 --- a/doc/api/issues_statistics.md +++ b/doc/api/issues_statistics.md @@ -41,6 +41,7 @@ GET /issues_statistics?confidential=true | `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 is returned otherwise. | +| `epic_id` **(PREMIUM)** | integer | no | Return issues associated with the given epic ID. `None` returns issues that are not associated with an epic. `Any` returns issues that are associated with an epic. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46887) in GitLab 13.6)_ | `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` | diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 7c7847bf368..a874379506f 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -259,7 +259,7 @@ Example response: } ``` -## Delete artifacts +## Delete job artifacts > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25522) in GitLab 11.9. @@ -284,3 +284,33 @@ 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. + +## Delete project artifacts + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223793) in GitLab 14.7 [with a flag](../administration/feature_flags.md) named `bulk_expire_project_artifacts`. Enabled by default on GitLab self-managed. Enabled on GitLab.com. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to +[disable the `bulk_expire_project_artifacts` flag](../administration/feature_flags.md). On GitLab.com, this feature is available. + +[Expire artifacts of a project that can be deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/223793) but that don't have an expiry time. + +```plaintext +DELETE /projects/:id/artifacts +``` + +| Attribute | Type | Required | Description | +|-----------|----------------|----------|-----------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | + +Example request: + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/artifacts" +``` + +NOTE: +At least Maintainer role is required to delete artifacts. + +Schedules a worker to update to the current time the expiry of all artifacts that can be deleted. +A response with status `202 Accepted` is returned. diff --git a/doc/api/markdown.md b/doc/api/markdown.md index d83b7420829..c128e8512df 100644 --- a/doc/api/markdown.md +++ b/doc/api/markdown.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Markdown API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18926) in GitLab 11.0. - Available only in APIv4. ## Render an arbitrary Markdown document diff --git a/doc/api/members.md b/doc/api/members.md index bc476980d2d..ee6d2cfa2d8 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -88,15 +88,20 @@ Example response: ] ``` -## List all members of a group or project including inherited members +## List all members of a group or project including inherited and invited members -Gets a list of group or project members viewable by the authenticated user, including inherited members and permissions through ancestor groups. +Gets a list of group or project members viewable by the authenticated user, including inherited members, invited users, and permissions through ancestor groups. If a user is a member of this group or project and also of one or more ancestor groups, only its membership with the highest `access_level` is returned. ([Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56677) in GitLab 13.11.) This represents the effective permission of the user. +Members from an invited group are returned if either: + +- The invited group is public. +- The requester is also a member of the invited group. + This function takes pagination parameters `page` and `per_page` to restrict the list of users. ```plaintext @@ -109,7 +114,7 @@ GET /projects/:id/members/all | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](index.md#namespaced-path-encoding) owned by the authenticated user | | `query` | string | no | A query string to search for members | | `user_ids` | array of integers | no | Filter the results on the given user IDs | -| `state` | string | no | Filter results by member state, one of `awaiting`, `active` or `created` **(PREMIUM)** | +| `state` | string | no | Filter results by member state, one of `awaiting` or `active` **(PREMIUM)** | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/:id/members/all" @@ -202,11 +207,11 @@ Example response: } ``` -## Get a member of a group or project, including inherited members +## Get a member of a group or project, including inherited and invited members > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17744) in GitLab 12.4. -Gets a member of a group or project, including members inherited through ancestor groups. See the corresponding [endpoint to list all inherited members](#list-all-members-of-a-group-or-project-including-inherited-members) for details. +Gets a member of a group or project, including members inherited or invited through ancestor groups. See the corresponding [endpoint to list all inherited members](#list-all-members-of-a-group-or-project-including-inherited-and-invited-members) for details. ```plaintext GET /groups/:id/members/all/:user_id diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index fa713558684..905ecd05d52 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -6,13 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Merge requests API **(FREE)** -> - `with_labels_details` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7. -> - `author_username` and `author_username` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10. > - `reference` was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.10 in favour of `references`. -> - `with_merge_status_recheck` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. > - `reviewer_username` and `reviewer_id` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. -> - `reviewer_ids` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51186) in GitLab 13.8. -> - `draft` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63473) as an eventual replacement for `work_in_progress` in GitLab 14.0 +> - `draft` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63473) as a replacement for `work_in_progress` in GitLab 14.0. +> - `merge_user` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349031) as an eventual replacement for `merged_by` in GitLab 14.7. Every API call to merge requests must be authenticated. @@ -46,6 +43,11 @@ This approach is generally slower and more resource-intensive, but isn't subject placed on database-backed diffs. [Limits inherent to Gitaly](../development/diffs.md#diff-limits) still apply. +- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349031) in GitLab 14.7, +field `merge_user` can be either user who merged this merge request, +user who set it to merge when pipeline succeeds or `null`. +Field `merged_by` (user who merged this merge request or `null`) has been deprecated. + ## List merge requests Get all merge requests the authenticated user has access to. By @@ -53,9 +55,10 @@ default it returns only merge requests created by the current user. To get all merge requests, use parameter `scope=all`. The `state` parameter can be used to get only merge requests with a -given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). It should be noted that when searching by `locked` it mostly returns no results as it is a short-lived, transitional state. -The pagination parameters `page` and `per_page` can be used to -restrict the list of merge requests. +given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). +It should be noted that when searching by `locked` it mostly returns no results +as it is a short-lived, transitional state. The pagination parameters `page` and +`per_page` can be used to restrict the list of merge requests. ```plaintext GET /merge_requests @@ -79,21 +82,21 @@ Parameters: | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | -| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | -| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | -| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. | +| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive. | +| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7. | +| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. | | `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. | +| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`. | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. | -| `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. | +| `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10. | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | | `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | | `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. | +| `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `source_branch` | string | no | Return merge requests with the given source branch. | | `target_branch` | string | no | Return merge requests with the given target branch. | @@ -114,7 +117,15 @@ Parameters: "title": "test1", "description": "fixed login page css paddings", "state": "merged", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -266,21 +277,21 @@ Parameters: | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | -| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | -| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. | -| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. | +| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive. | +| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7. | +| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. | | `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me`, or `all`. | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. | -| `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.| +| `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10. | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | | `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | | `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. | +| `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `source_branch` | string | no | Return merge requests with the given source branch. | @@ -298,7 +309,15 @@ Parameters: "title": "test1", "description": "fixed login page css paddings", "state": "merged", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -453,8 +472,8 @@ Parameters: | `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc`. | | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | -| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | -| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7.| +| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. Predefined names are case-insensitive. | +| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7. | | `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. | | `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -462,12 +481,12 @@ Parameters: | `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. | -| `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10)_. | +| `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10. | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | | `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | | `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. | | `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. | -| `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. | +| `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. | | `source_branch` | string | no | Return merge requests with the given source branch. | | `target_branch` | string | no | Return merge requests with the given target branch. | @@ -484,7 +503,15 @@ Parameters: "title": "test1", "description": "fixed login page css paddings", "state": "merged", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -720,7 +747,15 @@ Parameters: "squash": false, "subscribed": false, "changes_count": "1", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -1074,14 +1109,14 @@ POST /projects/:id/merge_requests | `title` | string | yes | Title of MR. | | `assignee_id` | integer | no | Assignee user ID. | | `assignee_ids` | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees. | -| `reviewer_ids` | integer array | no | The ID of the user(s) added as a reviewer to the MR. If set to `0` or left empty, no reviewers are added. | +| `reviewer_ids` | integer array | no | The ID of the user(s) added as a reviewer to the MR. If set to `0` or left empty, no reviewers are added. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `description` | string | no | Description of MR. Limited to 1,048,576 characters. | | `target_project_id` | integer | no | The target project (numeric ID). | | `labels` | string | no | Labels for MR as a comma-separated list. | | `milestone_id` | integer | no | The global ID of a milestone. | | `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging. | | `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch. | -| `allow_maintainer_to_push` | boolean | no | Deprecated, see `allow_collaboration`. | +| `allow_maintainer_to_push` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/22665), see `allow_collaboration`. | | `squash` | boolean | no | Squash commits into a single commit when merging. | ```json @@ -1162,7 +1197,15 @@ POST /projects/:id/merge_requests "squash": false, "subscribed": false, "changes_count": "1", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -1224,7 +1267,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `title` | string | no | Title of MR. | | `assignee_id` | integer | no | The ID of the user to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees. | | `assignee_ids` | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees. | -| `reviewer_ids` | integer array | no | The ID of the user(s) set as a reviewer to the MR. Set the value to `0` or provide an empty value to unset all reviewers. | +| `reviewer_ids` | integer array | no | The ID of the user(s) set as a reviewer to the MR. Set the value to `0` or provide an empty value to unset all reviewers. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. | | `milestone_id` | integer | no | The global ID of a milestone to assign the merge request to. Set to `0` or provide an empty value to unassign a milestone.| | `labels` | string | no | Comma-separated label names for a merge request. Set to an empty string to unassign all labels. | | `add_labels` | string | no | Comma-separated label names to add to a merge request. | @@ -1235,7 +1278,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | `squash` | boolean | no | Squash commits into a single commit when merging. | | `discussion_locked` | boolean | no | Flag indicating if the merge request's discussion is locked. If the discussion is locked only project members can add, edit or resolve comments. | | `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch. | -| `allow_maintainer_to_push` | boolean | no | Deprecated, see `allow_collaboration`. | +| `allow_maintainer_to_push` | boolean | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/22665), see `allow_collaboration`. | Must include at least one non-required attribute from above. @@ -1333,7 +1376,15 @@ Must include at least one non-required attribute from above. "squash": false, "subscribed": false, "changes_count": "1", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -1519,7 +1570,15 @@ Parameters: "squash": false, "subscribed": false, "changes_count": "1", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -1708,7 +1767,15 @@ Parameters: "squash": false, "subscribed": false, "changes_count": "1", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -2009,7 +2076,15 @@ Example response: "squash": false, "subscribed": false, "changes_count": "1", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -2169,7 +2244,15 @@ Example response: "squash": false, "subscribed": false, "changes_count": "1", - "merged_by": { + "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead + "id": 87854, + "name": "Douwe Maan", + "username": "DouweM", + "state": "active", + "avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png", + "web_url": "https://gitlab.com/DouweM" + }, + "merge_user": { "id": 87854, "name": "Douwe Maan", "username": "DouweM", @@ -2603,7 +2686,7 @@ Example response: ## Approvals -For approvals, please see [Merge Request Approvals](merge_request_approvals.md) +For approvals, see [Merge Request Approvals](merge_request_approvals.md) ## List merge request state events diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 9a52b0983a7..a02d44136d1 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 778c229e3c8..ef7d133e907 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -43,6 +43,8 @@ During registration, by enabling proper scopes, you can limit the range of resources which the `application` can access. Upon creation, you obtain the `application` credentials: _Application ID_ and _Client Secret_ - **keep them secure**. +For a list of scopes in GitLab, see [the provider documentation](../integration/oauth_provider.md#authorized-applications). + ### Prevent CSRF attacks To [protect redirect-based flows](https://tools.ietf.org/id/draft-ietf-oauth-security-topics-13.html#rec_redirect), @@ -97,7 +99,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD This page asks the user to approve the request from the app to access their account based on the scopes specified in `REQUESTED_SCOPES`. The user is then - redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes) + redirected back to the specified `REDIRECT_URI`. The [scope parameter](../integration/oauth_provider.md#authorized-applications) is a space-separated list of scopes associated with the user. For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes. The redirect includes the authorization `code`, for example: @@ -177,7 +179,7 @@ be used as a CSRF token. This page asks the user to approve the request from the app to access their account based on the scopes specified in `REQUESTED_SCOPES`. The user is then - redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes) + redirected back to the specified `REDIRECT_URI`. The [scope parameter](../integration/oauth_provider.md#authorized-applications) is a space-separated list of scopes associated with the user. For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes. The redirect includes the authorization `code`, for example: @@ -265,7 +267,7 @@ https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIREC This prompts the user to approve the applications access to their account based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to -the `REDIRECT_URI` you provided. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes) +the `REDIRECT_URI` you provided. The [scope parameter](../integration/oauth_provider.md#authorized-applications) is a space-separated list of scopes you want to have access to (for example, `scope=read_user+profile` would request `read_user` and `profile` scopes). The redirect includes a fragment with `access_token` as well as token details in GET @@ -371,6 +373,12 @@ or you can put the token to the Authorization header: curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/user" ``` +## Access Git over HTTPS with `access token` + +A token with [scope](../integration/oauth_provider.md#authorized-applications) +`read_repository` or `write_repository` can access Git over HTTPS. Use the token as the password. +The username must be `oauth2`, not your username. + ## Retrieve the token information To verify the details of a token, use the `token/info` endpoint provided by the diff --git a/doc/api/packages.md b/doc/api/packages.md index a75b2e376fa..555b8d5e054 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -12,8 +12,6 @@ This is the API documentation of [GitLab Packages](../administration/packages/in ### Within a project -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9259) in GitLab 11.8. - Get a list of project packages. All package types are included in results. When accessed without authentication, only packages of public projects are returned. @@ -26,7 +24,7 @@ GET /projects/:id/packages | `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, or `type`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | -| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, `helm`, or `golang`. (_Introduced in GitLab 12.9_) +| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, `helm`, `terraform_module`, or `golang`. (_Introduced in GitLab 12.9_) | `package_name` | string | no | Filter the project packages with a fuzzy search by name. (_Introduced in GitLab 12.9_) | `include_versionless` | boolean | no | When set to true, versionless packages are included in the response. (_Introduced in GitLab 13.8_) | `status` | string | no | Filter the returned packages by status. One of `default` (default), `hidden`, or `processing`. (_Introduced in GitLab 13.9_) @@ -176,8 +174,6 @@ can result in malformed data or broken packages. ## Get a project package -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9667) in GitLab 11.9. - Get a single project package. ```plaintext @@ -258,8 +254,6 @@ The `_links` object contains the following properties: ## List package files -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9305) in GitLab 11.8. - Get a list of package files of a single package. ```plaintext @@ -331,8 +325,6 @@ By default, the `GET` request returns 20 results, because the API is [paginated] ## Delete a project package -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9623) in GitLab 11.9. - Deletes a project package. ```plaintext diff --git a/doc/api/packages/maven.md b/doc/api/packages/maven.md index b046b0dc411..27bc4da07a1 100644 --- a/doc/api/packages/maven.md +++ b/doc/api/packages/maven.md @@ -22,8 +22,6 @@ for details on which headers and token types are supported. ## Download a package file at the instance-level -> Introduced in GitLab 11.6. - Download a Maven package file: ```plaintext @@ -49,8 +47,6 @@ This writes the downloaded file to `mypkg-1.0-SNAPSHOT.jar` in the current direc ## Download a package file at the group-level -> Introduced in GitLab 11.7. - Download a Maven package file: ```plaintext @@ -76,8 +72,6 @@ This writes the downloaded file to `mypkg-1.0-SNAPSHOT.jar` in the current direc ## Download a package file at the project-level -> Introduced in GitLab 11.3. - Download a Maven package file: ```plaintext @@ -103,8 +97,6 @@ This writes the downloaded file to `mypkg-1.0-SNAPSHOT.jar` in the current direc ## Upload a package file -> Introduced in GitLab 11.3. - Upload a Maven package file: ```plaintext diff --git a/doc/api/packages/npm.md b/doc/api/packages/npm.md index 24ac1a640c9..846271015cc 100644 --- a/doc/api/packages/npm.md +++ b/doc/api/packages/npm.md @@ -22,8 +22,6 @@ for details on which headers and token types are supported. ## Download a package -> Introduced in GitLab 11.8. - Downloads the npm package. This URL is provided by the [metadata endpoint](#metadata). ```plaintext @@ -50,8 +48,6 @@ This writes the downloaded file to `@myscope/my-pkg-0.0.1.tgz` in the current di ## Upload a package file -> Introduced in GitLab 11.8. - Upload a package. ```plaintext @@ -153,8 +149,6 @@ The examples in this document all use the project-level prefix. ## Metadata -> Introduced in GitLab 11.8. - Returns the metadata for a given package. ```plaintext diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index a1c96d03297..592b976da59 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -166,8 +166,6 @@ This writes the downloaded file to `simple.html` in the current directory. ## Upload a package -> Introduced in GitLab 11.3. - Upload a PyPI package: ```plaintext diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index d850113f9b6..b05c71d2748 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -280,7 +280,7 @@ POST /projects/:id/pipeline | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `ref` | string | yes | Reference to commit | +| `ref` | string | yes | The branch or tag to run the pipeline on. | | `variables` | array | no | An array containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. | ```shell diff --git a/doc/api/plan_limits.md b/doc/api/plan_limits.md index 8bd87f5a896..8d37189ef2a 100644 --- a/doc/api/plan_limits.md +++ b/doc/api/plan_limits.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/project_access_tokens.md b/doc/api/project_access_tokens.md new file mode 100644 index 00000000000..125797a802f --- /dev/null +++ b/doc/api/project_access_tokens.md @@ -0,0 +1,112 @@ +--- +stage: Manage +group: Authentication & Authorization +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Project access tokens API **(FREE)** + +You can read more about [project access tokens](../user/project/settings/project_access_tokens.md). + +## List project access tokens + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. + +Get a list of [project access tokens](../user/project/settings/project_access_tokens.md). + +```plaintext +GET projects/:id/access_tokens +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" +``` + +```json +[ + { + "user_id" : 141, + "scopes" : [ + "api" + ], + "name" : "token", + "expires_at" : "2021-01-31", + "id" : 42, + "active" : true, + "created_at" : "2021-01-20T22:11:48.151Z", + "revoked" : false, + "access_level": 40 + } +] +``` + +## Create a project access token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55408) in GitLab 13.10. + +Create a [project access token](../user/project/settings/project_access_tokens.md). + +```plaintext +POST projects/:id/access_tokens +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `name` | String | yes | The name of the project access token | +| `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#scopes-for-a-project-access-token) | +| `access_level` | Integer | no | A valid access level. Default value is 40 (Maintainer). Other allowed values are 10 (Guest), 20 (Reporter), and 30 (Developer). | +| `expires_at` | Date | no | The token expires at midnight UTC on that date | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ +--header "Content-Type:application/json" \ +--data '{ "name":"test_token", "scopes":["api", "read_repository"], "expires_at":"2021-01-31", "access_level": 30 }' \ +"https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" +``` + +```json +{ + "scopes" : [ + "api", + "read_repository" + ], + "active" : true, + "name" : "test", + "revoked" : false, + "created_at" : "2021-01-21T19:35:37.921Z", + "user_id" : 166, + "id" : 58, + "expires_at" : "2021-01-31", + "token" : "D4y...Wzr", + "access_level": 30 +} +``` + +## Revoke a project access token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. + +Revoke a [project access token](../user/project/settings/project_access_tokens.md). + +```plaintext +DELETE projects/:id/access_tokens/:token_id +``` + +| Attribute | Type | required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | +| `token_id` | integer or string | yes | The ID of the project access token | + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>" +``` + +### Responses + +- `204: No Content` if successfully revoked. +- `400 Bad Request` or `404 Not Found` if not revoked successfully. diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index c6f979c1643..846c0241dd1 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, api +info: To 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 badges API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17082) in GitLab 10.6. - ## Placeholder tokens Badges support placeholders that are replaced in real-time in both the link and image URL. The allowed placeholders are: diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index 39c68041725..e7609d34998 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, api +info: To 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 API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41899) in GitLab 10.6. - See also: - [Project import/export documentation](../user/project/settings/import_export.md). @@ -23,7 +20,7 @@ all the necessary information to upload the exported project to a web server or to any S3-compatible platform. At the moment we only support binary data file uploads to the final server. -From GitLab 10.7, the `upload[url]` parameter is required if the `upload` parameter is present. +The `upload[url]` parameter is required if the `upload` parameter is present. ```plaintext POST /projects/:id/export diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 569270e5de1..c5f317f7540 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -1,8 +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/#assignments" -type: reference, api +info: To 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 snippets **(FREE)** @@ -247,8 +246,6 @@ curl "https://gitlab.com/api/v4/projects/1/snippets/2/files/master/snippet%2Erb/ ## Get user agent details -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/29508) in GitLab 9.4. - Available only for users with the Administrator [role](../user/permissions.md). ```plaintext diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index 2ec30c80a6b..4c0a1890729 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -1,8 +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/#assignments" -type: reference, api +info: To 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 templates API **(FREE)** @@ -21,9 +20,7 @@ It deprecates these endpoints, which are scheduled for removal in 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) -in GitLab 11.5 +Support is also available for [group-level file templates](../user/group/index.md#group-file-templates). **(PREMIUM)** ## Get all templates of a particular type diff --git a/doc/api/projects.md b/doc/api/projects.md index 65911567f87..791be613c71 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -619,7 +619,7 @@ GET /users/:user_id/projects ## List projects starred by a user -Get a list of visible projects owned by the given user. When accessed without +Get a list of visible projects starred by the given user. When accessed without authentication, only public projects are returned. ```plaintext @@ -1049,8 +1049,10 @@ The `web_url` and `avatar_url` attributes on `namespace` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27427) in GitLab 11.11. -If the project is a fork, and you provide a valid token to authenticate, the -`forked_from_project` field appears in the response. +If the project is a fork, the `forked_from_project` field appears in the response. +For this field, if the upstream project is private, a valid token for authentication must be provided. +The field `mr_default_target_self` appears as well. If this value is `false`, then all merge requests +will target the upstream project by default. ```json { @@ -1058,6 +1060,7 @@ If the project is a fork, and you provide a valid token to authenticate, the ... + "mr_default_target_self": false, "forked_from_project":{ "id":13083, "description":"GitLab Community Edition", @@ -1448,6 +1451,7 @@ Supported attributes: | `issues_template` **(PREMIUM)** | string | **{dotted-circle}** No | Default description for Issues. Description is parsed with GitLab Flavored Markdown. See [Templates for issues and merge requests](#templates-for-issues-and-merge-requests). | | `merge_requests_template` **(PREMIUM)** | string | **{dotted-circle}** No | Default description for Merge Requests. Description is parsed with GitLab Flavored Markdown. See [Templates for issues and merge requests](#templates-for-issues-and-merge-requests). | | `keep_latest_artifact` | boolean | **{dotted-circle}** No | Disable or enable the ability to keep the latest artifact for this project. | +| `mr_default_target_self` | boolean | **{dotted-circle}** No | For forked projects, target merge requests to this project. If `false`, the target will be the upstream project. | ## Fork project @@ -1471,6 +1475,7 @@ POST /projects/:id/fork | `path` | string | **{dotted-circle}** No | The path assigned to the resultant project after forking. | | `description` | string | **{dotted-circle}** No | The description assigned to the resultant project after forking. | | `visibility` | string | **{dotted-circle}** No | The [visibility level](#project-visibility-level) assigned to the resultant project after forking. | +| `mr_default_target_self` | boolean | **{dotted-circle}** No | For forked projects, target merge requests to this project. If `false`, the target will be the upstream project. | ## List Forks of a project @@ -2386,6 +2391,7 @@ POST /projects/:id/hooks | `token` | string | **{dotted-circle}** No | Secret token to validate received payloads; this isn't returned in the response. | | `url` | string | **{check-circle}** Yes | The hook URL. | | `wiki_page_events` | boolean | **{dotted-circle}** No | Trigger hook on wiki events. | +| `releases_events` | boolean | **{dotted-circle}** No | Trigger hook on release events. | ### Edit project hook diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index d17341759ad..ea2412515a0 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Protected branches API **(FREE)** -> Introduced in GitLab 9.5. - **Valid access levels** The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` method. Currently, these levels are recognized: @@ -201,13 +198,13 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla | -------------------------------------------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch or wildcard | -| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, Maintainer role) | -| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, Maintainer role) | -| `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, Maintainer role) | +| `push_access_level` | integer | no | Access levels allowed to push (defaults: `40`, Maintainer role) | +| `merge_access_level` | integer | no | Access levels allowed to merge (defaults: `40`, Maintainer role) | +| `unprotect_access_level` | integer | no | Access levels allowed to unprotect (defaults: `40`, Maintainer role) | | `allow_force_push` | boolean | no | Allow all users with push access to force push. (default: `false`) | -| `allowed_to_push` **(PREMIUM)** | array | no | Array of access levels allowed to push, with each described by a hash | -| `allowed_to_merge` **(PREMIUM)** | array | no | Array of access levels allowed to merge, with each described by a hash | -| `allowed_to_unprotect` **(PREMIUM)** | array | no | Array of access levels allowed to unprotect, with each described by a hash | +| `allowed_to_push` **(PREMIUM)** | array | no | Array of access levels allowed to push, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | +| `allowed_to_merge` **(PREMIUM)** | array | no | Array of access levels allowed to merge, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | +| `allowed_to_unprotect` **(PREMIUM)** | array | no | Array of access levels allowed to unprotect, with each described by a hash of the form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}` | | `code_owner_approval_required` **(PREMIUM)** | boolean | no | Prevent pushes to this branch if it matches an item in the [`CODEOWNERS` file](../user/project/code_owners.md). (defaults: false) | Example response: @@ -332,7 +329,6 @@ curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --header "Content-Type: application/json" \ --data '{ - "id": 5, "name": "master", "allowed_to_push": [{"access_level": 30}], "allowed_to_merge": [{ diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index c7de4c504a4..61587136a14 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -49,7 +49,8 @@ Example response: "user_id":null, "group_id":null } - ] + ], + "required_approval_count": 0 } ] ``` @@ -78,12 +79,13 @@ Example response: "name":"production", "deploy_access_levels":[ { - "access_level":40, - "access_level_description":"Maintainers", - "user_id":null, - "group_id":null + "access_level": 40, + "access_level_description": "Maintainers", + "user_id": null, + "group_id": null } - ] + ], + "required_approval_count": 0 } ``` @@ -107,6 +109,7 @@ curl --header 'Content-Type: application/json' --request POST \ | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `name` | string | yes | The name of the environment. | | `deploy_access_levels` | array | yes | Array of access levels allowed to deploy, with each described by a hash. | +| `required_approval_count` | integer | no | The number of approvals required to deploy to this environment. This is part of Deployment Approvals, which isn't yet available for use. For details, see [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/343864). | Elements in the `deploy_access_levels` array should be one of `user_id`, `group_id` or `access_level`, and take the form `{user_id: integer}`, `{group_id: integer}` or @@ -125,7 +128,8 @@ Example response: "user_id": null, "group_id": 9899826 } - ] + ], + "required_approval_count": 0 } ``` diff --git a/doc/api/protected_tags.md b/doc/api/protected_tags.md index 7a46a2dbf12..e2b27692373 100644 --- a/doc/api/protected_tags.md +++ b/doc/api/protected_tags.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Protected tags API **(FREE)** -> Introduced in GitLab 11.3. - **Valid access levels** Currently, these levels are recognized: diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index c253358f01f..c603be9489c 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -6,15 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Releases API **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. -> - 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. > - `description_html` became an opt-in field [with GitLab 13.12 for performance reasons](https://gitlab.com/gitlab-org/gitlab/-/issues/299447). Please pass the `include_html_description` query string parameter if you need it. > - [The permission model for create, update and delete actions was fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/327505) in GitLab 14.1. See [Release permissions](../../user/project/releases/index.md#release-permissions) for more information. +Use this API to manipulate GitLab [Release](../../user/project/releases/index.md) +entries. For manipulating links as a release asset, see [Release Links API](links.md). + ## Authentication For authentication, the Releases API accepts either: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index c9d183b8351..282ef0adc78 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Release links API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. +Use this API to manipulate GitLab [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 diff --git a/doc/api/repository_submodules.md b/doc/api/repository_submodules.md index 06f9e514009..cbd6a369e97 100644 --- a/doc/api/repository_submodules.md +++ b/doc/api/repository_submodules.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, api +info: To 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 submodules API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41213) in GitLab 11.5 - ## Update existing submodule reference in repository In some workflows, especially automated ones, it can be useful to update a diff --git a/doc/api/resource_access_tokens.md b/doc/api/resource_access_tokens.md index 90e9769b896..c77a8f5d0d6 100644 --- a/doc/api/resource_access_tokens.md +++ b/doc/api/resource_access_tokens.md @@ -1,112 +1,9 @@ --- -stage: Manage -group: Access -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'project_access_tokens.md' +remove_date: '2022-04-06' --- -# Project access tokens API **(FREE)** +This document was moved to [another location](project_access_tokens.md). -You can read more about [project access tokens](../user/project/settings/project_access_tokens.md). - -## List project access tokens - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. - -Get a list of project access tokens. - -```plaintext -GET projects/:id/access_tokens -``` - -| Attribute | Type | required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | - -```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" -``` - -```json -[ - { - "user_id" : 141, - "scopes" : [ - "api" - ], - "name" : "token", - "expires_at" : "2021-01-31", - "id" : 42, - "active" : true, - "created_at" : "2021-01-20T22:11:48.151Z", - "revoked" : false, - "access_level": 40 - } -] -``` - -## Create a project access token - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55408) in GitLab 13.10. - -Create a project access token. - -```plaintext -POST projects/:id/access_tokens -``` - -| Attribute | Type | required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | -| `name` | String | yes | The name of the project access token | -| `scopes` | `Array[String]` | yes | [List of scopes](../user/project/settings/project_access_tokens.md#scopes-for-a-project-access-token) | -| `access_level` | Integer | no | A valid access level. Default value is 40 (Maintainer). Other allowed values are 10 (Guest), 20 (Reporter), and 30 (Developer). | -| `expires_at` | Date | no | The token expires at midnight UTC on that date | - -```shell -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ---header "Content-Type:application/json" \ ---data '{ "name":"test_token", "scopes":["api", "read_repository"], "expires_at":"2021-01-31", "access_level": 30 }' \ -"https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens" -``` - -```json -{ - "scopes" : [ - "api", - "read_repository" - ], - "active" : true, - "name" : "test", - "revoked" : false, - "created_at" : "2021-01-21T19:35:37.921Z", - "user_id" : 166, - "id" : 58, - "expires_at" : "2021-01-31", - "token" : "D4y...Wzr", - "access_level": 30 -} -``` - -## Revoke a project access token - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/238991) in GitLab 13.9. - -Revoke a project access token. - -```plaintext -DELETE projects/:id/access_tokens/:token_id -``` - -| Attribute | Type | required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | -| `token_id` | integer or string | yes | The ID of the project access token | - -```shell -curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<project_id>/access_tokens/<token_id>" -``` - -### Responses - -- `204: No Content` if successfully revoked. -- `400 Bad Request` or `404 Not Found` if not revoked successfully. +<!-- This redirect file can be deleted after <2022-04-06>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/runners.md b/doc/api/runners.md index 5e84080ecb5..e53062ce074 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -573,17 +573,18 @@ Register a new runner for the instance. POST /runners ``` -| Attribute | Type | Required | Description | -|--------------|---------|----------|---------------------| -| `token` | string | yes | [Registration token](#registration-and-authentication-tokens). | -| `description`| string | no | Runner's description| -| `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin area of the UI. | -| `active` | boolean | no | Whether the runner is active | -| `locked` | boolean | no | Whether the runner should be locked for current project | -| `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 handles the job | +| Attribute | Type | Required | Description | +|-------------------|----------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `token` | string | yes | [Registration token](#registration-and-authentication-tokens). | +| `description` | string | no | Runner's description | +| `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin area of the UI. | +| `active` | boolean | no | Whether the runner is active | +| `locked` | boolean | no | Whether the runner should be locked for current project | +| `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 handles the job | +| `maintainer_note` | string | no | Free-form maintainer notes for the runner (255 characters) | ```shell curl --request POST "https://gitlab.example.com/api/v4/runners" \ diff --git a/doc/api/scim.md b/doc/api/scim.md index 2d9cc148412..acc6a6ae686 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/search.md b/doc/api/search.md index d3f0cba9234..2969cf439dd 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -1,14 +1,12 @@ --- 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/#assignments" -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Search API **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41763) in GitLab 10.5. -> - [Feature flag `search_filter_by_confidential` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/244923) in GitLab 13.6. +> [Feature flag `search_filter_by_confidential` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/244923) in GitLab 13.6. Every API call to search must be authenticated. diff --git a/doc/api/settings.md b/doc/api/settings.md index e953990c091..2ed841b885c 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -385,7 +385,7 @@ listed in the descriptions of the relevant settings. | `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up. | | `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes. | | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | -| `shared_runners_minutes` **(PREMIUM)** | integer | required by: `shared_runners_enabled` | Set the maximum number of pipeline minutes that a group can use on shared runners per month. | +| `shared_runners_minutes` **(PREMIUM)** | integer | required by: `shared_runners_enabled` | Set the maximum number of CI/CD minutes that a group can use on shared runners per month. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | | `sidekiq_job_limiter_mode` | string | no | `track` or `compress`. Sets the behavior for [Sidekiq job size limits](../user/admin_area/settings/sidekiq_job_limits.md). Default: 'compress'. | | `sidekiq_job_limiter_compression_threshold_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are compressed before being stored in Redis. Default: 100 000 bytes (100KB). | diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 629dfebbefc..52bcd072de9 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -1,14 +1,11 @@ --- 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" -type: reference, api +info: To 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 API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6373) in GitLab 8.15. - Snippets API operates on [snippets](../user/snippets.md). Related APIs exist for [project snippets](project_snippets.md) and [moving snippets between storages](snippet_repository_storage_moves.md). @@ -449,8 +446,6 @@ Example response: ## Get user agent details -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12655) in GitLab 9.4. - NOTE: Available only for administrators. diff --git a/doc/api/statistics.md b/doc/api/statistics.md index 75dfa0de705..59197260988 100644 --- a/doc/api/statistics.md +++ b/doc/api/statistics.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/api/tags.md b/doc/api/tags.md index bbde6c1491b..6aa40cf476d 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -1,16 +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/#assignments" -type: reference, api +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Tags API **(FREE)** ## List project repository tags -Get a list of repository tags from a project, sorted by name in reverse -alphabetical order. This endpoint can be accessed without authentication if the +Get a list of repository tags from a project, sorted by update date and time in descending order. This endpoint can be accessed without authentication if the repository is publicly accessible. ```plaintext @@ -26,8 +24,6 @@ Parameters: | `sort` | string | no | Return tags sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Return list of tags matching the search criteria. You can use `^term` and `term$` to find tags that begin and end with `term` respectively. | -> Support for `search` was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54401) in GitLab 11.8. - ```json [ { diff --git a/doc/api/users.md b/doc/api/users.md index 292dc411e5b..28e1512ea12 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -434,7 +434,7 @@ Parameters: | `email` | Yes | Email | | `extern_uid` | No | External UID | | `external` | No | Flags the user as external - true or false (default) | -| `extra_shared_runners_minutes_limit` | No | Extra pipeline minutes quota for this user (purchased in addition to the minutes included in the plan) **(PREMIUM)** | +| `extra_shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Additional CI/CD minutes for this user. | | `force_random_password` | No | Set user password to a random value - true or false (default) | | `group_id_for_saml` | No | ID of group where SAML has been configured | | `linkedin` | No | LinkedIn | @@ -447,7 +447,7 @@ Parameters: | `projects_limit` | No | Number of projects user can create | | `provider` | No | External provider name | | `reset_password` | No | Send user password reset link - true or false(default) | -| `shared_runners_minutes_limit` | No | Pipeline minutes quota for this user (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` **(PREMIUM)** | +| `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. | | `skip_confirmation` | No | Skip confirmation - true or false (default) | | `skype` | No | Skype ID | | `theme_id` | No | The GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) | @@ -476,7 +476,7 @@ Parameters: | `email` | No | Email | | `extern_uid` | No | External UID | | `external` | No | Flags the user as external - true or false (default) | -| `extra_shared_runners_minutes_limit` | No | Extra pipeline minutes quota for this user (purchased in addition to the minutes included in the plan) **(PREMIUM)** | +| `extra_shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Additional CI/CD minutes for this user. | | `group_id_for_saml` | No | ID of group where SAML has been configured | | `id` | Yes | The ID of the user | | `linkedin` | No | LinkedIn | @@ -489,7 +489,7 @@ Parameters: | `projects_limit` | No | Limit projects each user can create | | `provider` | No | External provider name | | `public_email` | No | The public email of the user (must be already verified) | -| `shared_runners_minutes_limit` | No | Pipeline minutes quota for this user (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` **(PREMIUM)** | +| `shared_runners_minutes_limit` **(PREMIUM)** | No | Can be set by administrators only. Maximum number of monthly CI/CD minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0`. | | `skip_reconfirmation` | No | Skip reconfirmation - true or false (default) | | `skype` | No | Skype ID | | `theme_id` | No | The GitLab theme for the user (see [the user preference docs](../user/profile/preferences.md#navigation-theme) for more information) | diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index 1c6f7a760e6..18d97e30643 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -19,7 +19,7 @@ This API is in the process of being deprecated and considered unstable. The response payload may be subject to change or breakage across GitLab releases. Please use the [GraphQL API](graphql/reference/index.md#queryvulnerabilities) -instead. +instead. See the [GraphQL examples](#replace-vulnerability-rest-api-with-graphql) to get started. Every API call to vulnerabilities must be [authenticated](index.md#authentication). @@ -272,3 +272,185 @@ Example response: "closed_at": null } ``` + +## Replace Vulnerability REST API with GraphQL + +To prepare for the [upcoming deprecation](https://gitlab.com/groups/gitlab-org/-/epics/5118) of +the Vulnerability REST API endpoint, use the examples below to perform the equivalent operations +with the GraphQL API. + +### GraphQL - Single vulnerability + +Use [`Query.vulnerability`](graphql/reference/#queryvulnerability). + +```graphql +{ + vulnerability(id: "gid://gitlab/Vulnerability/20345379") { + title + description + state + severity + reportType + project { + id + name + fullPath + } + detectedAt + confirmedAt + resolvedAt + resolvedBy { + id + username + } + } +} +``` + +Example response: + +```json +{ + "data": { + "vulnerability": { + "title": "Improper Input Validation in railties", + "description": "A remote code execution vulnerability in development mode Rails beta3 can allow an attacker to guess the automatically generated development mode secret token. This secret token can be used in combination with other Rails internals to escalate to a remote code execution exploit.", + "state": "RESOLVED", + "severity": "CRITICAL", + "reportType": "DEPENDENCY_SCANNING", + "project": { + "id": "gid://gitlab/Project/6102100", + "name": "security-reports", + "fullPath": "gitlab-examples/security/security-reports" + }, + "detectedAt": "2021-10-14T03:13:41Z", + "confirmedAt": "2021-12-14T01:45:56Z", + "resolvedAt": "2021-12-14T01:45:59Z", + "resolvedBy": { + "id": "gid://gitlab/User/480804", + "username": "thiagocsf" + } + } + } +} +``` + +### GraphQL - Confirm vulnerability + +Use [`Mutation.vulnerabilityConfirm`](graphql/reference/#mutationvulnerabilityconfirm). + +```graphql +mutation { + vulnerabilityConfirm(input: { id: "gid://gitlab/Vulnerability/23577695"}) { + vulnerability { + state + } + errors + } +} +``` + +Example response: + +```json +{ + "data": { + "vulnerabilityConfirm": { + "vulnerability": { + "state": "CONFIRMED" + }, + "errors": [] + } + } +} +``` + +### GraphQL - Resolve vulnerability + +Use [`Mutation.vulnerabilityResolve`](graphql/reference/#mutationvulnerabilityresolve). + +```graphql +mutation { + vulnerabilityResolve(input: { id: "gid://gitlab/Vulnerability/23577695"}) { + vulnerability { + state + } + errors + } +} +``` + +Example response: + +```json +{ + "data": { + "vulnerabilityConfirm": { + "vulnerability": { + "state": "RESOLVED" + }, + "errors": [] + } + } +} +``` + +### GraphQL - Dismiss vulnerability + +Use [`Mutation.vulnerabilityDismiss`](graphql/reference/#mutationvulnerabilitydismiss). + +```graphql +mutation { + vulnerabilityDismiss(input: { id: "gid://gitlab/Vulnerability/23577695"}) { + vulnerability { + state + } + errors + } +} +``` + +Example response: + +```json +{ + "data": { + "vulnerabilityConfirm": { + "vulnerability": { + "state": "DISMISSED" + }, + "errors": [] + } + } +} +``` + +### GraphQL - Revert vulnerability to detected state + +Use [`Mutation.vulnerabilityRevertToDetected`](graphql/reference/#mutationvulnerabilityreverttodetected). + +```graphql +mutation { + vulnerabilityRevertToDetected(input: { id: "gid://gitlab/Vulnerability/20345379"}) { + vulnerability { + state + } + errors + } +} +``` + +Example response: + +```json +{ + "data": { + "vulnerabilityConfirm": { + "vulnerability": { + "state": "DETECTED" + }, + "errors": [] + } + } +} +``` diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index 36604ebf87d..20bbe66549d 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -25,9 +25,11 @@ If a user is able to access the project but does not have permission to any request for vulnerability findings of this project results in a `403` status code. WARNING: -This API is in an alpha stage and considered unstable. +This API is in the process of being deprecated and considered unstable. The response payload may be subject to change or breakage -across GitLab releases. +across GitLab releases. Please use the +[GraphQL API](graphql/reference/index.md#queryvulnerabilities) +instead. See the [GraphQL examples](#replace-vulnerability-findings-rest-api-with-graphql) to get started. ## Vulnerability findings pagination @@ -137,3 +139,130 @@ Example response: } ] ``` + +## Replace Vulnerability Findings REST API with GraphQL + +To prepare for the [upcoming deprecation](https://gitlab.com/groups/gitlab-org/-/epics/5118) of +the Vulnerability Findings REST API endpoint, use the examples below to perform the equivalent operations +with the GraphQL API. + +### GraphQL - Project vulnerabilities + +Use [`Project.vulnerabilities`](graphql/reference/#projectvulnerabilities). + +```graphql +{ + project(fullPath: "root/security-reports") { + vulnerabilities { + nodes{ + id + reportType + title + severity + scanner { + externalId + name + vendor + } + identifiers { + externalType + externalId + name + url + } + falsePositive + project { + id + name + fullPath + } + description + links { + name + url + } + location { + ... on + VulnerabilityLocationSast { + file + startLine + endLine + vulnerableClass + vulnerableMethod + blobPath + } + } + details { + ... on + VulnerabilityDetailCode { + description + fieldName + lang + name + value + } + } + state + } + } + } +} +``` + +Example response: + +```json +{ + "data": { + "project": { + "vulnerabilities": { + "nodes": [ + { + "id": "gid://gitlab/Vulnerability/236", + "reportType": "SAST", + "title": "Generic Object Injection Sink", + "severity": "CRITICAL", + "scanner": { + "externalId": "eslint", + "name": "ESLint", + "vendor": "GitLab" + }, + "identifiers": [ + { + "externalType": "eslint_rule_id", + "externalId": "security/detect-object-injection", + "name": "ESLint rule ID security/detect-object-injection", + "url": "https://github.com/nodesecurity/eslint-plugin-security#detect-object-injection" + }, + { + "externalType": "cwe", + "externalId": "94", + "name": "CWE-94", + "url": "https://cwe.mitre.org/data/definitions/94.html" + } + ], + "falsePositive": false, + "project": { + "id": "gid://gitlab/Project/20", + "name": "Security Reports", + "fullPath": "root/security-reports" + }, + "description": "Bracket object notation with user input is present, this might allow an attacker to access all properties of the object and even it's prototype, leading to possible code execution.", + "links": [], + "location": { + "file": "src/js/main.js", + "startLine": "28", + "endLine": "28", + "vulnerableClass": null, + "vulnerableMethod": null, + "blobPath": "/root/security-reports/-/blob/91031428a5b5dbb81e8d889738b1875c1bfea787/src/js/main.js" + }, + "details": [], + "state": "DETECTED" + } + ] + } + } + } +} +``` diff --git a/doc/api/wikis.md b/doc/api/wikis.md index 8f71097aa0f..fb49e9465bc 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -1,14 +1,11 @@ --- 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" -type: reference, api +info: To 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 wikis API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13372) in GitLab 10.0. - The project [wikis](../user/project/wiki/index.md) API is available only in APIv4. An API for [group wikis](group_wikis.md) is also available. diff --git a/doc/architecture/blueprints/ci_data_decay/index.md b/doc/architecture/blueprints/ci_data_decay/index.md new file mode 100644 index 00000000000..155c781b04a --- /dev/null +++ b/doc/architecture/blueprints/ci_data_decay/index.md @@ -0,0 +1,255 @@ +--- +stage: none +group: unassigned +comments: false +description: 'CI/CD data time decay' +--- + +# CI/CD data time decay + +## Summary + +GitLab CI/CD is one of the most data and compute intensive components of GitLab. +Since its [initial release in November 2012](https://about.gitlab.com/blog/2012/11/13/continuous-integration-server-from-gitlab/), +the CI/CD subsystem has evolved significantly. It was [integrated into GitLab in September 2015](https://about.gitlab.com/releases/2015/09/22/gitlab-8-0-released/) +and has become [one of the most beloved CI/CD solutions](https://about.gitlab.com/blog/2017/09/27/gitlab-leader-continuous-integration-forrester-wave/). + +On February 1st, 2021, GitLab.com surpassed 1 billion CI/CD builds, and the number of +builds [continues to grow exponentially](../ci_scale/index.md). + +GitLab CI/CD has come a long way since the initial release, but the design of +the data storage for pipeline builds remains almost the same since 2012. In +2021 we started working on database decomposition and extracting CI/CD data to +ia separate database. Now we want to improve the architecture of GitLab CI/CD +product to enable further scaling. + +_Disclaimer: The following contains information related to upcoming products, +features, and functionality._ + +_It is important to note that the information presented is for informational +purposes only. Please do not rely on this information for purchasing or +planning purposes._ + +_As with all projects, the items mentioned in this document and linked pages are +subject to change or delay. The development, release and timing of any +products, features, or functionality remain at the sole discretion of GitLab +Inc._ + +## Goals + +**Implement a new architecture of CI/CD data storage to enable scaling.** + +## Challenges + +There are more than two billion rows describing CI/CD builds in GitLab.com's +database. This data represents a sizable portion of the whole data stored in +PostgreSQL database running on GitLab.com. + +This volume contributes to significant performance problems, development +challenges and is often related to production incidents. + +We also expect a [significant growth in the number of builds executed on +GitLab.com](../ci_scale/index.md) in the upcoming years. + +## Opportunity + +CI/CD data is subject to +[time-decay](https://about.gitlab.com/company/team/structure/working-groups/database-scalability/time-decay.html) +because, usually, pipelines that are a few months old are not frequently +accessed or are even not relevant anymore. Restricting access to processing +pipelines that are older than a few months might help us to move this data out +of the primary database, to a different storage, that is more performant and +cost effective. + +It is already possible to prevent processing builds [that have been +archived](../../../user/admin_area/settings/continuous_integration.md#archive-jobs). +When a build gets archived it will not be possible to retry it, but we still do +keep all the processing metadata in the database, and it consumes resources +that are scarce in the primary database. + +In order to improve performance and make it easier to scale CI/CD data storage +we might want to follow these three tracks described below. + + + +<!-- markdownlint-disable MD029 --> + +1. Partition builds queuing tables +2. Archive CI/CD data into partitioned database schema +3. Migrate archived builds metadata out of primary database + +<!-- markdownlint-enable MD029 --> + +### Migrate archived builds metadata out of primary database + +Once a build (or a pipeline) gets archived, it is no longer possible to resume +pipeline processing in such pipeline. It means that all the metadata, we store +in PostgreSQL, that is needed to efficiently and reliably process builds can be +safely moved to a different data store. + +Currently, storing pipeline processing data is expensive as this kind of CI/CD +data represents a significant portion of data stored in CI/CD tables. Once we +restrict access to processing archived pipelines, we can move this metadata to +a different place - preferably object storage - and make it accessible on +demand, when it is really needed again (for example for compliance or auditing purposes). + +We need to evaluate whether moving data is the most optimal solution. We might +be able to use de-duplication of metadata entries and other normalization +strategies to consume less storage while retaining ability to query this +dataset. Technical evaluation will be required to find the best solution here. + +Epic: [Migrate archived builds metadata out of primary database](https://gitlab.com/groups/gitlab-org/-/epics/7216). + +### Archive CI/CD data into partitioned database schema + +After we move CI/CD metadata to a different store, the problem of having +billions of rows describing pipelines, builds and artifacts, remains. We still +need to keep reference to the metadata we store in object storage and we still +do need to be able to retrieve this information reliably in bulk (or search +through it). + +It means that by moving data to object storage we might not be able to reduce +the number of rows in CI/CD tables. Moving data to object storage should help +with reducing the data size, but not the quantity of entries describing this +data. Because of this limitation, we still want to partition CI/CD data to +reduce the impact on the database (indices size, auto-vacuum time and +frequency). + +Our intent here is not to move this data out of our primary database elsewhere. +What want to divide very large database tables, that store CI/CD data, into +multiple smaller ones, using PostgreSQL partitioning features. + +There are a few approaches we can take to partition CI/CD data. A promising one +is using list-based partitioning where a partition number is assigned a +pipeline, and gets propagated to all resources that are related to this +pipeline. We assign the partition number based on when the pipeline was created +or when we observed the last processing activity in it. This is very flexible +because we can extend this partitioning strategy at will; for example with this +strategy we can assign an arbitrary partition number based on multiple +partitioning keys, combining time-decay-based partitioning with tenant-based +partitioning on the application level. + +Partitioning rarely accessed data should also follow the policy defined for +builds archival, to make it consistent and reliable. + +Epic: [Archive CI/CD data into partitioned database schema](https://gitlab.com/groups/gitlab-org/-/epics/5417). + +### Partition builds queuing tables + +While working on the [CI/CD Scale](../ci_scale/index.md) blueprint, we have +introduced a [new architecture for queuing CI/CD builds](https://gitlab.com/groups/gitlab-org/-/epics/5909#note_680407908) +for execution. + +This allowed us to significantly improve performance. We still consider the new +solution as an intermediate mechanism, needed before we start working on the +next iteration. The following iteration that should improve the architecture of +builds queuing even more (it might require moving off the PostgreSQL fully or +partially). + +In the meantime we want to ship another iteration, an intermediate step towards +more flexible and reliable solution. We want to partition the new queuing +tables, to reduce the impact on the database, to improve reliability and +database health. + +Partitioning of CI/CD queuing tables does not need to follow the policy defined +for builds archival. Instead we should leverage a long-standing policy saying +that builds created more 24 hours ago need to be removed from the queue. This +business rule is present in the product since the inception of GitLab CI. + +Epic: [Partition builds queuing tables](https://gitlab.com/gitlab-org/gitlab/-/issues/347027). + +## Principles + +All the three tracks we will use to implement CI/CD time decay pattern are +associated with some challenges. As we progress with the implementation we will +need to solve many problems and devise many implementation details to make this +successful. + +Below, we documented a few foundational principles to make it easier for +everyone to understand the vision described in this architectural blueprint. + +### Removing pipeline data + +While it might be tempting to simply remove old or archived data from our +databases this should be avoided. It is usually not desired to permanently +remove user data unless consent is given to do so. We can, however, move data +to a different data store, like object storage. + +Archived data can still be needed sometimes (for example for compliance or +auditing reasons). We want to be able to retrieve this data if needed, as long +as permanent removal has not been requested or approved by a user. + +### Accessing pipeline data in the UI + +Implementing CI/CD data time-decay through partitioning might be challenging +when we still want to make it possible for users to access data stored in many +partitions. + +We want to retain simplicity of accessing pipeline data in the UI. It will +require some backstage changes in how we reference pipeline data from other +resources, but we don't want to make it more difficult for users to find their +pipelines in the UI. + +We may need to add "Archived" tab on the pipelines / builds list pages, but we +should be able to avoid additional steps / clicks when someone wants to view +pipeline status or builds associated with a merge request or a deployment. + +We also may need to disable search in the "Archived" tab on pipelines / builds +list pages. + +### Accessing pipeline data through the API + +We accept the possible necessity of building a separate API endpoint / +endpoints needed to access pipeline data through the API. + +In the new API users might need to provide a time range in which the data has +been created to search through their pipelines / builds. In order to make it +efficient it might be necessary to restrict access to querying data residing in +more than two partitions at once. We can do that by supporting time ranges +spanning the duration that equals to the builds archival policy. + +It is possible to still allow users to use the old API to access archived +pipelines data, although a user provided partition identifier may be required. + +## Iterations + +All three tracks can be worked on in parallel: + +1. [Migrate archived build metadata to object storage](https://gitlab.com/groups/gitlab-org/-/epics/7216). +1. [Partition CI/CD data that have been archived](https://gitlab.com/groups/gitlab-org/-/epics/5417). +1. [Partition CI/CD queuing tables using list partitioning](https://gitlab.com/gitlab-org/gitlab/-/issues/347027) + +## Status + +In progress. + +## Who + +Proposal: + +<!-- vale gitlab.Spelling = NO --> + +| Role | Who +|------------------------------|-------------------------| +| Author | Grzegorz Bizon | +| Engineering Leader | Cheryl Li | +| Product Manager | Jackie Porter | +| Architecture Evolution Coach | Kamil Trzciński | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Leadership | Cheryl Li | +| Product | Jackie Porter | +| Engineering | Grzegorz Bizon | + +Domain experts: + +| Area | Who +|------------------------------|------------------------| +| Verify / Pipeline execution | Fabio Pitino | +| Verify / Pipeline execution | Marius Bobin | +| PostgreSQL Database | Andreas Brandl | + +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/architecture/blueprints/ci_data_decay/pipeline_data_time_decay.png b/doc/architecture/blueprints/ci_data_decay/pipeline_data_time_decay.png Binary files differnew file mode 100644 index 00000000000..e094b87933a --- /dev/null +++ b/doc/architecture/blueprints/ci_data_decay/pipeline_data_time_decay.png diff --git a/doc/architecture/blueprints/container_registry_metadata_database/index.md b/doc/architecture/blueprints/container_registry_metadata_database/index.md index a38a8727dc4..c1aac235085 100644 --- a/doc/architecture/blueprints/container_registry_metadata_database/index.md +++ b/doc/architecture/blueprints/container_registry_metadata_database/index.md @@ -78,7 +78,7 @@ The single entrypoint for the registry is the [HTTP API](https://gitlab.com/gitl | Operation | UI | Background | Observations | | ------------------------------------------------------------ | ------------------ | ------------------------ | ------------------------------------------------------------ | | [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | **{check-circle}** Yes | **{check-circle}** Yes | Used globally to ensure that the registry supports the Docker Distribution V2 API, as well as for identifying whether GitLab Rails is talking to the GitLab Container Registry or a third-party one (used to toggle features only available in the former). | -| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | **{check-circle}** Yes | **{check-circle}** Yes | Used to list and show tags in the UI. Used to list tags in the background for [cleanup policies](../../../user/packages/container_registry/#cleanup-policy) and [Geo replication](../../../administration/geo/replication/docker_registry.md). | +| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | **{check-circle}** Yes | **{check-circle}** Yes | Used to list and show tags in the UI. Used to list tags in the background for [cleanup policies](../../../user/packages/container_registry/reduce_container_registry_storage.md#cleanup-policy) and [Geo replication](../../../administration/geo/replication/docker_registry.md). | | [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | **{check-circle}** Yes | **{dotted-circle}** No | Used to get the digest of a manifest by tag. This is then used to pull the manifest and show the tag details in the UI. | | [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | **{check-circle}** Yes | **{dotted-circle}** No | Used to show the image size and the manifest digest in the tag details UI. | | [Pull blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-a-layer) | **{check-circle}** Yes | **{dotted-circle}** No | Used to show the configuration digest and the creation date in the tag details UI. | diff --git a/doc/architecture/blueprints/database_testing/index.md b/doc/architecture/blueprints/database_testing/index.md index 38629e7348d..4676caab85d 100644 --- a/doc/architecture/blueprints/database_testing/index.md +++ b/doc/architecture/blueprints/database_testing/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false description: 'Database Testing' --- diff --git a/doc/architecture/blueprints/runner_scaling/gitlab-autoscaling-overview.png b/doc/architecture/blueprints/runner_scaling/gitlab-autoscaling-overview.png Binary files differnew file mode 100644 index 00000000000..c3ba615784f --- /dev/null +++ b/doc/architecture/blueprints/runner_scaling/gitlab-autoscaling-overview.png diff --git a/doc/architecture/blueprints/runner_scaling/index.md b/doc/architecture/blueprints/runner_scaling/index.md new file mode 100644 index 00000000000..8e47b5fda8c --- /dev/null +++ b/doc/architecture/blueprints/runner_scaling/index.md @@ -0,0 +1,239 @@ +--- +stage: none +group: unassigned +comments: false +description: 'Next Runner Auto-scaling Architecture' +--- + +# Next Runner Auto-scaling Architecture + +## Summary + +GitLab Runner is a core component of GitLab CI/CD. It makes it possible to run +CI/CD jobs in a reliable and concurrent environment. It has been initially +introduced by Kamil Trzciński in early 2015 to replace a Ruby version of the +same service. GitLab Runner written in Go turned out to be easier to use by the +wider community, it was more efficient and reliable than the previous, +Ruby-based, version. + +In February 2016 Kamil Trzciński [implemented an auto-scaling feature](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/53) +to leverage cloud infrastructure to run many CI/CD jobs in parallel. This +feature has become a foundation supporting CI/CD adoption on GitLab.com over +the years, where we now run around 4 million builds per day at peak. + +During the initial implementation a decision was made to use Docker Machine: + +> Is easy to use. Is well documented. Is well supported and constantly +> extended. It supports almost any cloud provider or virtualization +> infrastructure. We need minimal amount of changes to support Docker Machine: +> machine enumeration and inspection. We don't need to implement any "cloud +> specific" features. + +This design choice was crucial for the GitLab Runner success. Since that time +the auto-scaling feature has been used by many users and customers and enabled +rapid growth of CI/CD adoption on GitLab.com. + +We can not, however, continue using Docker Machine. Work on that project [was +paused in July 2018](https://github.com/docker/machine/issues/4537) and there +was no development made since that time (except for some highly important +security fixes). In 2018, after Docker Machine entered the “maintenance mode”, +we decided to create [our own fork](https://gitlab.com/gitlab-org/ci-cd/docker-machine) +to be able to keep using this and ship fixes and updates needed for our use case. +[On September 26th, 2021 the project got archived](https://github.com/docker/docker.github.io/commit/2dc8b49dcbe85686cc7230e17aff8e9944cb47a5) +and the documentation for it has been removed from the official page. This +means that the original reason to use Docker Machine is no longer valid too. + +To keep supporting our customers and the wider community we need to design a +new mechanism for GitLab Runner autoscaling. It not only needs to support +auto-scaling, but it also needs to do that in the way to enable us to build on +top of it to improve efficiency, reliability and availability. + +We call this new mechanism the “next GitLab Runner Scaling architecture”. + +_Disclaimer The following contain information related to upcoming products, +features, and functionality._ + +_It is important to note that the information presented is for informational +purposes only. Please do not rely on this information for purchasing or +planning purposes._ + +_As with all projects, the items mentioned in this document and linked pages are +subject to change or delay. The development, release and timing of any +products, features, or functionality remain at the sole discretion of GitLab +Inc._ + +## Proposal + +Currently, GitLab Runner auto-scaling can be configured in a few ways. Some +customers are successfully using an auto-scaled environment in Kubernetes. We +know that a custom and unofficial GitLab Runner version has been built to make +auto-scaling on Kubernetes more reliable. We recognize the importance of having +a really good Kubernetes solution for running multiple jobs in parallel, but +refinements in this area are out of scope for this architectural initiative. + +We want to focus on resolving problems with Docker Machine and replacing this +mechanism with a reliable and flexible mechanism. We might be unable to build a +drop-in replacement for Docker Machine, as there are presumably many reasons +why it has been deprecated. It is very difficult to maintain compatibility with +so many cloud providers, and it seems that Docker Machine has been deprecated +in favor of Docker Desktop, which is not a viable replacement for us. [This +issue](https://github.com/docker/roadmap/issues/245) contains a discussion +about how people are using Docker Machine right now, and it seems that GitLab +CI is one of the most frequent reasons for people to keep using Docker Machine. + +There is also an opportunity in being able to optionally run multiple jobs in a +single, larger virtual machine. We can’t do that today, but we know that this +can potentially significantly improve efficiency. We might want to build a new +architecture that makes it easier and allows us to test how efficient it is +with PoCs. Running multiple jobs on a single machine can also make it possible +to reuse what we call a “sticky context” - a space for build artifacts / user +data that can be shared between job runs. + +### 💡 Design a simple abstraction that users will be able to build on top of + +Because there is no viable replacement and we might be unable to support all +cloud providers that Docker Machine used to support, the key design requirement +is to make it really simple and easy for the wider community to write a custom +GitLab auto-scaling plugin, whatever cloud provider they might be using. We +want to design a simple abstraction that users will be able to build on top, as +will we to support existing workflows on GitLab.com. + +The designed mechanism should abstract what Docker Machine executor has been doing: +providing a way to create an external Docker environment, waiting to execute +jobs by provisioning this environment and returning credentials required to +perform these operations. + +The new plugin system should be available for all major platforms: Linux, +Windows, MacOS. + +### 💡 Migrate existing Docker Machine solution to a plugin + +Once we design and implement the new abstraction, we should be able to migrate +existing Docker Machine mechanisms to a plugin. This will make it possible for +users and customers to immediately start using the new architecture, but still +keep their existing workflows and configuration for Docker Machine. This will +give everyone time to migrate to the new architecture before we drop support +for the legacy auto-scaling entirely. + +### 💡 Build plugins for AWS, Google Cloud Platform and Azure + +Although we might be unable to add support for all the cloud providers that +Docker Machine used to support, it seems to be important to provide +GitLab-maintained plugins for the major cloud providers like AWS, Google Cloud +Platform and Azure. + +We should build them, presumably in separate repositories, in a way that they +are easy to contribute to, fork, modify for certain needs the wider community +team members might have. It should be also easy to install a new plugin without +the need of rebuilding GitLab Runner whenever it happens. + +### 💡 Write a solid documentation about how to build your own plugin + +It is important to show users how to build an auto-scaling plugin, so that they +can implement support for their own cloud infrastructure. + +Building new plugins should be simple, and with the support of great +documentation it should not require advanced skills, like understanding how +gRPC works. We want to design the plugin system in a way that the entry barrier +for contributing new plugins is very low. + +### 💡 Build a PoC to run multiple builds on a single machine + +We want to better understand what kind of efficiency can running multiple jobs +on a single machine bring. It is difficult to predict that, so ideally we +should build a PoC that will help us to better understand what we can expect +from this. + +To run this experiement we most likely we will need to build an experimental +plugin, that not only allows us to schedule running multiple builds on a single +machine, but also has a set of comprehensive metrics built into it, to make it +easier to understand how it performs. + +## Details + +How the abstraction for the custom provider will look exactly is something that +we will need to prototype, PoC and decide in a data-informed way. There are a +few proposals that we should describe in detail, develop requirements for, PoC +and score. We will choose the solution that seems to support our goals the +most. + +In order to describe the proposals we first need to better explain what part of +the GitLab Runner needs to be abstracted away. To make this easier to grasp +these concepts, let's take a look at the current auto-scaling architecture and +sequence diagram. + + + +On the diagrams above we see that currently a GitLab Runner Manager runs on a +machine that has access to a cloud provider’s API. It is using Docker Machine +to provision new Virtual Machines with Docker Engine installed and it +configures the Docker daemon there to allow external authenticated requests. It +stores credentials to such ephemeral Docker environments on disk. Once a +machine has been provisioned and made available for GitLab Runner Manager to +run builds, it is using one of the existing executors to run a user-provided +script. In auto-scaling, this is typically done using Docker executor. + +### Custom provider + +In order to reduce the scope of work, we only want to introduce the new +abstraction layer in one place. + +A few years ago we introduced the [Custom Executor](https://docs.gitlab.com/runner/executors/custom.html) +feature in GitLab Runner. It allows users to design custom build execution +methods. The custom executor driver can be implemented in any way - from a +simple shell script to a dedicated binary - that is then used by a Runner +through os/exec system calls. + +Thanks to the custom executor abstraction there is no more need to implement +new executors internally in Runner. Users who have specific needs can implement +their own drivers and don’t need to wait for us to make their work part of the +“official” GitLab Runner. As each driver is a separate project, it also makes +it easier to create communities around them, where interested people can +collaborate together on improvements and bug fixes. + +We want to design the new Custom Provider to replicate the success of the +Custom Executor. It will make it easier for users to build their own ways to +provide a context and an environment in which a build will be executed by one +of the Custom Executors. + +There are multiple solutions to implementing a custom provider abstraction. We +can use raw Go plugins, Hashcorp’s Go Plugin, HTTP interface or gRPC based +facade service. There are many solutions, and we want to choose the most +optimal one. In order to do that, we will describe the solutions in a separate +document, define requirements and score the solution accordingly. This will +allow us to choose a solution that will work best for us and the wider +community. + +## Status + +Status: RFC. + +## Who + +Proposal: + +<!-- vale gitlab.Spelling = NO --> + +| Role | Who +|------------------------------|------------------------------------------| +| Authors | Grzegorz Bizon, Tomasz Maczukin | +| Architecture Evolution Coach | Kamil Trzciński | +| Engineering Leader | Elliot Rushton, Cheryl Li | +| Product Manager | Darren Eastman, Jackie Porter | +| Domain Expert / Runner | Arran Walker | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Leadership | Elliot Rushton | +| Product | Darren Eastman | +| Engineering | Tomasz Maczukin | + +Domain experts: + +| Area | Who +|------------------------------|------------------------| +| Domain Expert / Runner | Arran Walker | + +<!-- vale gitlab.Spelling = YES --> diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 491454aed28..c634491662d 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -235,6 +235,39 @@ test_async: - node ./specs/start.js ./specs/async.spec.js ``` +#### Compute the cache key from the lock file + +You can use [`cache:key:files`](../yaml/index.md#cachekeyfiles) to compute the cache +key from a lock file like `package-lock.json` or `yarn.lock`, and reuse it in many jobs. + +```yaml +# Cache modules using lock file +cache: + key: + files: + - package-lock.json + paths: + - .npm/ +``` + +If you're using [Yarn](https://yarnpkg.com/), you can use [`yarn-offline-mirror`](https://classic.yarnpkg.com/blog/2016/11/24/offline-mirror/) +to cache the zipped `node_modules` tarballs. The cache generates more quickly, because +fewer files have to be compressed: + +```yaml +job: + script: + - echo 'yarn-offline-mirror ".yarn-cache/"' >> .yarnrc + - echo 'yarn-offline-mirror-pruning true' >> .yarnrc + - yarn install --frozen-lockfile --no-progress + cache: + key: + files: + - yarn.lock + paths: + - .yarn-cache/ +``` + ### Cache PHP dependencies If your project uses [Composer](https://getcomposer.org/) to install 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 cf4e846ebb4..0aa7f157602 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -65,8 +65,7 @@ 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 are overwritten by any changes made - upstream in Bitbucket. + The changes must be made in Bitbucket as any changes in the GitLab repository are overwritten by Bitbucket when GitLab next mirrors the repository. Create a file `build_status` and insert the script below and run `chmod +x build_status` in your terminal to make the script executable. diff --git a/doc/ci/ci_cd_for_external_repos/img/ci_cd_for_external_repo.png b/doc/ci/ci_cd_for_external_repos/img/ci_cd_for_external_repo.png Binary files differdeleted file mode 100644 index f068688146b..00000000000 --- a/doc/ci/ci_cd_for_external_repos/img/ci_cd_for_external_repo.png +++ /dev/null diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 7bc138d083d..4e0cd7609cb 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -9,10 +9,6 @@ type: index, howto >[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4642) in GitLab 10.6. -INFO: -Get external repo access and more by upgrading to GitLab Ultimate. -[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-ci-cd-external-docs). - GitLab CI/CD can be used with [GitHub](github_integration.md), [Bitbucket Cloud](bitbucket_integration.md), or any other Git server. diff --git a/doc/ci/cloud_services/aws/index.md b/doc/ci/cloud_services/aws/index.md new file mode 100644 index 00000000000..f09b23db2c5 --- /dev/null +++ b/doc/ci/cloud_services/aws/index.md @@ -0,0 +1,92 @@ +--- +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/#assignments +--- + +# Configure OpenID Connect in AWS to retrieve temporary credentials + +In this tutorial, we'll show you how to use a GitLab CI/CD job with a JSON web token (JWT) to retrieve temporary credentials from AWS without needing to store secrets. +To do this, you must configure OpenID Connect (OIDC) for ID federation between GitLab and AWS. For background and requirements for integrating GitLab using OIDC, see [Connect to cloud services](../index.md). + +To complete this tutorial: + +1. [Add the identity provider](#add-the-identity-provider) +1. [Configure the role and trust](#configure-a-role-and-trust) +1. [Retrieve a temporary credential](#retrieve-temporary-credentials) + +## Add the identity provider + +Create GitLab as a IAM OIDC provider in AWS following these [instructions](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html). + +Include the following information: + +- **Provider URL**: The address of your GitLab instance, such as `https://gitlab.com` or `http://gitlab.example.com`. +- **Audience**: The address of your GitLab instance, such as `https://gitlab.com` or `http://gitlab.example.com`. + - The address must include `https://`. + - Do not include a trailing slash. + +## Configure a role and trust + +After you create the identity provider, configure a [web identity role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html) with conditions for limiting access to GitLab resources. Temporary credentials are obtained using [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html), so set the `Action` to [sts:AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html). + +For the full list of supported filtering types, see [Connect to cloud services](../index.md). + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam::AWS_ACCOUNT:oidc-provider/gitlab.example.com" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "gitlab.example.com:sub": "project_path:mygroup/myproject:ref_type:branch:ref:main" + } + } + } + ] +} +``` + +After the role is created, attach a policy defining permissions to an AWS service (S3, EC2, Secrets Manager). + +## Retrieve temporary credentials + +After you configure the OIDC and role, the GitLab CI/CD job can retrieve a temporary credential from [AWS Security Token Service (STS)](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html). + +```yaml +assume role: + script: + - > + STS=($(aws sts assume-role-with-web-identity + --role-arn ${ROLE_ARN} + --role-session-name "GitLabRunner-${CI_PROJECT_ID}-${CI_PIPELINE_ID}" + --web-identity-token $CI_JOB_JWT_V2 + --duration-seconds 3600 + --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' + --output text)) + - export AWS_ACCESS_KEY_ID="${STS[0]}" + - export AWS_SECRET_ACCESS_KEY="${STS[1]}" + - export AWS_SESSION_TOKEN="${STS[2]}" + - aws sts get-caller-identity +``` + +- `CI_JOB_JWT_V2`: Predefined variable. +- `ROLE_ARN`: The role ARN defined in this [step](#configure-a-role-and-trust). + +## Working example + +See this [reference project](https://gitlab.com/guided-explorations/aws/configure-openid-connect-in-aws) for provisioning OIDC in AWS using Terraform and a sample script to retrieve temporary credentials. + +## Troubleshooting + +### `An error occurred (AccessDenied) when calling the AssumeRoleWithWebIdentity operation: Not authorized to perform sts:AssumeRoleWithWebIdentity` + +This error can occur for multiple reasons: + +- The cloud administrator has not configured the project to use OIDC with GitLab. +- The role is restricted from being run on the branch or tag. See [configure a conditional role](../index.md). diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md new file mode 100644 index 00000000000..73e726ea8a9 --- /dev/null +++ b/doc/ci/cloud_services/index.md @@ -0,0 +1,133 @@ +--- +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/#assignments +--- + +# Connect to cloud services + +> - `CI_JOB_JWT` variable for reading secrets from Vault [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) in GitLab 12.10. +> - `CI_JOB_JWT_V2` variable to support additional OIDC providers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346737) in GitLab 14.7. + +GitLab CI/CD supports [OpenID Connect (OIDC)](https://openid.net/connect/faq/) that allows your build and deployment job access to cloud credentials and services. Historically, teams stored secrets in projects or applied permissions on the GitLab Runner instance to build and deploy. To support this, a predefined variable named `CI_JOB_JWT_V2` is included in the CI/CD job allowing you to follow a scalable and least-privilege security approach. + +## Requirements + +- Account on GitLab. +- Access to a cloud provider that supports OIDC to configure authorization and create roles. + +The original implementation of `CI_JOB_JWT` supports [HashiCorp Vault integration](../examples/authenticating-with-hashicorp-vault/). The updated implementation of `CI_JOB_JWT_V2` supports additional cloud providers with OIDC including AWS, GCP, and Vault. + +WARNING: +The `CI_JOB_JWT_V2` variable is under development [(alpha)](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) and is not yet suitable for production use. + +## Use cases + +- Removes the need to store secrets in your GitLab group or project. Temporary credentials can be retrieved from your cloud provider through OIDC. +- Provides temporary access to cloud resources with granular GitLab conditionals including a group, project, branch, or tag. +- Enables you to define separation of duties in the CI/CD job with conditional access to environments. Historically, apps may have been deployed with a designated GitLab Runner that had only access to staging or production environments. This led to Runner sprawl as each machine had dedicated permissions. +- Allows shared runners to securely access multiple cloud accounts. The access is determined by the JWT token, which is specific to the user running the pipeline. +- Removes the need to create logic to rotate secrets by retrieving temporary credentials by default. + +## How it works + +Each job has a JSON web token (JWT) provided as a CI/CD [predefined variable](../variables/predefined_variables.md) named `CI_JOB_JWT` or `CI_JOB_JWT_V2`. This JWT can be used to authenticate with the OIDC-supported cloud provider such as AWS, GCP, or Vault. + +The following fields are included in the JWT: + +| Field | When | Description | +| ----------------------- | ------ | ----------- | +| `jti` | Always | Unique identifier for this token | +| `iss` | Always | Issuer, the domain of your GitLab instance | +| `iat` | Always | Issued at | +| `nbf` | Always | Not valid before | +| `exp` | Always | Expires at | +| `aud` | Always | Issuer, the domain of your GitLab instance | +| `sub` | Always |`project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` | +| `namespace_id` | Always | Use this to scope to group or user level namespace by ID | +| `namespace_path` | Always | Use this to scope to group or user level namespace by path | +| `project_id` | Always | Use this to scope to project by ID | +| `project_path` | Always | Use this to scope to project by path | +| `user_id` | Always | ID of the user executing the job | +| `user_login` | Always | Username of the user executing the job | +| `user_email` | Always | Email of the user executing the job | +| `pipeline_id` | Always | ID of this pipeline | +| `pipeline_source` | Always | [Pipeline source](../jobs/job_control.md#common-if-clauses-for-rules) | +| `job_id` | Always | ID of this job | +| `ref` | Always | Git ref for this job | +| `ref_type` | Always | Git ref type, either `branch` or `tag` | +| `ref_protected` | Always | `true` if this Git ref is protected, `false` otherwise | +| `environment` | Job is creating a deployment | Environment this job deploys to ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) | +| `environment_protected` | Job is creating a deployment |`true` if deployed environment is protected, `false` otherwise ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) | + +```json +{ + "jti": "c82eeb0c-5c6f-4a33-abf5-4c474b92b558", + "iss": "https://gitlab.example.com", + "aud": "https://gitlab.example.com", + "iat": 1585710286, + "nbf": 1585798372, + "exp": 1585713886, + "sub": "project_path:mygroup/myproject:ref_type:branch:ref:main", + "namespace_id": "1", + "namespace_path": "mygroup", + "project_id": "22", + "project_path": "mygroup/myproject", + "user_id": "42", + "user_login": "myuser", + "user_email": "myuser@example.com", + "pipeline_id": "1212", + "pipeline_source": "web", + "job_id": "1212", + "ref": "auto-deploy-2020-04-01", + "ref_type": "branch", + "ref_protected": "true", + "environment": "production", + "environment_protected": "true" +} +``` + +### Authorization workflow + +```mermaid +sequenceDiagram + participant GitLab + Note right of Cloud: Create OIDC identity provider + Note right of Cloud: Create role with conditionals + Note left of GitLab: CI/CD job with CI_JOB_JWT_V2 + GitLab->>+Cloud: Call cloud API with CI_JOB_JWT_V2 + Note right of Cloud: Decode & verify JWT with public key (https://gitlab/-/jwks) + Note right of Cloud: Validate audience defined in OIDC + Note right of Cloud: Validate conditional (sub, aud) role + Note right of Cloud: Generate credential or fetch secret + Cloud->>GitLab: Return temporary credential + Note left of GitLab: Perform operation + +``` + +1. Create an OIDC identity provider in the cloud (for example, AWS, GCP, Vault). +1. Create a conditional role in the cloud service that filters to a group, project, branch, or tag. +1. The CI/CD job includes a predefined variable `CI_JOB_JWT_V2` that is a JWT token. You can use this token for authorization with your cloud API. +1. The cloud verifies the token, validates the conditional role from the payload, and returns a temporary credential. + +## Configure a conditional role with OIDC claims + +To configure the trust between GitLab and OIDC, you must create a conditional role in the cloud provider that checks against the JWT token. The condition is validated against the JWT to create a trust specifically against two claims, the audience and subject. + +- Audience or `aud`: The URL of the GitLab instance. This is defined when the identity provider is first configured in your cloud provider. +- Subject or `sub`: A concatenation of metadata describing the GitLab CI/CD workflow including the group, project, branch, and tag. The `sub` field is in the following format: + - `project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` + +| Filter type | Example | +| ------------------------------------ | ------------------------------------------------------------ | +| Filter to main branch | `project_path:mygroup/myproject:ref_type:branch:ref:main` | +| Filter to any branch | Wildcard supported. `project_path:mygroup/myproject:ref_type:branch:ref:*` | +| Filter to specific project | `project_path:mygroup/myproject:ref_type:branch:ref:main` | +| Filter to all projects under a group | Wildcard supported. `project_path:mygroup/*:ref_type:branch:ref:main` | +| Filter to a Git tag | Wildcard supported. `project_path:mygroup/*:ref_type:tag:ref:1.0` | + +## OIDC authorization with your cloud provider + +To connect with your cloud provider, see the following tutorials: + +- [Configure OpenID Connect in AWS](aws/index.md) diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 3a05e9aa7d9..9b91cd40338 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -19,7 +19,7 @@ GitLab Runner to support `docker` commands. To enable Docker commands for your CI/CD jobs, you can use: - [The shell executor](#use-the-shell-executor) -- [The Docker executor with the Docker image (Docker-in-Docker)](#use-the-docker-executor-with-the-docker-image-docker-in-docker) +- [Docker-in-Docker](#use-docker-in-docker) - [Docker socket binding](#use-docker-socket-binding) If you don't want to execute a runner in privileged mode, @@ -78,54 +78,29 @@ You can now use `docker` commands (and install `docker-compose` if needed). When you add `gitlab-runner` to the `docker` group, you are effectively granting `gitlab-runner` full root permissions. Learn more about the [security of the `docker` group](https://blog.zopyx.com/on-docker-security-docker-group-considered-harmful/). -### Use the Docker executor with the Docker image (Docker-in-Docker) +### Use Docker-in-Docker "Docker-in-Docker" (`dind`) means: -- Your registered runner uses the [Docker executor](https://docs.gitlab.com/runner/executors/docker.html). +- Your registered runner uses the [Docker executor](https://docs.gitlab.com/runner/executors/docker.html) or the [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html). - The executor uses a [container image of Docker](https://hub.docker.com/_/docker/), provided by Docker, to run your CI/CD jobs. The Docker image has all of the `docker` tools installed and can run the job script in context of the image in privileged mode. -We recommend you use [Docker-in-Docker with TLS enabled](#docker-in-docker-with-tls-enabled), +We recommend you use Docker-in-Docker with TLS enabled, which is supported by [GitLab.com shared runners](../runners/index.md). You should always specify a specific version of the image, like `docker:19.03.12`. If you use a tag like `docker:stable`, you have no control over which version is used. Unpredictable behavior can result, especially when new versions are released. -#### Limitations of Docker-in-Docker +#### Use the Docker executor with Docker-in-Docker -Docker-in-Docker is the recommended configuration, but is -not without its own challenges: +You can use the Docker executor to run jobs in a Docker container. -- **The `docker-compose` command**: This command is not available in this configuration by default. - To use `docker-compose` in your job scripts, follow the `docker-compose` - [installation instructions](https://docs.docker.com/compose/install/). -- **Cache**: Each job runs in a new environment. Concurrent jobs work fine, - because every build gets its own instance of Docker engine and they don't conflict with each other. - However, jobs can be slower because there's no caching of layers. -- **Storage drivers**: By default, earlier versions of Docker use the `vfs` storage driver, - which copies the file system for each job. Docker 17.09 and later use `--storage-driver overlay2`, which is - the recommended storage driver. See [Using the OverlayFS driver](#use-the-overlayfs-driver) for details. -- **Root file system**: Because the `docker:19.03.12-dind` container and the runner container don't share their - root file system, you can use the job's working directory as a mount point for - child containers. For example, if you have files you want to share with a - child container, you might create a subdirectory under `/builds/$CI_PROJECT_PATH` - and use it as your mount point. For a more detailed explanation, view [issue - #41227](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41227). - - ```yaml - variables: - MOUNT_POINT: /builds/$CI_PROJECT_PATH/mnt - script: - - mkdir -p "$MOUNT_POINT" - - docker run -v "$MOUNT_POINT:/mnt" my-docker-image - ``` - -#### Docker-in-Docker with TLS enabled +##### Docker-in-Docker with TLS enabled in the Docker executor > Introduced in GitLab Runner 11.11. @@ -198,7 +173,7 @@ To use Docker-in-Docker with TLS enabled: # https://github.com/docker-library/docker/blob/d45051476babc297257df490d22cbd806f1b11e4/19.03/docker-entrypoint.sh#L23-L29 # # 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. + # https://docs.gitlab.com/ee/ci/services/#accessing-the-services. # # Specify to Docker where to create the certificates. Docker # creates them automatically on boot, and creates @@ -219,7 +194,72 @@ To use Docker-in-Docker with TLS enabled: - docker run my-docker-image /script/to/run/tests ``` -#### Docker-in-Docker with TLS enabled in Kubernetes +##### Docker-in-Docker with TLS disabled in the Docker executor + +Sometimes you might have legitimate reasons to disable TLS. +For example, you have no control over the GitLab Runner configuration +that you are using. + +Assuming that the runner's `config.toml` is similar to: + +```toml +[[runners]] + url = "https://gitlab.com/" + token = TOKEN + executor = "docker" + [runners.docker] + tls_verify = false + image = "docker:19.03.12" + privileged = true + disable_cache = false + volumes = ["/cache"] + [runners.cache] + [runners.cache.s3] + [runners.cache.gcs] +``` + +You can now use `docker` in the job script. Note the inclusion of the +`docker:19.03.12-dind` service: + +```yaml +image: docker:19.03.12 + +variables: + # When using dind service, you must 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. + # + # 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:2375 because of how the + # Kubernetes executor connects services to the job container + # DOCKER_HOST: tcp://localhost:2375 + # + DOCKER_HOST: tcp://docker:2375 + # + # This instructs Docker not to start over TLS. + DOCKER_TLS_CERTDIR: "" + +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 +``` + +#### Use the Kubernetes executor with Docker-in-Docker + +You can use the Kubernetes executor to run jobs in a Docker container. + +##### Docker-in-Docker with TLS enabled in Kubernetes > [Introduced](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/106) in GitLab Runner Helm Chart 0.23.0. @@ -257,7 +297,7 @@ To use Docker-in-Docker with TLS enabled in Kubernetes: 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. + # https://docs.gitlab.com/ee/ci/services/#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 @@ -287,66 +327,34 @@ To use Docker-in-Docker with TLS enabled in Kubernetes: - docker run my-docker-image /script/to/run/tests ``` -#### Docker-in-Docker with TLS disabled - -Sometimes you might have legitimate reasons to disable TLS. -For example, you have no control over the GitLab Runner configuration -that you are using. - -Assuming that the runner's `config.toml` is similar to: - -```toml -[[runners]] - url = "https://gitlab.com/" - token = TOKEN - executor = "docker" - [runners.docker] - tls_verify = false - image = "docker:19.03.12" - privileged = true - disable_cache = false - volumes = ["/cache"] - [runners.cache] - [runners.cache.s3] - [runners.cache.gcs] -``` - -You can now use `docker` in the job script. Note the inclusion of the -`docker:19.03.12-dind` service: - -```yaml -image: docker:19.03.12 - -variables: - # When using dind service, you must 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. - # - # 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:2375 because of how the - # Kubernetes executor connects services to the job container - # DOCKER_HOST: tcp://localhost:2375 - # - DOCKER_HOST: tcp://docker:2375 - # - # This instructs Docker not to start over TLS. - DOCKER_TLS_CERTDIR: "" +#### Limitations of Docker-in-Docker -services: - - docker:19.03.12-dind +Docker-in-Docker is the recommended configuration, but is +not without its own challenges: -before_script: - - docker info +- **The `docker-compose` command**: This command is not available in this configuration by default. + To use `docker-compose` in your job scripts, follow the `docker-compose` + [installation instructions](https://docs.docker.com/compose/install/). +- **Cache**: Each job runs in a new environment. Concurrent jobs work fine, + because every build gets its own instance of Docker engine and they don't conflict with each other. + However, jobs can be slower because there's no caching of layers. +- **Storage drivers**: By default, earlier versions of Docker use the `vfs` storage driver, + which copies the file system for each job. Docker 17.09 and later use `--storage-driver overlay2`, which is + the recommended storage driver. See [Using the OverlayFS driver](#use-the-overlayfs-driver) for details. +- **Root file system**: Because the `docker:19.03.12-dind` container and the runner container don't share their + root file system, you can use the job's working directory as a mount point for + child containers. For example, if you have files you want to share with a + child container, you might create a subdirectory under `/builds/$CI_PROJECT_PATH` + and use it as your mount point. For a more detailed explanation, view [issue + #41227](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41227). -build: - stage: build + ```yaml + variables: + MOUNT_POINT: /builds/$CI_PROJECT_PATH/mnt script: - - docker build -t my-docker-image . - - docker run my-docker-image /script/to/run/tests -``` + - mkdir -p "$MOUNT_POINT" + - docker run -v "$MOUNT_POINT:/mnt" my-docker-image + ``` ### Use Docker socket binding @@ -359,87 +367,50 @@ If you bind the Docker socket and you are 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: +#### Use the Docker executor with Docker socket binding -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`: +To make Docker available in the context of the image, you will need to mount +`/var/run/docker.sock` into the launched containers. To do this with the Docker +executor, you need to add `"/var/run/docker.sock:/var/run/docker.sock"` to the +[Volumes in the `[runners.docker]` section](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#volumes-in-the-runnersdocker-section). - ```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 - `docker:19.03.12` image 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 now 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 job 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 +Your configuration should look something like this: - 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: +```toml +[[runners]] + url = "https://gitlab.com/" + token = RUNNER_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 +``` -- 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: +You can also do this while registering your runner by providing the following options: - ```shell - docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests - ``` +```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 +``` -#### Enable registry mirror for `docker:dind` service +##### Enable registry mirror for `docker:dind` service When the Docker daemon starts inside of the service container, it uses the default configuration. You may want to configure a [registry mirror](https://docs.docker.com/registry/recipes/mirror/) for performance improvements and to ensure you don't reach Docker Hub rate limits. -##### The service in the `.gitlab-ci.yml` file +###### The service in the `.gitlab-ci.yml` file You can append extra CLI flags to the `dind` service to set the registry mirror: @@ -450,7 +421,7 @@ services: command: ["--registry-mirror", "https://registry-mirror.example.com"] # Specify the registry mirror to use ``` -##### The service in the GitLab Runner configuration file +###### The service in the GitLab Runner configuration file > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27173) in GitLab Runner 13.6. @@ -487,7 +458,7 @@ Kubernetes: command = ["--registry-mirror", "https://registry-mirror.example.com"] ``` -##### The Docker executor in the GitLab Runner configuration file +###### The Docker executor in the GitLab Runner configuration file If you are a GitLab Runner administrator, you can use the mirror for every `dind` service. Update the @@ -520,7 +491,7 @@ picked up by the `dind` service. volumes = ["/opt/docker/daemon.json:/etc/docker/daemon.json:ro"] ``` -##### The Kubernetes executor in the GitLab Runner configuration file +###### The Kubernetes executor in the GitLab Runner configuration file > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3223) in GitLab Runner 13.6. @@ -569,6 +540,45 @@ The configuration is picked up by the `dind` service. sub_path = "daemon.json" ``` +##### Limitations of Docker socket binding + +When you use Docker socket binding, you avoid running 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. +- 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. +- 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 + ``` + +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 +``` + ## Authenticate with registry in Docker-in-Docker When you use Docker-in-Docker, the @@ -831,13 +841,13 @@ After you've built a Docker image, you can push it up to the built-in ### `docker: Cannot connect to the Docker daemon at tcp://docker:2375. Is the docker daemon running?` This is a common error when you are using -[Docker-in-Docker](#use-the-docker-executor-with-the-docker-image-docker-in-docker) +[Docker-in-Docker](#use-docker-in-docker) v19.03 or later. This issue occurs because Docker starts on TLS automatically. - If this is your first time setting it up, read - [use the Docker executor with the Docker image](#use-the-docker-executor-with-the-docker-image-docker-in-docker). + [use the Docker executor with the Docker image](#use-docker-in-docker). - If you are upgrading from v18.09 or earlier, read our [upgrade guide](https://about.gitlab.com/blog/2019/07/31/docker-in-docker-with-docker-19-dot-03/). diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index def7703231c..5bd9293924d 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -401,10 +401,10 @@ pulling from Docker Hub fails. Docker daemon tries to use the same credentials f > Introduced in GitLab Runner 12.0. -As an example, let's assume that you want to use the `aws_account_id.dkr.ecr.region.amazonaws.com/private/image:latest` +As an example, let's assume that you want to use the `<aws_account_id>.dkr.ecr.<region>.amazonaws.com/private/image:latest` image. This image is private and requires you to log in into a private container registry. -To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow these steps: +To configure access for `<aws_account_id>.dkr.ecr.<region>.amazonaws.com`, follow these steps: 1. Make sure `docker-credential-ecr-login` is available in the GitLab Runner `$PATH`. 1. Have any of the following [AWS credentials setup](https://github.com/awslabs/amazon-ecr-credential-helper#aws-credentials). @@ -418,7 +418,7 @@ To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow th ```json { "credHelpers": { - "aws_account_id.dkr.ecr.region.amazonaws.com": "ecr-login" + "<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login" } } ``` @@ -438,14 +438,14 @@ To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow th GitLab Runner reads this configuration file and uses the needed helper for this specific repository. -1. You can now use any private image from `aws_account_id.dkr.ecr.region.amazonaws.com` defined in +1. You can now use any private image from `<aws_account_id>.dkr.ecr.<region>.amazonaws.com` defined in `image` and/or `services` in your `.gitlab-ci.yml` file: ```yaml - image: aws_account_id.dkr.ecr.region.amazonaws.com/private/image:latest + image: <aws_account_id>.dkr.ecr.<region>.amazonaws.com/private/image:latest ``` - In the example, GitLab Runner looks at `aws_account_id.dkr.ecr.region.amazonaws.com` for the + In the example, GitLab Runner looks at `<aws_account_id>.dkr.ecr.<region>.amazonaws.com` for the image `private/image:latest`. You can add configuration for as many registries as you want, adding more diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index ea3e81329d3..098ec9bdd02 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -13,7 +13,7 @@ type: howto container images from a Dockerfile, inside a container or Kubernetes cluster. kaniko solves two problems with using the -[Docker-in-Docker build](using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) +[Docker-in-Docker build](using_docker_build.md#use-docker-in-docker) method: - Docker-in-Docker requires [privileged mode](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) diff --git a/doc/ci/environments/deployment_approvals.md b/doc/ci/environments/deployment_approvals.md new file mode 100644 index 00000000000..d60e5704877 --- /dev/null +++ b/doc/ci/environments/deployment_approvals.md @@ -0,0 +1,114 @@ +--- +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 +description: Require approvals prior to deploying to a Protected Environment +--- + +# Deployment approvals **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343864) in GitLab 14.7 with a flag named `deployment_approvals`. Disabled by default. + +WARNING: +This feature is in an alpha stage and subject to change without prior notice. + +It may be useful to require additional approvals before deploying to certain protected environments (for example, production). This pre-deployment approval requirement is useful to accommodate testing, security, or compliance processes that must happen before each deployment. + +When a protected environment requires one or more approvals, all deployments to that environment become blocked and wait for the required approvals before running. + +NOTE: +See the [epic](https://gitlab.com/groups/gitlab-org/-/epics/6832) for planned features. + +## Requirements + +- Basic knowledge of [GitLab Environments and Deployments](index.md). +- Basic knowledge of [Protected Environments](protected_environments.md). + +## Configure deployment approvals for a project + +To configure deployment approvals for a project: + +1. [Create a deployment job](#create-a-deployment-job). +1. [Require approvals for a protected environment](#require-approvals-for-a-protected-environment). + +### Create a deployment job + +Create a deployment job in the `.gitlab-ci.yaml` file of the desired project. The job does **not** need to be manual (`when: manual`). + +Example: + + ```yaml + stages: + - deploy + + production: + stage: deploy + script: + - 'echo "Deploying to ${CI_ENVIRONMENT_NAME}"' + environment: + name: ${CI_JOB_NAME} + ``` + +### Require approvals for a protected environment + +NOTE: +At this time, only API-based configuration is available. UI-based configuration is planned for the near future. See [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/344675). + +Use the [Protected Environments API](../../api/protected_environments.md#protect-repository-environments) to create an environment with `required_approval_count` > 0. After this is set, all jobs deploying to this environment automatically go into a blocked state and wait for approvals before running. + +Example: + +```shell +curl --header 'Content-Type: application/json' --request POST \ + --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}], "required_approval_count": 1}' \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/22034114/protected_environments" +``` + +To protect, update, or unprotect an environment, you must have at least the +[Maintainer role](../../user/permissions.md). + +## Approve or reject a deployment + +NOTE: +This functionality is currently only available through the API. UI is planned for the near future. See [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342180/). + +A blocked deployment is enqueued as soon as it receives the required number of approvals. A single rejection causes the deployment to fail. The creator of a deployment cannot approve it, even if they have permission to deploy. + +Using the [Deployments API](../../api/deployments.md#approve-or-reject-a-blocked-deployment), users who are allowed to deploy to the protected environment can approve or reject a blocked deployment. + +Example: + +```shell +curl --data "status=approved" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/1/approval" +``` + +### How to see blocked deployments + +#### Using the UI + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Deployments > Environments**. +1. Select the environment being deployed to. +1. Look for the `blocked` label. + +#### Using the API + +Use the [Deployments API](../../api/deployments.md) to see deployments. The `status` field indicates if a deployment is blocked. + +## Related features + +For details about other GitLab features aimed at protecting deployments, see [safe deployments](deployment_safety.md). + +<!-- ## 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. + +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. --> diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index ca7b01edf39..55c3c83338d 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -144,6 +144,10 @@ appropriate permissions in the other project. For more information, see [Custom CI/CD configuration path](../pipelines/settings.md#specify-a-custom-cicd-configuration-file). +## Require an approval before deploying + +Before promoting a deployment to a production environment, cross-verifying it with a dedicated testing group is an effective way to ensure safety. For more information, see [Deployment Approvals](deployment_approvals.md). + ## Troubleshooting ### Pipelines jobs fail with `The deployment job is older than the previously succeeded deployment job...` diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 561507cab97..794e4320fc6 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -166,7 +166,7 @@ deploy_prod: The `when: manual` action: -- Exposes a play button for the job in the GitLab UI. +- Exposes a play button for the job in the GitLab UI, with the text **Can be manually deployed to <environment>**. - Means the `deploy_prod` job is only triggered when the play button is clicked. You can find the play button in the pipelines, environments, deployments, and jobs views. @@ -774,10 +774,8 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/* ### Archive Old Deployments > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73628) in GitLab 14.5. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.6. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the feature flag](../../administration/feature_flags.md) named `deployments_archive`. On GitLab.com, this feature is available. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/345027) in GitLab 14.6. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73628) in GitLab 14.0. [Feature flag `deployments_archive`](https://gitlab.com/gitlab-org/gitlab/-/issues/345027) removed. When a new deployment happens in your project, GitLab creates [a special Git-ref to the deployment](#check-out-deployments-locally). diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 57fd72863c1..78db2345de4 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -248,6 +248,10 @@ NOTE: Configuration [with the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/325249) is scheduled for a later release. +## Deployment approvals + +Protected environments can also be used to require manual approvals before deployments. See [Deployment approvals](deployment_approvals.md) for more information. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index 1141583df3f..aed45951239 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -189,6 +189,28 @@ Combined with [protected branches](../../../user/project/protected_branches.md), [`bound_claims_type`](https://www.vaultproject.io/api-docs/auth/jwt#bound_claims_type) configures the interpretation of the `bound_claims` values. If set to `glob`, the values are interpreted as globs, with `*` matching any number of characters. +The claim fields listed in [the table above](#how-it-works) can also be accessed for [Vault's policy path templating](https://learn.hashicorp.com/tutorials/vault/policy-templating?in=vault/policies) purposes by using the accessor name of the JWT auth within Vault. The [mount accessor name](https://learn.hashicorp.com/tutorials/vault/identity#step-1-create-an-entity-with-alias) (`ACCESSOR_NAME` in the example below) can be retrieved by running `vault auth list`. + +Policy template example making use of a named metadata field named `project_path`: + +```plaintext +path "secret/data/{{identity.entity.aliases.ACCESSOR_NAME.metadata.project_path}}/staging/*" { + capabilities = [ "read" ] +} +``` + +Role example to support the templated policy above, mapping the claim field `project_path` as a metadata field through use of [`claim_mappings`](https://www.vaultproject.io/api-docs/auth/jwt#claim_mappings) configuration: + +```plaintext +{ + "role_type": "jwt", + ... + "claim_mappings": { + "project_path": "project_path" + } +} +``` + For the full list of options, see Vault's [Create Role documentation](https://www.vaultproject.io/api/auth/jwt#create-role). WARNING: 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 a9794afaf10..9881c9657bc 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -4,8 +4,6 @@ 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/#assignments author: Vincent Tunru author_gitlab: Vinnl -type: tutorial -date: 2019-02-18 description: 'Confidence checking your entire app every time a new feature is added can quickly become repetitive. Learn how to automate it with GitLab CI/CD.' --- 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 e2e12235eba..be33e62b75c 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -5,8 +5,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w disqus_identifier: 'https://docs.gitlab.com/ee/articles/laravel_with_gitlab_and_envoy/index.html' author: Mehran Rasulian author_gitlab: mehranrasulian -type: tutorial -date: 2017-08-31 --- <!-- vale off --> diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md index 2a002b8fb9f..cdc75fd2bec 100644 --- a/doc/ci/git_submodules.md +++ b/doc/ci/git_submodules.md @@ -64,3 +64,14 @@ If you use the [`CI_JOB_TOKEN`](jobs/ci_job_token.md) to clone a submodule in a pipeline job, the user executing the job must be assigned to a role that has [permission](../user/permissions.md#gitlab-cicd-permissions) to trigger a pipeline in the upstream submodule project. + +## Troubleshooting + +### Can't find the `.gitmodules` file + +The `.gitmodules` file might be hard to find because it is usually a hidden file. +You can check documentation for your specific OS to learn how to find and display +hidden files. + +If there is no `.gitmodules` file, it's possible the submodule settings are in a +[gitconfig](https://www.atlassian.com/git/tutorials/setting-up-a-repository/git-config) file. diff --git a/doc/ci/index.md b/doc/ci/index.md index 5dcb0bcb242..c557e9e6f57 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -81,6 +81,7 @@ GitLab CI/CD features, grouped by DevOps stage, include: | **Configure** | | | [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. | | [ChatOps](chatops/index.md) | Trigger CI jobs from chat, with results sent back to the channel. | +| [Connect to cloud services](cloud_services/index.md) | Connect to cloud providers using OpenID Connect (OIDC) to retrieve temporary credentials to access services or secrets. | |-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| | **Verify** | | | [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 5724c56b096..f49fdd6c39f 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -32,10 +32,18 @@ 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: -Interactive web terminals are not yet supported by -[`gitlab-runner` Helm chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-runner/index.html). -Support is tracked [in this issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/79). +### Partial support for Helm chart + +Interactive web terminals are partially supported in `gitlab-runner` Helm chart. +They are enabled when: + +- The number of replica is one +- You use the `loadBalancer` service + +Support for fixing these limitations is tracked in the following issues: + +- [Support of more than one replica](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/323) +- [Support of more service types](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/324) ## Debugging a running job diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 532a0dffbce..1906d9cdb6c 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -24,7 +24,10 @@ You can use a GitLab CI/CD job token to authenticate with specific API endpoints - [Terraform plan](../../user/infrastructure/index.md). The token has the same permissions to access the API as the user that executes the -job. Therefore, this user must be assigned to [a role that has the required privileges](../../user/permissions.md#gitlab-cicd-permissions). +The token has the same permissions to access the API as the user that caused the +job to run. A user can cause a job to run by pushing a commit, triggering a manual job, +being the owner of a scheduled pipeline, and so on. Therefore, this user must be assigned to +[a role that has the required privileges](../../user/permissions.md#gitlab-cicd-permissions). The token is valid only while the pipeline job runs. After the job finishes, you can't use the token anymore. diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index 596df34b5c2..a2406a68bb2 100644 --- a/doc/ci/jobs/job_control.md +++ b/doc/ci/jobs/job_control.md @@ -404,10 +404,7 @@ build: If you change multiple files, but only one file ends in `.md`, the `build` job is still skipped. The job does not run for any of the files. -Read more about how to use `only:changes` and `except:changes`: - -- [New branches or tags *without* pipelines for merge requests](#use-onlychanges-without-pipelines-for-merge-requests). -- [Scheduled pipelines](#use-onlychanges-with-scheduled-pipelines). +With some configurations that use `changes`, [jobs or pipelines might run unexpectedly](#jobs-or-pipelines-run-unexpectedly-when-using-changes) #### Use `only:changes` with pipelines for merge requests @@ -459,22 +456,6 @@ it doesn't matter that an earlier pipeline failed because of a change that has n When you use this configuration, ensure that the most recent pipeline properly corrects any failures from previous pipelines. -#### Use `only:changes` without pipelines for merge requests - -Without [pipelines for merge requests](../pipelines/merge_request_pipelines.md), pipelines -run on branches or tags that don't have an explicit association with a merge request. -In this case, a previous SHA is used to calculate the diff, which is equivalent to `git diff HEAD~`. -This can result in some unexpected behavior, including: - -- When pushing a new branch or a new tag to GitLab, the policy always evaluates to true. -- When pushing a new commit, the changed files are calculated by using the previous commit - as the base SHA. - -#### Use `only:changes` with scheduled pipelines - -`only:changes` always evaluates as true in [Scheduled pipelines](../pipelines/schedules.md). -All files are considered to have changed when a scheduled pipeline runs. - ### Combine multiple keywords with `only` or `except` If you use multiple keywords with `only` or `except`, the keywords are evaluated @@ -777,7 +758,7 @@ job1: - echo rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" - - if: $CI_PIPELINE_SOURCE == "scheduled" + - if: $CI_PIPELINE_SOURCE == "schedule" - if: $CI_PIPELINE_SOURCE == "push" when: never ``` @@ -943,3 +924,23 @@ For example: - `($VARIABLE1 =~ /^content.*/ || $VARIABLE2) && ($VARIABLE3 =~ /thing$/ || $VARIABLE4)` - `($VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/) && $VARIABLE3` - `$CI_COMMIT_BRANCH == "my-branch" || (($VARIABLE1 == "thing" || $VARIABLE2 == "thing") && $VARIABLE3)` + +## Troubleshooting + +### Jobs or pipelines run unexpectedly when using `changes:` + +You might have jobs or pipelines that run unexpectedly when using [`rules: changes`](../yaml/index.md#ruleschanges) +or [`only: changes`](../yaml/index.md#onlychanges--exceptchanges) without +[pipelines for merge requests](../pipelines/merge_request_pipelines.md). + +Pipelines on branches or tags that don't have an explicit association with a merge request +use a previous SHA to calculate the diff. This calculation is equivalent to `git diff HEAD~` +and can cause unexpected behavior, including: + +- The `changes` rule always evaluates to true when pushing a new branch or a new tag to GitLab. +- When pushing a new commit, the changed files are calculated by using the previous commit + as the base SHA. + +Additionally, rules with `changes` always evaluate as true in [scheduled pipelines](../pipelines/schedules.md). +All files are considered to have changed when a scheduled pipeline runs, so jobs +might always be added to scheduled pipelines that use `changes`. diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 5be016aff40..d72cb14681d 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -83,7 +83,41 @@ where: - Configuration imported with [`include`](../yaml/index.md#include) is copied into the view. - Jobs that use [`extends`](../yaml/index.md#extends) display with the [extended configuration merged into the job](../yaml/yaml_optimization.md#merge-details). -- YAML anchors are [replaced with the linked configuration](../yaml/yaml_optimization.md#anchors). +- [YAML anchors](../yaml/yaml_optimization.md#anchors) are replaced with the linked configuration. +- [YAML `!reference` tags](../yaml/yaml_optimization.md#reference-tags) are also replaced + with the linked configuration. + +Using `!refence` tags can cause nested configuration that display with +multiple hyphens (`-`) in the expanded view. This behavior is expected, and the extra +hyphens do not affect the job's execution. For example, this configuration and +fully expanded version are both valid: + +- `.gitlab-ci.yml` file: + + ```yaml + .python-req: + script: + - pip install pyflakes + + lint-python: + image: python:latest + script: + - !reference [.python-req, script] + - pyflakes python/ + ``` + +- Expanded configuration in **View merged YAML** tab: + + ```yaml + ".python-req": + script: + - pip install pyflakes + lint-python: + script: + - - pip install pyflakes # <- The extra hyphens do not affect the job's execution. + - pyflakes python/ + image: python:latest + ``` ## Commit changes to CI configuration @@ -97,3 +131,20 @@ If you enter a new branch name, the **Start a new merge request with these chang checkbox appears. Select it to start a new merge request after you commit the changes.  + +## Troubleshooting + +### `Configuration validation currently not available` message + +This message is due to a problem with the syntax validation in the pipeline editor. +If GitLab is unable to communicate with the service that validates the syntax, the +information in these sections may not display properly: + +- The syntax status on the **Edit** tab (valid or invalid). +- The **Visualize** tab. +- The **Lint** tab. +- The **View merged YAML** tab. + +You can still work on your CI/CD configuration and commit the changes you made without +any issues. As soon as the service becomes available again, the syntax validation +should display immediately. diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md new file mode 100644 index 00000000000..e0fb5b45986 --- /dev/null +++ b/doc/ci/pipelines/cicd_minutes.md @@ -0,0 +1,221 @@ +--- +stage: Verify +group: Pipeline Execution +info: To determine 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 +--- + +# CI/CD minutes quota **(PREMIUM)** + +[Shared runners](../runners/runners_scope.md#shared-runners) are shared with every project and group in a GitLab instance. +When jobs run on shared runners, CI/CD minutes are used. + +You can set limits on the number of CI/CD minutes that are used each month. + +- On GitLab.com, the quota of CI/CD minutes is set for each [namespace](../../user/group/index.md#namespaces), + and is determined by [your license tier](https://about.gitlab.com/pricing/). +- On self-managed GitLab instances, the quota of CI/CD minutes for each namespace is set by administrators. + +In addition to the monthly quota, you can add more CI/CD minutes when needed. + +- On GitLab.com, you can [purchase additional CI/CD minutes](#purchase-additional-cicd-minutes). +- On self-managed GitLab instances, administrators can [assign more CI/CD minutes](#set-the-quota-of-cicd-minutes-for-a-specific-namespace). + +[Specific runners](../runners/runners_scope.md#specific-runners) +are not subject to a quota of CI/CD minutes. + +## Set the quota of CI/CD minutes for all namespaces + +> [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. + +By default, GitLab instances do not have a quota of CI/CD minutes. +The default value for the quota is `0`, which grants unlimited CI/CD minutes. +However, you can change this default value. + +Prerequisite: + +- You must be a GitLab administrator. + +To change the default quota that applies to all namespaces: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Continuous Integration and Deployment**. +1. In the **Quota of CI/CD minutes** box, enter the maximum number of CI/CD minutes. +1. Select **Save changes**. + +If a quota is already defined for a specific namespace, this value does not change that quota. + +## Set the quota of CI/CD minutes for a specific namespace + +> [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. + +You can override the global value and set a quota of CI/CD minutes +for a specific namespace. + +Prerequisite: + +- You must be a GitLab administrator. + +To set a quota of CI/CD minutes for a namespace: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Groups**. +1. For the group you want to update, select **Edit**. +1. In the **Quota of CI/CD minutes** box, enter the maximum number of CI/CD minutes. +1. Select **Save changes**. + +You can also use the [update group API](../../api/groups.md#update-group) or the +[update user API](../../api/users.md#user-modification) instead. + +NOTE: +You can set a quota of CI/CD minutes for only top-level groups or user namespaces. +If you set a quota for a subgroup, it is not used. + +## View CI/CD minutes used by a group + +You can view the number of CI/CD minutes being used by a group. + +Prerequisite: + +- You must have the Owner role for the group. + +To view CI/CD minutes being used for your group: + +1. On the top bar, select **Menu > Groups** and find your group. The group must not be a subgroup. +1. On the left sidebar, select **Settings > Usage Quotas**. +1. Select the **Pipelines** tab. + + + +## View CI/CD minutes used by a personal namespace + +You can view the number of CI/CD minutes being used by a personal namespace: + +1. On the top bar, in the top right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Usage Quotas**. + +## Purchase additional CI/CD minutes **(FREE SAAS)** + +If you're using GitLab SaaS, you can purchase additional packs of CI/CD minutes. +These additional CI/CD minutes: + +- Are used only after the monthly quota included in your subscription runs out. +- Are carried over to the next month, if any remain at the end of the month. +- Don't expire. + +If you use more CI/CD minutes than your monthly quota, when you purchase more, +those CI/CD minutes are deducted from your quota. For example, with a GitLab SaaS +Premium license: + +- You have `10,000` monthly minutes. +- You purchase an additional `5,000` minutes. +- Your total limit is `15,000` minutes. + +If you use `13,000` minutes during the month, the next month your additional minutes become +`2,000`. If you use `9,000` minutes during the month, your additional minutes remain the same. + +You can find pricing for additional CI/CD minutes on the +[GitLab Pricing page](https://about.gitlab.com/pricing/). + +### Purchase CI/CD minutes for a group **(FREE SAAS)** + +You can purchase additional CI/CD minutes for your group. +You cannot transfer purchased CI/CD minutes from one group to another, +so be sure to select the correct group. + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Usage Quotas**. +1. Select **Buy additional minutes**. +1. Complete the details of the transaction. + +After your payment is processed, the additional CI/CD minutes are added to your group +namespace. + +### Purchase CI/CD minutes for a personal namespace **(FREE SAAS)** + +To purchase additional minutes for your personal namespace: + +1. On the top bar, in the top right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Usage Quotas**. +1. Select **Buy additional minutes**. GitLab redirects you to the Customers Portal. +1. Locate the subscription card that's linked to your personal namespace on GitLab SaaS, select **Buy more CI minutes**, + and complete the details of the transaction. + +After your payment is processed, the additional CI/CD minutes are added to your personal +namespace. + +## How CI/CD minutes are calculated + +CI/CD minutes are calculated based on: + +- The duration the job runs. +- The visibility of the projects where the job runs. + +GitLab uses this formula to calculate CI/CD minutes consumed by a job: + +```plaintext +Job duration * Cost factor +``` + +- **Job duration**: The time, in seconds, that a job took to run on a shared runner. + It does not include time spent in `created` or `pending` status. +- **Cost factor**: A number based on project visibility. + +The number is transformed into minutes and added to the overall quota in the job's top-level namespace. + +For example: + +- A user, `alice`, runs a pipeline under the `gitlab-org` namespace. +- The CI/CD minutes consumed by each job in the pipeline are added to the + overall consumption for the `gitlab-org` namespace, not the `alice` namespace. +- If a pipeline runs for one of the personal projects for `alice`, the CI/CD minutes + are added to the overall consumption for the `alice` namespace. + +### Cost factor + +The cost factor for a job running on a shared runner is: + +- `0.008` for public projects on GitLab SaaS, if [created 2021-07-17 or later](https://gitlab.com/gitlab-org/gitlab/-/issues/332708). + (For every 125 minutes of job time, you accrue 1 CD/CD minute.) +- `0.008` for projects members of GitLab [Open Source program](../../subscriptions/index.md#gitlab-for-open-source). + (For every 125 minutes of job time, you accrue 1 CD/CD minute.) +- `0` for public projects on GitLab self-managed instances, and for GitLab SaaS public projects created before 2021-07-17. +- `1` for internal and private projects. + +### Additional costs on GitLab SaaS + +On GitLab SaaS, shared runners can have different cost factors depending on the cost involved +in executing the runner. For example, a high spec shared runner could be set to have a cost factor of `2`. +Conversely, a shared runner that executes jobs for public projects could have a low cost factor, like `0.008`. + +### Monthly reset of CI/CD minutes + +On the first day of each calendar month, the accumulated usage of CI/CD minutes is reset to `0` +for all namespaces that use shared runners. + +Usage data for the previous month is kept to show historical view of the consumption over time. + +## What happens when you exceed the quota + +When the quota of CI/CD minutes is used for the current month, GitLab stops +processing new jobs. + +- Any non-running job that should be picked by shared runners is automatically dropped. +- Any job being retried is automatically dropped. +- Any running job can be dropped at any point if the overall namespace usage goes over-quota + by a grace period. + +The grace period for running jobs is `1,000` CI/CD minutes. + +Jobs on specific runners are not affected by the quota of CI/CD minutes. + +### GitLab SaaS usage notifications + +On GitLab SaaS an email notification is sent to the namespace owners when: + +- The available CI/CD minutes are below 30% of the quota. +- The available CI/CD minutes are below 5% of the quota. +- All CI/CD minutes have been used. diff --git a/doc/user/admin_area/settings/img/group_pipelines_quota.png b/doc/ci/pipelines/img/group_cicd_minutes_quota.png Binary files differindex 318527426bd..318527426bd 100644 --- a/doc/user/admin_area/settings/img/group_pipelines_quota.png +++ b/doc/ci/pipelines/img/group_cicd_minutes_quota.png diff --git a/doc/ci/pipelines/img/pipeline-fork_v13_7.png b/doc/ci/pipelines/img/pipeline_fork_v13_7.png Binary files differindex eb44290aa66..eb44290aa66 100644 --- a/doc/ci/pipelines/img/pipeline-fork_v13_7.png +++ b/doc/ci/pipelines/img/pipeline_fork_v13_7.png diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 24e518b1f69..b873b2ae30f 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -50,10 +50,6 @@ Pipelines can be configured in many different ways: followed by the next stage. - [Directed Acyclic Graph Pipeline (DAG) pipelines](../directed_acyclic_graph/index.md) are based on relationships between jobs and can run more quickly than basic pipelines. -- [Multi-project pipelines](multi_project_pipelines.md) combine pipelines for different projects together. -- [Parent-Child pipelines](parent_child_pipelines.md) break down complex pipelines - into one parent pipeline that can trigger multiple child sub-pipelines, which all - run in the same project and with the same SHA. This pipeline architecture is commonly used for mono-repos. - [Pipelines for Merge Requests](../pipelines/merge_request_pipelines.md) run for merge requests only (rather than for every commit). - [Pipelines for Merged Results](../pipelines/pipelines_for_merged_results.md) @@ -61,6 +57,44 @@ Pipelines can be configured in many different ways: already been merged into the target branch. - [Merge Trains](../pipelines/merge_trains.md) use pipelines for merged results to queue merges one after the other. +- [Parent-Child pipelines](parent_child_pipelines.md) break down complex pipelines + into one parent pipeline that can trigger multiple child sub-pipelines, which all + run in the same project and with the same SHA. This pipeline architecture is commonly used for mono-repos. +- [Multi-project pipelines](multi_project_pipelines.md) combine pipelines for different projects together. + +### How parent-child pipelines compare to multi-project pipelines + +Parent-child pipelines and multi-project pipelines can sometimes be used for similar +purposes, but there are some key differences: + +Parent-child pipelines: + +- Run under the same project, ref, and commit SHA as the parent pipeline. +- Affect the overall status of the ref the pipeline runs against. For example, + if a pipeline fails for the main branch, it's common to say that "main is broken". + The status of child pipelines don't directly affect the status of the ref, unless the child + pipeline is triggered with [`strategy:depend`](../yaml/index.md#triggerstrategy). +- Are automatically canceled if the pipeline is configured with [`interruptible`](../yaml/index.md#interruptible) + when a new pipeline is created for the same ref. +- Display only the parent pipelines in the pipeline index page. Child pipelines are + visible when visiting their parent pipeline's page. +- Are limited to 2 levels of nesting. A parent pipeline can trigger multiple child pipelines, + and those child pipeline can trigger multiple child pipelines (`A -> B -> C`). + +Multi-project pipelines: + +- Are triggered from another pipeline, but the upstream (triggering) pipeline does + not have much control over the downstream (triggered) pipeline. However, it can + choose the ref of the downstream pipeline, and pass CI/CD variables to it. +- Affect the overall status of the ref of the project it runs in, but does not + affect the status of the triggering pipeline's ref, unless it was triggered with + [`strategy:depend`](../yaml/index.md#triggerstrategy). +- Are not automatically canceled in the downstream project when using [`interruptible`](../yaml/index.md#interruptible) + if a new pipeline runs for the same ref in the upstream pipeline. They can be + automatically canceled if a new pipeline is triggered for the same ref on the downstream project. +- Multi-project pipelines are standalone pipelines because they are normal pipelines + that happened to be triggered by an external project. They are all visible on the pipeline index page. +- Are independent, so there are no nesting limits. ## Configure a pipeline @@ -257,14 +291,33 @@ 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.** -### Pipeline quotas +### Pipeline security on protected branches + +A strict security model is enforced when pipelines are executed on +[protected branches](../../user/project/protected_branches.md). + +The following actions are allowed on protected branches only if the user is +[allowed to merge or push](../../user/project/protected_branches.md) +on that specific branch: + +- Run manual pipelines (using the [Web UI](#run-a-pipeline-manually) or [pipelines API](#pipelines-api)). +- Run scheduled pipelines. +- Run pipelines using triggers. +- Run on-demand DAST scan. +- Trigger manual actions on existing pipelines. +- Retry or cancel existing jobs (using the Web UI or pipelines API). -Each user has a personal pipeline quota that tracks the usage of shared runners in all personal projects. -Each group has a [usage quota](../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes) that tracks the usage of shared runners for all projects created within the group. +**Variables** marked as **protected** are accessible only to jobs that +run on protected branches, preventing untrusted users getting unintended access to +sensitive information like deployment credentials and tokens. -When a pipeline is triggered, regardless of who triggered it, the pipeline quota for the project owner's [namespace](../../user/group/index.md#namespaces) is used. In this case, the namespace can be the user or group that owns the project. +**Runners** marked as **protected** can run jobs only on protected +branches, preventing untrusted code from executing on the protected runner and +preserving deployment keys and other credentials from being unintentionally +accessed. In order to ensure that jobs intended to be executed on protected +runners do not use regular runners, they must be tagged accordingly. -#### How pipeline duration is calculated +### How pipeline duration is calculated Total running time for a given pipeline excludes retries and pending (queued) time. @@ -301,44 +354,6 @@ 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 -[protected branches](../../user/project/protected_branches.md). - -The following actions are allowed on protected branches only if the user is -[allowed to merge or push](../../user/project/protected_branches.md) -on that specific branch: - -- Run manual pipelines (using the [Web UI](#run-a-pipeline-manually) or [pipelines API](#pipelines-api)). -- Run scheduled pipelines. -- Run pipelines using triggers. -- Run on-demand DAST scan. -- Trigger manual actions on existing pipelines. -- Retry or cancel existing jobs (using the Web UI or pipelines API). - -**Variables** marked as **protected** are accessible only to jobs that -run on protected branches, preventing untrusted users getting unintended access to -sensitive information like deployment credentials and tokens. - -**Runners** marked as **protected** can run jobs only on protected -branches, preventing untrusted code from executing on the protected runner and -preserving deployment keys and other credentials from being unintentionally -accessed. In order to ensure that jobs intended to be executed on protected -runners do not use regular runners, they must be tagged accordingly. - ## Visualize pipelines Pipelines can be complex structures with many sequential and parallel jobs. diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index e47b6dddc5f..1710c57b36b 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -405,3 +405,27 @@ generated. Check the job log for these messages. If you find no helpful messages, retry the failed job after activating [CI/CD debug logging](../variables/index.md#debug-logging). This logging should provide information to help you investigate further. + +### Error message `Missing /usr/bin/gitlab-runner-helper. Uploading artifacts is disabled.` + +There is a [known issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3068) where setting a CI/CD variable named `DEBUG` can cause artifact uploads to fail. + +To work around this, either use a different variable name or set it inline with `script`: + +```yaml +# This job might fail due to issue gitlab-org/gitlab-runner#3068 +failing_test_job: + variables: + DEBUG: true + script: bin/mycommand + artifacts: + paths: + - bin/results + +# This job does not define a CI/CD variable named `DEBUG` and is not affected by the issue +successful_test_job: + script: DEBUG=true bin/mycommand + artifacts: + paths: + - bin/results +``` diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index 85e5b62b0c4..4d7ebc09e6f 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -2,214 +2,197 @@ stage: Verify group: Pipeline Execution info: To determine 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 --- -# Pipelines for merge requests **(FREE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/15310) in GitLab 11.6. -In a [basic configuration](pipeline_architectures.md#basic-pipelines), GitLab runs a pipeline each time -changes are pushed to a branch. +# Pipelines for merge requests **(FREE)** -If you want the pipeline to run jobs **only** on commits associated with a merge request, -you can use *pipelines for merge requests*. +You can configure your [pipeline](index.md) to run every time you commit changes to a branch. +This type of pipeline is called a *branch pipeline*. -These pipelines are labeled as `detached` in the UI, and they do not have access to [protected variables](../variables/index.md#protect-a-cicd-variable). -Otherwise, these pipelines are the same as other pipelines. +Alternatively, you can configure your pipeline to run every time you make changes to the +source branch for a merge request. This type of pipeline is called a *pipeline for merge requests*. -Pipelines for merge requests can run when you: +Branch pipelines: -- Create a new merge request. -- Commit changes to the source branch for the merge request. -- Select the **Run pipeline** button from the **Pipelines** tab in the merge request. +- Run when you push a new commit to a branch. +- Are the default type of pipeline. +- Have access to [some predefined variables](../variables/predefined_variables.md). +- Have access to [protected variables](../variables/index.md#protect-a-cicd-variable). -If you use this feature with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md), -pipelines for merge requests take precedence over other pipelines. +Pipelines for merge requests: -## Prerequisites +- Run when you: + - Create a new merge request. + - Push a new commit to the source branch for a merge request. + - Select **Run pipeline** from the **Pipelines** tab in a merge request. This option + is only available when pipelines for merge requests are configured for the pipeline. +- Do not run by default. The jobs in the CI/CD configuration file [must be configured](#prerequisites) + to run in pipelines for merge request. +- Have access to [more predefined variables](#available-predefined-variables). +- Do not have access to [protected variables](../variables/index.md#protect-a-cicd-variable). -To enable pipelines for merge requests: +Both of these types of pipelines can appear on the **Pipelines** tab of a merge request. -- Your repository must be a GitLab repository, not an - [external repository](../ci_cd_for_external_repos/index.md). -- You must have the Developer [role](../../user/permissions.md) - to run a pipeline for merge requests. +## Types of pipelines for merge requests -## Configure pipelines for merge requests +The three types of pipelines for merge requests are: -To configure pipelines for merge requests, you must configure your [CI/CD configuration file](../yaml/index.md). -To do this, you can use [`rules`](#use-rules-to-run-pipelines-for-merge-requests) or [`only/except`](#use-only-or-except-to-run-pipelines-for-merge-requests). +- Pipelines for merge requests, which run on the changes in the merge request's + source branch. These pipelines display a `detached` label to indicate that the + pipeline ran only on the contents of the source branch, ignoring the target branch. +- [Pipelines for merged results](pipelines_for_merged_results.md), which run on + the result of combining the source branch's changes with the target branch. +- [Merge trains](merge_trains.md), which run when merging multiple merge requests + at the same time. The changes from each merge request are combined into the + target branch with the changes in the earlier enqueued merge requests, to ensure + they all work together. -### Use `rules` to run pipelines for merge requests +## Prerequisites -GitLab recommends that you use the `rules` keyword, which is available in -[`workflow:rules` templates](../yaml/workflow.md#workflowrules-templates). +To use pipelines for merge requests: -### Use `only` or `except` to run pipelines for merge requests +- Your project's [CI/CD configuration file](../yaml/index.md) must be configured with + jobs that run in pipelines for merge requests. To do this, you can use: + - [`rules`](#use-rules-to-add-jobs). + - [`only/except`](#use-only-to-add-jobs). +- You must have at least the Developer [role](../../user/permissions.md) in the + source project to run a pipeline for merge requests. +- Your repository must be a GitLab repository, not an [external repository](../ci_cd_for_external_repos/index.md). -You can use the `only/except` keywords. However, with this method, you must specify `only: - merge_requests` for each job. +## Use `rules` to add jobs -In the following 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 don't run on merge requests. +You can use the [`rules`](../yaml/index.md#rules) keyword to configure jobs to run in +pipelines for merge requests. For example: ```yaml -build: - stage: build - script: ./build - only: - - main - -test: - stage: test - script: ./test - only: - - merge_requests - -deploy: - stage: deploy - script: ./deploy - only: - - main +job1: + script: + - echo "This job runs in pipelines for merge requests" + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' ``` -#### Exclude specific jobs - -When you use `only: [merge_requests]`, only jobs with -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. For example, you might have a pipeline with jobs `A`, `B`, and `C`, and you want: - -- All pipelines to always run `A` and `B`. -- `C` to run only for merge requests. - -To achieve this outcome, configure your `.gitlab-ci.yml` file as follows: +You can also use the [`workflow: rules`](../yaml/index.md#workflowrules) keyword +to configure the entire pipeline to run in pipelines for merge requests. For example: ```yaml -.only-default: &only-default - only: - - main - - merge_requests - - tags +workflow: + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' -A: - <<: *only-default +job1: script: - - ... + - echo "This job runs in pipelines for merge requests" -B: - <<: *only-default +job2: script: - - ... - -C: - script: - - ... - only: - - merge_requests + - echo "This job also runs in pipelines for merge requests" ``` -- `A` and `B` always run, because they get the `only` rule to execute in all cases. -- `C` only runs for merge requests. It doesn't run for any pipeline - except a merge request pipeline. - -In this example, you don't have to add the `only` rule to all of your jobs to make -them always run. You can use this format to set up a Review App, which helps to -save resources. +## Use `only` to add jobs -#### Exclude specific branches - -Branch refs use this format: `refs/heads/my-feature-branch`. -Merge request refs use this format: `refs/merge-requests/:iid/head`. - -Because of this difference, the following configuration does not work as expected: - -```yaml -# Does not exclude a branch named "docs-my-fix"! -test: - only: [merge_requests] - except: [/^docs-/] -``` - -Instead, use the -[`$CI_COMMIT_REF_NAME` predefined environment -variable](../variables/predefined_variables.md) in -combination with -[`only:variables`](../yaml/index.md#onlyvariables--exceptvariables) to -accomplish this behavior: +You can use the [`only`](../yaml/index.md#onlyrefs--exceptrefs) keyword with `merge_requests` +to configure jobs to run in pipelines for merge requests. ```yaml -test: - only: [merge_requests] - except: - variables: - - $CI_COMMIT_REF_NAME =~ /^docs-/ +job1: + script: + - echo "This job runs in pipelines for merge requests" + only: + - merge_requests ``` -## Run pipelines in the parent project for merge requests from a forked project **(PREMIUM)** +## Use with forked projects > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217451) in GitLab 13.3. > - [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. -By default, external contributors who work in forks can't create pipelines in the -parent project. When a merge request that comes from a fork triggers a pipeline: +External contributors who work in forks can't create pipelines in the parent project. -- The pipeline is created and runs in the fork (source) project, not the parent (target) project. -- The pipeline uses the fork project's CI/CD configuration and resources. +A merge request from a fork that is submitted to the parent project triggers a +pipeline that: -If a pipeline runs in a fork, a **fork** badge appears for the pipeline in the merge request. +- Is created and runs in the fork (source) project, not the parent (target) project. +- Uses the fork project's CI/CD configuration, resources, and project CI/CD variables. - +Pipelines for forks display with the **fork** badge in the parent project: -Sometimes parent project members want the pipeline to run in the parent -project. They may want to ensure that the post-merge pipeline passes in the parent project. -For example, a fork project could try to use a corrupted runner that doesn't execute -test scripts properly, but reports a passed pipeline. Reviewers in the parent project -could mistakenly trust the merge request because it passed a faked pipeline. + -Parent project members with at least the [Developer role](../../user/permissions.md) -can create pipelines in the parent project for merge requests -from a forked project. In the merge request, go to the **Pipelines** tab and select -**Run pipeline**. +### Run pipelines in the parent project **(PREMIUM)** + +Project members in the parent project can choose to run a pipeline for merge requests +for a merge request submitted from a fork project. This pipeline: + +- Is created and runs in the parent (target) project, not the fork (source) project. +- Uses the CI/CD configuration present in the fork project's branch +- Uses the parent project's CI/CD configuration, resources, and project CI/CD variables. +- Uses the permissions of the parent project member that triggers the pipeline. + +Run pipelines in fork project MRs to ensure that the post-merge pipeline passes in +the parent project. Additionally, if you do not trust the fork project's runner, +running the pipeline in the parent project uses the parent project's trusted runners. WARNING: Fork merge requests can contain malicious code that tries to steal secrets in the -parent project when the pipeline runs, even before merge. As a reviewer, you must carefully +parent project when the pipeline runs, even before merge. As a reviewer, carefully check the changes in the merge request before triggering the pipeline. GitLab shows a warning that you must accept before you can trigger the pipeline. -## Predefined variables available for pipelines for merge requests +Parent project members with at least the [Developer role](../../user/permissions.md) +can create pipelines in the parent project for merge requests from a forked project: -When you use pipelines for merge requests, [additional predefined variables](../variables/predefined_variables.md#predefined-variables-for-merge-request-pipelines) are available to the CI/CD jobs. -These variables contain information from the associated merge request, so that you can -integrate your job with the [GitLab Merge Request API](../../api/merge_requests.md). +1. In the merge request, go to the **Pipelines** tab. +1. Select **Run pipeline**. You must accept the warning, or the pipeline does not run. -## Troubleshooting +## Available predefined variables -### Two pipelines created when pushing to a merge request +When you use pipelines for merge requests, you can use: + +- All the same [predefined variables](../variables/predefined_variables.md) that are + available in branch pipelines. +- [Additional predefined variables](../variables/predefined_variables.md#predefined-variables-for-merge-request-pipelines) + available only to jobs in pipelines for merge requests. These variables contain + information from the associated merge request, which can be when calling the + [GitLab Merge Request API endpoint](../../api/merge_requests.md) from a job. + +## Troubleshooting -If you are experiencing duplicated pipelines when using `rules`, take a look at -the [important differences between `rules` and `only`/`except`](../jobs/job_control.md#avoid-duplicate-pipelines), -which helps you get your starting configuration correct. +### Two pipelines when pushing to a branch -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`). +If you get duplicate pipelines in merge requests, your pipeline might be configured +to run for both branches and merge requests at the same time. Adjust your pipeline +configuration to [avoid duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines). In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201845), -you can add `workflow:rules` to [switch from branch pipelines to merge request pipelines](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines). +you can add `workflow:rules` to [switch from branch pipelines to pipelines for merge requests](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines). After a merge request is open on the branch, the pipeline switches to a merge request pipeline. -### Two pipelines created when pushing an invalid CI configuration file +### Two pipelines when pushing an invalid CI/CD configuration file + +If you push an invalid CI/CD configuration to a merge request's branch, two failed +pipelines appear in the pipelines tab. One pipeline is a failed branch pipeline, +the other is a failed pipeline for merge requests. + +When the configuration syntax is fixed, no further failed pipelines should appear. +To find and fix the configuration problem, you can use: + +- The [pipeline editor](../pipeline_editor/index.md). +- The [CI lint tool](../lint.md). + +### The merge request's pipeline is marked as failed but the latest pipeline succeeded + +It's possible to have both branch pipelines and pipelines for merge requests in the +**Pipelines** tab of a single merge request. This might be [by configuration](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines), +or [by accident](#two-pipelines-when-pushing-to-a-branch). -Pushing to a branch with an invalid CI configuration file can trigger -the creation of two types of failed pipelines. One pipeline is a failed merge request -pipeline, and the other is a failed branch pipeline, but both are caused by the same -invalid configuration. +If both types of pipelines are in one merge request, the merge request's pipeline +is not considered successful if: -## Related topics +- The branch pipeline succeeds. +- The pipeline for merge request fails. -- [Pipelines for merged results](pipelines_for_merged_results.md). -- [Merge trains](merge_trains.md). +When using the [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md) +feature and both pipelines types are present, the pipelines for merge requests are checked, +not the branch pipelines. diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index 593cdb68b3f..d47cbf5f47c 100644 --- a/doc/ci/pipelines/merge_trains.md +++ b/doc/ci/pipelines/merge_trains.md @@ -2,8 +2,6 @@ stage: Verify group: Pipeline Execution info: To determine 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 --- # Merge trains **(PREMIUM)** @@ -11,10 +9,6 @@ last_update: 2019-07-03 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9186) in GitLab 12.0. > - [Squash and merge](../../user/project/merge_requests/squash_and_merge.md) support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13001) in GitLab 12.6. -INFO: -Get merge trains and more in GitLab Ultimate. -[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-ci-cd-external-docs). - For more information about why you might want to use merge trains, read [How merge trains keep your master green](https://about.gitlab.com/blog/2020/01/30/all-aboard-merge-trains/). When [pipelines for merged results](pipelines_for_merged_results.md) are @@ -84,7 +78,7 @@ To enable merge trains: To enable merge trains for your project: 1. If you are on a self-managed GitLab instance, ensure the [feature flag](#merge-trains-feature-flag) is set correctly. -1. [Configure your CI/CD configuration file](merge_request_pipelines.md#configure-pipelines-for-merge-requests) +1. [Configure your CI/CD configuration file](merge_request_pipelines.md#prerequisites) so that the pipeline or individual jobs run for merge requests. 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > General**. diff --git a/doc/ci/pipelines/pipelines_for_merged_results.md b/doc/ci/pipelines/pipelines_for_merged_results.md index 718519faf48..91a49a48882 100644 --- a/doc/ci/pipelines/pipelines_for_merged_results.md +++ b/doc/ci/pipelines/pipelines_for_merged_results.md @@ -2,18 +2,12 @@ stage: Verify group: Pipeline Execution info: To determine 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 --- # Pipelines for merged results **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7380) in GitLab 11.10. -INFO: -Get these pipelines and more in GitLab Ultimate. -[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-ci-cd-external-docs). - When you submit a merge request, you are requesting to merge changes from a source branch into a target branch. By default, the CI pipeline runs jobs against the source branch. @@ -61,7 +55,7 @@ To enable pipelines for merge results: To enable pipelines for merged results for your project: -1. [Configure your CI/CD configuration file](merge_request_pipelines.md#configure-pipelines-for-merge-requests) +1. [Configure your CI/CD configuration file](merge_request_pipelines.md#prerequisites) so that the pipeline or individual jobs run for merge requests. 1. Visit your project's **Settings > General** and expand **Merge requests**. 1. Check **Enable merged results pipelines**. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index cf470836e32..85824dfb7c7 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -21,11 +21,7 @@ For public and internal projects, you can change who can see your: - Pipelines - Job output logs - Job artifacts -- [Pipeline security dashboard](../../user/application_security/security_dashboard/index.md#pipeline-security) - -However: - -- Job output logs and artifacts are [never visible for Guest users and non-project members](https://gitlab.com/gitlab-org/gitlab/-/issues/25649). +- [Pipeline security dashboard](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline) To change the visibility of your pipelines and related features: @@ -41,8 +37,10 @@ To change the visibility of your pipelines and related features: When it is cleared: - - For **public** projects, pipelines are visible to everyone. Related features are visible - only to project members (Reporter or higher). + - For **public** projects, job logs, job artifacts, the pipeline security dashboard, + and the **CI/CD** menu items are visible only to project members (Reporter or higher). + Other users, including guest users, can only view the status of pipelines and jobs, and only + when viewing merge requests or commits. - For **internal** projects, pipelines are visible to all logged in users except [external users](../../user/permissions.md#external-users). Related features are visible only to project members (Reporter or higher). - For **private** projects, pipelines and related features are visible to project members (Reporter or higher) only. @@ -161,7 +159,8 @@ in the `.gitlab-ci.yml` file. ## Limit the number of changes fetched during clone -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28919) in GitLab 12.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28919) in GitLab 12.0. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77576) `git depth` value in GitLab 14.7. You can limit the number of changes that GitLab CI/CD fetches when it clones a repository. @@ -173,8 +172,8 @@ a repository. The maximum value is `1000`. To disable shallow clone and make GitLab CI/CD fetch all branches and tags each time, keep the value empty or set to `0`. -In GitLab 12.0 and later, newly created projects automatically have a default -`git depth` value of `50`. +In GitLab versions 14.7 and later, newly created projects have a default `git depth` +value of `20`. GitLab versions 14.6 and earlier have a default `git depth` value of `50`. This value can be overridden by the [`GIT_DEPTH` variable](../large_repositories/index.md#shallow-cloning) in the `.gitlab-ci.yml` file. diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index c67282643a4..37005939eb7 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -181,7 +181,7 @@ After you have the route mapping set up, it takes effect in the following locati  -- In the diff for a merge request, comparison, or commit. +- In the diff for a comparison or commit.  diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index b2885262e9d..d826b28acce 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -2,7 +2,6 @@ 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/#assignments -type: reference --- # Configuring runners **(FREE)** @@ -640,7 +639,7 @@ support this feature. A meter can be enabled to provide the rate of transfer for uploads and downloads. -You can set a maximum time for cache upload and download with the `CACHE_REQUEST_TIMEOUT` setting. +You can set a maximum time for cache upload and download with the `CACHE_REQUEST_TIMEOUT` setting. This setting can be useful when slow cache uploads substantially increase the duration of your job. ```yaml diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index b4e9fe818cf..064ad64b79f 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -17,6 +17,6 @@ No configuration is required. Your jobs can run on: - [Windows runners](build_cloud/windows_build_cloud.md) (beta). - [macOS runners](build_cloud/macos_build_cloud.md) (beta). -The number of minutes you can use on these runners depends on your -[quota](../../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota), -which depends on your [subscription plan](../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes). +The number of minutes you can use on these runners depends on the +[maximum number of CI/CD minutes](../pipelines/cicd_minutes.md) +in your [subscription plan](https://about.gitlab.com/pricing/). diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index b16957ae83c..f76a767abec 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -28,13 +28,13 @@ If you are using a self-managed instance of GitLab: going to your project's **Settings > CI/CD**, expanding the **Runners** section, and clicking **Show runner installation instructions**. These instructions are also available [in the documentation](https://docs.gitlab.com/runner/install/index.html). -- The administrator can also configure a maximum number of shared runner [pipeline minutes for - each group](../../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota). +- The administrator can also configure a maximum number of shared runner [CI/CD minutes for + each group](../pipelines/cicd_minutes.md#set-the-quota-of-cicd-minutes-for-a-specific-namespace). If you are using GitLab.com: - You can select from a list of [shared runners that GitLab maintains](index.md). -- The shared runners consume the [pipelines minutes](../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes) +- The shared runners consume the [CI/CD minutes](../pipelines/cicd_minutes.md) included with your account. ### Enable shared runners diff --git a/doc/ci/runners/saas/windows_saas_runner.md b/doc/ci/runners/saas/windows_saas_runner.md index 87ee542fb14..b08be14dbc3 100644 --- a/doc/ci/runners/saas/windows_saas_runner.md +++ b/doc/ci/runners/saas/windows_saas_runner.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w SaaS runners on Windows are in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) and shouldn't be used for production workloads. -During this beta period, the [shared runner pipeline quota](../../../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) +During this beta period, the [shared runner quota for CI/CD minutes](../../pipelines/cicd_minutes.md) applies for groups and projects in the same manner as Linux runners. This may change when the beta period ends, as discussed in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834). diff --git a/doc/ci/test_cases/index.md b/doc/ci/test_cases/index.md index 4c840125d24..384bfc10779 100644 --- a/doc/ci/test_cases/index.md +++ b/doc/ci/test_cases/index.md @@ -11,10 +11,6 @@ type: reference > - [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. -INFO: -Create test cases in GitLab Ultimate. -[Try it free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-test-cases-docs). - Test cases in GitLab can help your teams create testing scenarios in their existing development platform. Now your Implementation and Testing teams can collaborate better, as they no longer have to diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index d3ac1de7c3b..1b648a486ef 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -54,7 +54,7 @@ For example: ```shell curl --request POST \ --form token=<token> \ - --formref=<ref_name> \ + --form ref=<ref_name> \ "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline" ``` @@ -104,20 +104,18 @@ To trigger a pipeline from another project's webhook, use a webhook URL like the for push and tag events: ```plaintext -https://gitlab.example.com/api/v4/projects/9/ref/main/trigger/pipeline?token=TOKEN +https://gitlab.example.com/api/v4/projects/<project_id>/ref/<ref_name>/trigger/pipeline?token=<token> ``` Replace: - The URL with `https://gitlab.com` or the URL of your instance. -- `<token>` with your trigger token. -- `<ref_name>` with a branch or tag name, like `main`. - `<project_id>` with your project ID, like `123456`. The project ID is displayed at the top of the project's landing page. - -The `ref` in the URL takes precedence over the `ref` in the webhook payload. The -payload `ref` is the branch that fired the trigger in the source repository. -You must URL-encode `ref` if it contains slashes. +- `<ref_name>` with a branch or tag name, like `main`. This value takes precedence over the `ref_name` in the webhook payload. + The payload's `ref` is the branch that fired the trigger in the source repository. + You must URL-encode the `ref_name` if it contains slashes. +- `<token>` with your trigger token. #### Use a webhook payload diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index acc3489143a..7ce58b015ca 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -81,7 +81,7 @@ to execute scripts. Each shell has its own set of reserved variable names. Make sure each variable is defined for the [scope you want to use it in](where_variables_can_be_used.md). By default, pipelines from forked projects can't access CI/CD variables in the parent project. -If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project), +If you [run a merge request pipeline in the parent project for a merge request from a fork](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project), all variables become available to the pipeline. ### Create a custom CI/CD variable in the `.gitlab-ci.yml` file @@ -394,7 +394,7 @@ runs on a [protected branch](../../user/project/protected_branches.md) or Review all merge requests that introduce changes to the `.gitlab-ci.yml` file before you: -- [Run a pipeline in the parent project for a merge request submitted from a forked project](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project). +- [Run a pipeline in the parent project for a merge request submitted from a forked project](../pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project). - Merge the changes. The following example shows malicious code in a `.gitlab-ci.yml` file: @@ -554,37 +554,45 @@ export GITLAB_USER_ID="42" > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22638) in GitLab 13.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217834) in GitLab 13.1. -You can pass environment variables from one job to another job in a later stage. +You can pass environment variables from one job to another job in a later stage +through variable inheritance. These variables cannot be used as CI/CD variables to configure a pipeline, but they can be used in job scripts. 1. In the job script, save the variable as a `.env` file. + - The format of the file must be one variable definition per line. + - Each defined line must be of the form `VARIABLE_NAME=ANY VALUE HERE`. + - Values can be wrapped in quotes, but cannot contain newline characters. 1. Save the `.env` file as an [`artifacts:reports:dotenv`](../yaml/artifacts_reports.md#artifactsreportsdotenv) artifact. -1. Set a job in a later stage to receive the artifact by using the [`dependencies`](../yaml/index.md#dependencies) - or the [`needs`](../yaml/index.md#needs) keywords. -1. The later job can then [use the variable in scripts](#use-cicd-variables-in-job-scripts). +1. Jobs in later stages can then [use the variable in scripts](#use-cicd-variables-in-job-scripts). -For example, with the [`dependencies`](../yaml/index.md#dependencies) keyword: +Inherited variables [take precedence](#cicd-variable-precedence) over +certain types of new variable definitions such as job defined variables. ```yaml build: stage: build script: - - echo "BUILD_VERSION=hello" >> build.env + - echo "BUILD_VARIABLE=value_from_build_job" >> build.env artifacts: reports: dotenv: build.env deploy: stage: deploy + variables: + BUILD_VARIABLE: value_from_deploy_job script: - - echo "$BUILD_VERSION" # Output is: 'hello' - dependencies: - - build + - echo "$BUILD_VARIABLE" # Output is: 'value_from_build_job' due to precedence ``` -For example, with the [`needs:artifacts`](../yaml/index.md#needsartifacts) keyword: +The [`dependencies`](../yaml/index.md#dependencies) or +[`needs`](../yaml/index.md#needs) keywords can be used to control +which jobs receive inherited values. + +To have no inherited dotenv environment variables, pass an empty `dependencies` or +`needs` list, or pass [`needs:artifacts`](../yaml/index.md#needsartifacts) as `false` ```yaml build: @@ -595,15 +603,46 @@ build: reports: dotenv: build.env -deploy: +deploy_one: + stage: deploy + script: + - echo "$BUILD_VERSION" # Output is: 'hello' + dependencies: + - build + +deploy_two: + stage: deploy + script: + - echo "$BUILD_VERSION" # Output is empty + dependencies: [] + +deploy_three: stage: deploy script: - echo "$BUILD_VERSION" # Output is: 'hello' needs: - - job: build - artifacts: true + - build + +deploy_four: + stage: deploy + script: + - echo "$BUILD_VERSION" # Output is: 'hello' + needs: + job: build + artifacts: true + +deploy_five: + stage: deploy + script: + - echo "$BUILD_VERSION" # Output is empty + needs: + job: build + artifacts: false ``` +[Multi-project pipelines](../pipelines/multi_project_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline-by-using-variable-inheritance) +can also inherit variables from their upstream pipelines. + ## CI/CD variable precedence You can use CI/CD variables with the same name in different places, but the values diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index c06ca6878c4..60888cd9b97 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -62,6 +62,8 @@ There are also a number of [variables you can use to configure runner behavior]( | `CI_JOB_ID` | 9.0 | all | The internal ID of the job, unique across all jobs in the GitLab instance. | | `CI_JOB_IMAGE` | 12.9 | 12.9 | The name of the Docker image running the job. | | `CI_JOB_JWT` | 12.10 | all | A RS256 JSON web token to authenticate with third party systems that support JWT authentication, for example [HashiCorp's Vault](../secrets/index.md). | +| `CI_JOB_JWT_V1` | 14.6 | all | The same value as `CI_JOB_JWT`. | +| `CI_JOB_JWT_V2` | 14.6 | all | [**alpha:**](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) A newly formatted RS256 JSON web token to increase compatibility. Similar to `CI_JOB_JWT`, except the issuer (`iss`) claim is changed from `gitlab.com` to `https://gitlab.com`, `sub` has changed from `job_id` to a string that contains the project path, and an `aud` claim is added. Format is subject to change. Be aware, the `aud` field is a constant value. Trusting JWTs in multiple relying parties can lead to [one RP sending a JWT to another one and acting maliciously as a job](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/72555#note_769112331). | | `CI_JOB_MANUAL` | 8.12 | all | `true` if a job was started manually. | | `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job. | | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the job's stage. | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index e32f0391d2e..4f304a10256 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -22,20 +22,25 @@ There are two places defined variables can be used. On the: ### `.gitlab-ci.yml` file -| Definition | Can be expanded? | Expansion place | Description | -|:-------------------------------------------|:-----------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `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/>- `CI_ENVIRONMENT_URL`<br/>- [Persisted variables](#persisted-variables) | -| `include` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. <br/><br/>Predefined project variables are supported: `GITLAB_FEATURES`, `CI_DEFAULT_BRANCH`, and all variables that start with `CI_PROJECT_` (for example `CI_PROJECT_NAME`). | -| `variables` | yes | GitLab/Runner | The variable expansion is first made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab, and then any unrecognized or unavailable variables are expanded by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | -| `image` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | -| `services:[]` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | -| `services:[]:name` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | -| `cache:key` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | -| `artifacts:name` | yes | Runner | The variable expansion is made by GitLab Runner's shell environment | -| `script`, `before_script`, `after_script` | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment) | -| `only:variables:[]`, `except:variables:[]`, `rules:if` | no | n/a | The variable must be in the form of `$variable`. Not supported are 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). | +| Definition | Can be expanded? | Expansion place | Description | +|:----------------------|:-----------------|:-----------------------|:------------| +| `after_script` | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment). | +| `artifacts:name` | yes | Runner | The variable expansion is made by GitLab Runner's shell environment. | +| `before_script` | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment) | +| `cache:key` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | +| `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). | +| `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`. | +| `except:variables:[]` | no | n/a | The variable must be in the form of `$variable`. Not supported are 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). | +| `image` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | +| `include` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. <br/><br/>Predefined project variables are supported: `GITLAB_FEATURES`, `CI_DEFAULT_BRANCH`, and all variables that start with `CI_PROJECT_` (for example `CI_PROJECT_NAME`). | +| `only:variables:[]` | no | n/a | The variable must be in the form of `$variable`. Not supported are 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/>- `CI_ENVIRONMENT_URL`<br/>- [Persisted variables](#persisted-variables). | +| `rules:if` | no | n/a | The variable must be in the form of `$variable`. Not supported are 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). | +| `script` | yes | Script execution shell | The variable expansion is made by the [execution shell environment](#execution-shell-environment). | +| `services:[]:name` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | +| `services:[]` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | +| `tags` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35742) in GitLab 14.1. | +| `variables` | yes | GitLab/Runner | The variable expansion is first made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab, and then any unrecognized or unavailable variables are expanded by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | ### `config.toml` file diff --git a/doc/ci/yaml/artifacts_reports.md b/doc/ci/yaml/artifacts_reports.md index cd38cf58c71..25fb861cfb7 100644 --- a/doc/ci/yaml/artifacts_reports.md +++ b/doc/ci/yaml/artifacts_reports.md @@ -52,7 +52,7 @@ GitLab can display the results of one or more reports in: - The merge request [security widget](../../user/application_security/api_fuzzing/index.md#view-details-of-an-api-fuzzing-vulnerability). - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). +- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline). - The [security dashboard](../../user/application_security/api_fuzzing/index.md#security-dashboard). ## `artifacts:reports:browser_performance` **(PREMIUM)** @@ -117,7 +117,7 @@ The collected Container Scanning report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in: - The merge request [container scanning widget](../../user/application_security/container_scanning/index.md). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). +- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline). - The [security dashboard](../../user/application_security/security_dashboard/index.md). - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). @@ -131,7 +131,7 @@ The collected coverage fuzzing report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in: - The merge request [coverage fuzzing widget](../../user/application_security/coverage_fuzzing/index.md#interacting-with-the-vulnerabilities). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). +- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline). - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). - The [security dashboard](../../user/application_security/security_dashboard/index.md). @@ -143,7 +143,7 @@ report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in: - The merge request [security widget](../../user/application_security/dast/index.md#view-details-of-a-vulnerability-detected-by-dast). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). +- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline). - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). - The [security dashboard](../../user/application_security/security_dashboard/index.md). @@ -155,7 +155,7 @@ The collected Dependency Scanning report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in: - The merge request [dependency scanning widget](../../user/application_security/dependency_scanning/index.md#overview). -- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#pipeline-security). +- The pipeline [**Security** tab](../../user/application_security/security_dashboard/index.md#view-vulnerabilities-in-a-pipeline). - The [security dashboard](../../user/application_security/security_dashboard/index.md). - The [Project Vulnerability report](../../user/application_security/vulnerability_report/index.md). - The [dependency list](../../user/application_security/dependency_list/). diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index ed05ef08d02..4530e2675c4 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -24,12 +24,13 @@ A GitLab CI/CD pipeline configuration includes: - [Global keywords](#global-keywords) that configure pipeline behavior: - | Keyword | Description | - |-------------------------|:------------| - | [`default`](#default) | Custom default values for job keywords. | - | [`include`](#include) | Import configuration from other YAML files. | - | [`stages`](#stages) | The names and order of the pipeline stages. | - | [`workflow`](#workflow) | Control what types of pipeline run. | + | Keyword | Description | + |---------------------------|:------------| + | [`default`](#default) | Custom default values for job keywords. | + | [`include`](#include) | Import configuration from other YAML files. | + | [`stages`](#stages) | The names and order of the pipeline stages. | + | [`variables`](#variables) | Define CI/CD variables for all job in the pipeline. | + | [`workflow`](#workflow) | Control what types of pipeline run. | - [Jobs](../jobs/index.md) configured with [job keywords](#job-keywords): @@ -414,6 +415,7 @@ and the pipeline is for either: - You can use the [`workflow:rules` templates](workflow.md#workflowrules-templates) to import a preconfigured `workflow: rules` entry. - [Common `if` clauses for `workflow:rules`](workflow.md#common-if-clauses-for-workflowrules). +- [Use `rules` to run pipelines for merge requests](../pipelines/merge_request_pipelines.md#use-rules-to-add-jobs). #### `workflow:rules:variables` @@ -1429,13 +1431,13 @@ test osx: stage: test script: make test:osx dependencies: - - build:osx + - build osx test linux: stage: test script: make test:linux dependencies: - - build:linux + - build linux deploy: stage: deploy @@ -2506,8 +2508,7 @@ docker build: - [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples). - If you use `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`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests). -- Use `changes` with [new branches or tags *without* pipelines for merge requests](../jobs/job_control.md#use-onlychanges-without-pipelines-for-merge-requests). -- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines). +- [Jobs or pipelines can run unexpectedly when using `only: changes`](../jobs/job_control.md#jobs-or-pipelines-run-unexpectedly-when-using-changes). #### `only:kubernetes` / `except:kubernetes` @@ -3066,8 +3067,10 @@ job: - If a rule matches and has no `when` defined, the rule uses the `when` defined for the job, which defaults to `on_success` if not defined. -- You can define `when` once per rule, or once at the job-level, which applies to - all rules. You can't mix `when` at the job-level with `when` in rules. +- In GitLab 14.5 and earlier, you can define `when` once per rule, or once at the job-level, + which applies to all rules. You can't mix `when` at the job-level with `when` in rules. +- In GitLab 14.6 and later, you can [mix `when` at the job-level with `when` in rules](https://gitlab.com/gitlab-org/gitlab/-/issues/219437). + `when` configuration in `rules` takes precedence over `when` at the job-level. - Unlike variables in [`script`](../variables/index.md#use-cicd-variables-in-job-scripts) sections, variables in rules expressions are always formatted as `$VARIABLE`. - You can use `rules:if` with `include` to [conditionally include other configuration files](includes.md#use-rules-with-include). @@ -3076,6 +3079,7 @@ job: - [Common `if` expressions for `rules`](../jobs/job_control.md#common-if-clauses-for-rules). - [Avoid duplicate pipelines](../jobs/job_control.md#avoid-duplicate-pipelines). +- [Use `rules` to run pipelines for merge requests](../pipelines/merge_request_pipelines.md#use-rules-to-add-jobs). #### `rules:changes` @@ -3120,6 +3124,10 @@ docker build: - You can use `when: never` to implement a rule similar to [`except:changes`](#onlychanges--exceptchanges). - `changes` resolves to `true` if any of the matching files are changed (an `OR` operation). +**Related topics**: + +- [Jobs or pipelines can run unexpectedly when using `rules: changes`](../jobs/job_control.md#jobs-or-pipelines-run-unexpectedly-when-using-changes). + #### `rules:exists` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4. @@ -3834,13 +3842,13 @@ The following keywords are deprecated. ### Globally-defined `types` WARNING: -`types` is deprecated, and could be removed in a future release. +`types` is deprecated, and is [scheduled to be removed in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/346823). Use [`stages`](#stages) instead. ### Job-defined `type` WARNING: -`type` is deprecated, and could be removed in one of the future releases. +`type` is deprecated, and is [scheduled to be removed in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/346823). Use [`stage`](#stage) instead. ### Globally-defined `image`, `services`, `cache`, `before_script`, `after_script` diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index fdec0947df5..ca1e79c2395 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -164,10 +164,14 @@ Second command line. When you omit the `>` or `|` block scalar indicators, GitLab concatenates non-empty lines to form the command. Make sure the lines can run when concatenated. -[These documents](https://en.wikipedia.org/wiki/Here_document) work with the +<!-- vale gitlab.MeaningfulLinkWords = NO --> + +[Shell here documents](https://en.wikipedia.org/wiki/Here_document) work with the `|` and `>` operators as well. The example below transliterates lower case letters to upper case: +<!-- vale gitlab.MeaningfulLinkWords = YES --> + ```yaml job: script: diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md index 2075e7cda3c..15d21883bb8 100644 --- a/doc/development/application_limits.md +++ b/doc/development/application_limits.md @@ -141,6 +141,8 @@ end ### Subscription Plans +> The `opensource` plan was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346399) in GitLab 14.7. + Self-managed: - `default`: Everyone. @@ -156,5 +158,6 @@ GitLab.com: - `gold`: Namespaces and projects with an Ultimate subscription. - `ultimate`: Namespaces and projects with an Ultimate subscription. - `ultimate_trial`: Namespaces and projects with an Ultimate Trial subscription. +- `opensource`: Namespaces and projects that are member of GitLab Open Source program. The `test` environment doesn't have any plans. diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 078eb5dd0de..36d3655ba93 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -339,7 +339,7 @@ Component statuses are linked to configuration documentation for each component. ### Component list -| Component | Description | [Omnibus GitLab](https://docs.gitlab.com/omnibus/) | [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit) | [GitLab chart](https://docs.gitlab.com/charts/) | [Minikube Minimal](https://docs.gitlab.com/charts/development/minikube/#deploying-gitlab-with-minimal-settings) | [GitLab.com](https://gitlab.com) | [Source](../install/installation.md) | [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) | [CE/EE](https://about.gitlab.com/install/ce-or-ee/) | +| Component | Description | [Omnibus GitLab](https://docs.gitlab.com/omnibus/) | [GitLab Environment Toolkit (GET)](https://gitlab.com/gitlab-org/quality/gitlab-environment-toolkit) | [GitLab chart](https://docs.gitlab.com/charts/) | [minikube Minimal](https://docs.gitlab.com/charts/development/minikube/#deploying-gitlab-with-minimal-settings) | [GitLab.com](https://gitlab.com) | [Source](../install/installation.md) | [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) | [CE/EE](https://about.gitlab.com/install/ce-or-ee/) | |-------------------------------------------------------|----------------------------------------------------------------------|:--------------:|:--------------:|:------------:|:----------------:|:----------:|:------:|:---:|:-------:| | [Certificate Management](#certificate-management) | TLS Settings, Let's Encrypt | ✅ | ✅ | ✅ | ⚙ | ✅ | ⚙ | ⚙ | CE & EE | | [Consul](#consul) | Database node discovery, failover | ⚙ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | EE Only | @@ -797,7 +797,7 @@ For monitoring deployed apps, see the [Sentry integration docs](../operations/er - 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/sidekiq/) - - [Minikube Minimal](https://docs.gitlab.com/charts/charts/gitlab/sidekiq/index.html) + - [minikube Minimal](https://docs.gitlab.com/charts/charts/gitlab/sidekiq/index.html) - [Source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) - [GDK](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/gitlab.yml.example) - Layer: Core Service (Processor) diff --git a/doc/development/avoiding_downtime_in_migrations.md b/doc/development/avoiding_downtime_in_migrations.md index a5fc1909551..1d36bbf1212 100644 --- a/doc/development/avoiding_downtime_in_migrations.md +++ b/doc/development/avoiding_downtime_in_migrations.md @@ -228,100 +228,9 @@ can take a very long time to complete, preventing a deployment from proceeding. They can also produce a lot of pressure on the database due to it rapidly updating many rows in sequence. -To reduce database pressure you should instead use -`change_column_type_using_background_migration` or `rename_column_using_background_migration` -when migrating a column in a large table (for example, `issues`). These methods work -similarly to the concurrent counterparts but uses background migration to spread -the work / load over a longer time period, without slowing down deployments. - -For example, to change the column type using a background migration: - -```ruby -class ExampleMigration < Gitlab::Database::Migration[1.0] - disable_ddl_transaction! - - class Issue < ActiveRecord::Base - self.table_name = 'issues' - - include EachBatch - - def self.to_migrate - where('closed_at IS NOT NULL') - end - end - - def up - change_column_type_using_background_migration( - Issue.to_migrate, - :closed_at, - :datetime_with_timezone - ) - end - - def down - change_column_type_using_background_migration( - Issue.to_migrate, - :closed_at, - :datetime - ) - end -end -``` - -This would change the type of `issues.closed_at` to `timestamp with time zone`. - -Keep in mind that the relation passed to -`change_column_type_using_background_migration` _must_ include `EachBatch`, -otherwise it will raise a `TypeError`. - -This migration then needs to be followed in a separate release (_not_ a patch -release) by a cleanup migration, which should steal from the queue and handle -any remaining rows. For example: - -```ruby -class MigrateRemainingIssuesClosedAt < Gitlab::Database::Migration[1.0] - disable_ddl_transaction! - - class Issue < ActiveRecord::Base - self.table_name = 'issues' - include EachBatch - end - - def up - Gitlab::BackgroundMigration.steal('CopyColumn') - Gitlab::BackgroundMigration.steal('CleanupConcurrentTypeChange') - - migrate_remaining_rows if migrate_column_type? - end - - def down - # Previous migrations already revert the changes made here. - end - - def migrate_remaining_rows - Issue.where('closed_at_for_type_change IS NULL AND closed_at IS NOT NULL').each_batch do |batch| - batch.update_all('closed_at_for_type_change = closed_at') - end - - cleanup_concurrent_column_type_change(:issues, :closed_at) - end - - def migrate_column_type? - # Some environments may have already executed the previous version of this - # migration, thus we don't need to migrate those environments again. - column_for('issues', 'closed_at').type == :datetime # rubocop:disable Migration/Datetime - end -end -``` - -The same applies to `rename_column_using_background_migration`: - -1. Create a migration using the helper, which will schedule background - migrations to spread the writes over a longer period of time. -1. In the next monthly release, create a clean-up migration to steal from the - Sidekiq queues, migrate any missing rows, and cleanup the rename. This - migration should skip the steps after stealing from the Sidekiq queues if the - column has already been renamed. +To reduce database pressure you should instead use a background migration +when migrating a column in a large table (for example, `issues`). This will +spread the work / load over a longer time period, without slowing down deployments. For more information, see [the documentation on cleaning up background migrations](background_migrations.md#cleaning-up). diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index 4a18b2123da..49835085f96 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -83,23 +83,11 @@ replacing the class name and arguments with whatever values are necessary for your migration: ```ruby -migrate_async('BackgroundMigrationClassName', [arg1, arg2, ...]) +migrate_in('BackgroundMigrationClassName', [arg1, arg2, ...]) ``` -Usually it's better to enqueue jobs in bulk, for this you can use -`bulk_migrate_async`: - -```ruby -bulk_migrate_async( - [['BackgroundMigrationClassName', [1]], - ['BackgroundMigrationClassName', [2]]] -) -``` - -Note that this will queue a Sidekiq job immediately: if you have a large number -of records, this may not be what you want. You can use the function -`queue_background_migration_jobs_by_range_at_intervals` to split the job into -batches: +You can use the function `queue_background_migration_jobs_by_range_at_intervals` +to automatically split the job into batches: ```ruby queue_background_migration_jobs_by_range_at_intervals( @@ -117,16 +105,6 @@ consuming migrations it's best to schedule a background job using an updates. Removals in turn can be handled by simply defining foreign keys with cascading deletes. -If you would like to schedule jobs in bulk with a delay, you can use -`BackgroundMigrationWorker.bulk_perform_in`: - -```ruby -jobs = [['BackgroundMigrationClassName', [1]], - ['BackgroundMigrationClassName', [2]]] - -bulk_migrate_in(5.minutes, jobs) -``` - ### Rescheduling background migrations If one of the background migrations contains a bug that is fixed in a patch @@ -197,53 +175,47 @@ the new format. ## Example -To explain all this, let's use the following example: the table `services` has a +To explain all this, let's use the following example: the table `integrations` has a field called `properties` which is stored in JSON. For all rows you want to -extract the `url` key from this JSON object and store it in the `services.url` -column. There are millions of services and parsing JSON is slow, thus you can't +extract the `url` key from this JSON object and store it in the `integrations.url` +column. There are millions of integrations and parsing JSON is slow, thus you can't do this in a regular migration. To do this using a background migration we'll start with defining our migration class: ```ruby -class Gitlab::BackgroundMigration::ExtractServicesUrl - class Service < ActiveRecord::Base - self.table_name = 'services' +class Gitlab::BackgroundMigration::ExtractIntegrationsUrl + class Integration < ActiveRecord::Base + self.table_name = 'integrations' end - def perform(service_id) - # A row may be removed between scheduling and starting of a job, thus we - # need to make sure the data is still present before doing any work. - service = Service.select(:properties).find_by(id: service_id) + def perform(start_id, end_id) + Integration.where(id: start_id..end_id).each do |integration| + json = JSON.load(integration.properties) - return unless service - - begin - json = JSON.load(service.properties) + integration.update(url: json['url']) if json['url'] rescue JSON::ParserError # If the JSON is invalid we don't want to keep the job around forever, # instead we'll just leave the "url" field to whatever the default value # is. - return + next end - - service.update(url: json['url']) if json['url'] end end ``` Next we'll need to adjust our code so we schedule the above migration for newly -created and updated services. We can do this using something along the lines of +created and updated integrations. We can do this using something along the lines of the following: ```ruby -class Service < ActiveRecord::Base - after_commit :schedule_service_migration, on: :update - after_commit :schedule_service_migration, on: :create +class Integration < ActiveRecord::Base + after_commit :schedule_integration_migration, on: :update + after_commit :schedule_integration_migration, on: :create - def schedule_service_migration - BackgroundMigrationWorker.perform_async('ExtractServicesUrl', [id]) + def schedule_integration_migration + BackgroundMigrationWorker.perform_async('ExtractIntegrationsUrl', [id, id]) end end ``` @@ -253,21 +225,20 @@ before the transaction completes as doing so can lead to race conditions where the changes are not yet visible to the worker. Next we'll need a post-deployment migration that schedules the migration for -existing data. Since we're dealing with a lot of rows we'll schedule jobs in -batches instead of doing this one by one: +existing data. ```ruby -class ScheduleExtractServicesUrl < Gitlab::Database::Migration[1.0] +class ScheduleExtractIntegrationsUrl < Gitlab::Database::Migration[1.0] disable_ddl_transaction! - def up - define_batchable_model('services').select(:id).in_batches do |relation| - jobs = relation.pluck(:id).map do |id| - ['ExtractServicesUrl', [id]] - end + MIGRATION = 'ExtractIntegrationsUrl' + DELAY_INTERVAL = 2.minutes - BackgroundMigrationWorker.bulk_perform_async(jobs) - end + def up + queue_background_migration_jobs_by_range_at_intervals( + define_batchable_model('integrations'), + MIGRATION, + DELAY_INTERVAL) end def down @@ -284,18 +255,18 @@ jobs and manually run on any un-migrated rows. Such a migration would look like this: ```ruby -class ConsumeRemainingExtractServicesUrlJobs < Gitlab::Database::Migration[1.0] +class ConsumeRemainingExtractIntegrationsUrlJobs < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up # This must be included - Gitlab::BackgroundMigration.steal('ExtractServicesUrl') + Gitlab::BackgroundMigration.steal('ExtractIntegrationsUrl') # This should be included, but can be skipped - see below - define_batchable_model('services').where(url: nil).each_batch(of: 50) do |batch| + define_batchable_model('integrations').where(url: nil).each_batch(of: 50) do |batch| range = batch.pluck('MIN(id)', 'MAX(id)').first - Gitlab::BackgroundMigration::ExtractServicesUrl.new.perform(*range) + Gitlab::BackgroundMigration::ExtractIntegrationsUrl.new.perform(*range) end end @@ -313,9 +284,9 @@ If the application does not depend on the data being 100% migrated (for instance, the data is advisory, and not mission-critical), then this final step can be skipped. -This migration will then process any jobs for the ExtractServicesUrl migration +This migration will then process any jobs for the ExtractIntegrationsUrl migration and continue once all jobs have been processed. Once done you can safely remove -the `services.properties` column. +the `integrations.properties` column. ## Testing diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md index d04761400ac..f9c96e414d0 100644 --- a/doc/development/cascading_settings.md +++ b/doc/development/cascading_settings.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 82fd37eacaf..17a70393c96 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -109,6 +109,11 @@ After the server receives the request it selects a `pending` job based on the [` Once all jobs are completed for the current stage, the server "unlocks" all the jobs from the next stage by changing their state to `pending`. These can now be picked by the scheduling algorithm when the runner requests new jobs, and continues like this until all stages are completed. +If a job is not picked up by a runner in 24 hours it is automatically removed from +the processing queue after that time. If a pending job is stuck, when there is no +runner available that can process it, it is removed from the queue after 1 hour. +In both cases the job's status is changed to `failed` with an appropriate failure reason. + ### Communication between runner and GitLab server After the runner is [registered](https://docs.gitlab.com/runner/register/) using the registration token, the server knows what type of jobs it can execute. This depends on: @@ -169,18 +174,18 @@ We have a few inconsistencies in our codebase that should be refactored. For example, `CommitStatus` should be `Ci::Job` and `Ci::JobArtifact` should be `Ci::BuildArtifact`. See [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16111) for the full refactoring plan. -## CI Minutes +## CI/CD Minutes -This diagram shows how the [CI minutes](../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes) +This diagram shows how the [CI/CD minutes](../../ci/pipelines/cicd_minutes.md) feature and its components work. - + <!-- Editable diagram available at https://app.diagrams.net/?libs=general;flowchart#G1XjLPvJXbzMofrC3eKRyDEk95clV6ypOb --> Watch a walkthrough of this feature in details in the video below. <div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=NmdWRGT8kZg">CI Minutes - architectural overview</a>. + See the video: <a href="https://www.youtube.com/watch?v=NmdWRGT8kZg">CI/CD minutes - architectural overview</a>. </div> <figure class="video-container"> <iframe src="https://www.youtube.com/embed/NmdWRGT8kZg" frameborder="0" allowfullscreen="true"> </iframe> diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 742d183e15c..1ed510c6ad7 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -394,9 +394,9 @@ the roulette is not available, choose someone else from that list. It is the responsibility of the author for the merge request to be reviewed. If it stays in the `ready for review` state too long it is recommended to request a review from a specific reviewer. -#### List of merge requests ready for review +### Volunteering to review -Developers who have capacity can regularly check the list of [merge requests to review](https://gitlab.com/groups/gitlab-org/-/merge_requests?state=opened&label_name%5B%5D=workflow%3A%3Aready%20for%20review) and add themselves as a reviewer for any merge request they want to review. +GitLab engineers who have capacity can regularly check the list of [merge requests to review](https://gitlab.com/groups/gitlab-org/-/merge_requests?state=opened&label_name%5B%5D=workflow%3A%3Aready%20for%20review) and add themselves as a reviewer for any merge request they want to review. ### Reviewing a merge request @@ -501,7 +501,7 @@ Merge Results against the latest `main` at the time of the pipeline creation. WARNING: **Review all changes thoroughly for malicious code before starting a -[Pipeline for Merged Results](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project).** +[Pipeline for Merged Results](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project).** When reviewing merge requests added by wider community contributors: @@ -522,9 +522,12 @@ If the MR source branch is more than 1,000 commits behind the target branch: or check with the contributor first when they're actively working on the MR. - The rebase can usually be done inside GitLab with the `/rebase` [quick action](../user/project/quick_actions.md). +#### Taking over a community merge request + When an MR needs further changes but the author is not responding for a long period of time, -or unable to finish the MR, we can take it over in accordance with our -[Closing policy for issues and merge requests](contributing/#closing-policy-for-issues-and-merge-requests): +or is unable to finish the MR, GitLab can take it over in accordance with our +[Closing policy for issues and merge requests](contributing/#closing-policy-for-issues-and-merge-requests). +A GitLab engineer (generally the merge request coach) will: 1. Add a comment to their MR saying you'll take it over to be able to get it merged. 1. Add the label `~"coach will finish"` to their MR. diff --git a/doc/development/database/efficient_in_operator_queries.md b/doc/development/database/efficient_in_operator_queries.md index 1e706890f64..76518a6f5e2 100644 --- a/doc/development/database/efficient_in_operator_queries.md +++ b/doc/development/database/efficient_in_operator_queries.md @@ -589,6 +589,87 @@ LIMIT 20 NOTE: To make the query efficient, the following columns need to be covered with an index: `project_id`, `issue_type`, `created_at`, and `id`. +#### Using calculated ORDER BY expression + +The following example orders epic records by the duration between the creation time and closed +time. It is calculated with the following formula: + +```sql +SELECT EXTRACT('epoch' FROM epics.closed_at - epics.created_at) FROM epics +``` + +The query above returns the duration in seconds (`double precision`) between the two timestamp +columns in seconds. To order the records by this expression, you must reference it +in the `ORDER BY` clause: + +```sql +SELECT EXTRACT('epoch' FROM epics.closed_at - epics.created_at) +FROM epics +ORDER BY EXTRACT('epoch' FROM epics.closed_at - epics.created_at) DESC +``` + +To make this ordering efficient on the group-level with the in-operator optimization, use a +custom `ORDER BY` configuration. Since the duration is not a distinct value (no unique index +present), you must add a tie-breaker column (`id`). + +The following example shows the final `ORDER BY` clause: + +```sql +ORDER BY extract('epoch' FROM epics.closed_at - epics.created_at) DESC, epics.id DESC +``` + +Snippet for loading records ordered by the calcualted duration: + +```ruby +arel_table = Epic.arel_table +order = Gitlab::Pagination::Keyset::Order.build([ + Gitlab::Pagination::Keyset::ColumnOrderDefinition.new( + attribute_name: 'duration_in_seconds', + order_expression: Arel.sql('EXTRACT(EPOCH FROM epics.closed_at - epics.created_at)').desc, + distinct: false, + sql_type: 'double precision' # important for calculated SQL expressions + ), + Gitlab::Pagination::Keyset::ColumnOrderDefinition.new( + attribute_name: 'id', + order_expression: arel_table[:id].desc + ) +]) + +records = Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder.new( + scope: Epic.where.not(closed_at: nil).reorder(order), # filter out NULL values + array_scope: Group.find(9970).self_and_descendants.select(:id), + array_mapping_scope: -> (id_expression) { Epic.where(Epic.arel_table[:group_id].eq(id_expression)) } +).execute.limit(20) + +puts records.pluck(:duration_in_seconds, :id) # other columnns are not available +``` + +Building the query requires quite a bit of configuration. For the order configuration you +can find more information within the +[complex order configuration](keyset_pagination.md#complex-order-configuration) +section for keyset paginated database queries. + +The query requires a specialized database index: + +```sql +CREATE INDEX index_epics_on_duration ON epics USING btree (group_id, EXTRACT(EPOCH FROM epics.closed_at - epics.created_at) DESC, id DESC) WHERE (closed_at IS NOT NULL); +``` + +Notice that the `finder_query` parameter is not used. The query only returns the `ORDER BY` columns +which are the `duration_in_seconds` (calculated column) and the `id` columns. This is a limitation +of the feature, defining the `finder_query` with calculated `ORDER BY` expressions is not supported. +To get the complete database records, an extra query can be invoked by the returned `id` column: + +```ruby +records_by_id = records.index_by(&:id) +complete_records = Epic.where(id: records_by_id.keys).index_by(&:id) + +# Printing the complete records according to the `ORDER BY` clause +records_by_id.each do |id, _| + puts complete_records[id].attributes +end +``` + #### Batch iteration Batch iteration over the records is possible via the keyset `Iterator` class. diff --git a/doc/development/database/loose_foreign_keys.md b/doc/development/database/loose_foreign_keys.md index c60989f225d..97d150b1a18 100644 --- a/doc/development/database/loose_foreign_keys.md +++ b/doc/development/database/loose_foreign_keys.md @@ -43,7 +43,7 @@ we can: 1. Create a `DELETE` trigger on the `projects` table. Record the deletions in a separate table (`deleted_records`). -1. A job checks the `deleted_records` table every 5 minutes. +1. A job checks the `deleted_records` table every minute or two. 1. For each record in the table, delete the associated `ci_pipelines` records using the `project_id` column. @@ -89,9 +89,10 @@ ci_pipelines: ### Track record changes -To know about deletions in the `projects` table, configure a `DELETE` trigger using a database -migration (post-migration). The trigger needs to be configured only once. If the model already has -at least one `loose_foreign_key` definition, then this step can be skipped: +To know about deletions in the `projects` table, configure a `DELETE` trigger +using a [post-deployment migration](../post_deployment_migrations.md). The +trigger needs to be configured only once. If the model already has at least one +`loose_foreign_key` definition, then this step can be skipped: ```ruby class TrackProjectRecordChanges < Gitlab::Database::Migration[1.0] @@ -122,15 +123,20 @@ REFERENCES projects(id) ON DELETE CASCADE; ``` -The migration should run after the `DELETE` trigger is installed. If the foreign key is deleted -earlier, there is a good chance of introducing data inconsistency which needs manual cleanup: +The migration must run after the `DELETE` trigger is installed and the loose +foreign key definition is deployed. As such, it must be a [post-deployment +migration](../post_deployment_migrations.md) dated after the migration for the +trigger. If the foreign key is deleted earlier, there is a good chance of +introducing data inconsistency which needs manual cleanup: ```ruby class RemoveProjectsCiPipelineFk < Gitlab::Database::Migration[1.0] - enable_lock_retries! + disable_ddl_transaction! def up - remove_foreign_key_if_exists(:ci_pipelines, :projects, name: "fk_86635dbd80") + with_lock_retries do + remove_foreign_key_if_exists(:ci_pipelines, :projects, name: "fk_86635dbd80") + end end def down @@ -155,6 +161,17 @@ it_behaves_like 'it has loose foreign keys' do end ``` +**After** [removing a foreign key](#remove-the-foreign-key), +use the "`cleanup by a loose foreign key`" shared example to test a child record's deletion or nullification +via the added loose foreign key: + +```ruby +it_behaves_like 'cleanup by a loose foreign key' do + let!(:model) { create(:ci_pipeline, user: create(:user)) } + let!(:parent) { model.user } +end +``` + ## Caveats of loose foreign keys ### Record creation diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 45be797b720..082c843a12c 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -132,6 +132,18 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - This job runs migrations in a production-like environment (similar to `#database_lab`) and posts to the MR its findings (queries, runtime, size change). - Review migration runtimes and any warnings. +#### Preparation when adding data migrations + +Data migrations are inherently risky. Additional actions are required to reduce the possibility +of error that would result in corruption or loss of production data. + +Include in the MR description: + +- If the migration itself is not reversible, details of how data changes could be reverted in the event of an incident. For example, in the case of a migration that deletes records (an operation that most of the times is not automatically revertable), how _could_ the deleted records be recovered. +- If the migration deletes data, apply the label `~data-deletion`. +- Concise descriptions of possible user experience impact of an error; for example, "Issues would unexpectedly go missing from Epics". +- Relevant data from the [query plans](#query-plans) that indicate the query works as expected; such as the approximate number of records that will be modified/deleted. + #### Preparation when adding or modifying queries ##### Raw SQL diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 6a618e47211..1e4698ff867 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -1,6 +1,7 @@ --- -type: reference, dev info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +stage: none +group: unassigned description: "GitLab development - how to document features deployed behind feature flags" --- diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md index ef94c33a276..8f13048f663 100644 --- a/doc/development/documentation/redirects.md +++ b/doc/development/documentation/redirects.md @@ -94,7 +94,6 @@ To add a redirect: ``` If you don't want to use the Rake task, you can use the following template. - However, the file paths must be relative to the `doc` or `docs` directory. Replace the value of `redirect_to` with the new file path and `YYYY-MM-DD` with the date the file should be removed. diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 5dc627c93e9..4d654b6b901 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -1,5 +1,7 @@ --- info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +stage: none +group: unassigned description: 'Writing styles, markup, formatting, and other standards for the GitLab RESTful APIs.' --- diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 7f2e5a1ba26..e57ffb90028 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -1,5 +1,7 @@ --- info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +stage: none +group: unassigned description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' --- @@ -13,7 +15,7 @@ use the `#docs-processes` channel. In addition to this page, the following resources can help you craft and contribute to documentation: - [Doc contribution guidelines](../index.md) -- [A-Z word list](word_list.md) +- [Recommended word list](word_list.md) - [Doc style and consistency testing](../testing.md) - [UI text guidelines](https://design.gitlab.com/content/error-messages/) - [GitLab Handbook style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) @@ -392,39 +394,26 @@ especially in tutorials, instructional documentation, and Some contractions, however, should be avoided: -- Do not use the word "GitLab" in a contraction. +<!-- vale gitlab.Possessive = NO --> -- Do not use contractions with a proper noun and a verb. For example: +| Do not use a contraction | Example | Use instead | +|-------------------------------|--------------------------------------------------|------------------------------------------------------------------| +| With a proper noun and a verb | The **Container Registry's** a powerful feature. | The **Container Registry** is a powerful feature. | +| To emphasize a negative | **Don't** install X with Y. | **Do not** install X with Y. | +| In reference documentation | **Don't** set a limit. | **Do not** set a limit. | +| In error messages | Requests to localhost **aren't** allowed. | Requests to localhost **are not** allowed. | - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Canada is establishing X. | Canada's establishing X. | - -- Do not use contractions when you need to emphasize a negative. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do not install X with Y. | Don't install X with Y. | - -- Do not use contractions in reference documentation. For example: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Do not set a limit greater than 1000. | Don't set a limit greater than 1000. | - | For `parameter1`, the default is 10. | For `parameter1`, the default's 10. | - -- Avoid contractions in error messages. Examples: - - | Do | Don't | - |------------------------------------------|-----------------------------------------| - | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | - | Specified URL cannot be used. | Specified URL can't be used. | +<!-- vale gitlab.Possessive = YES --> ### Acronyms If you use an acronym, spell it out on first use on a page. You do not need to spell it out more than once on a page. When possible, try to avoid acronyms in headings. +### Numbers + +When using numbers in text, spell out zero through nine, and use numbers for 10 and greater. For details, see the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/numbers). + ## Text - [Write in Markdown](#markdown). @@ -1626,7 +1615,7 @@ the section. The version information must: - Be surrounded by blank lines. - Start with `>`. If there are multiple bullets, each line must start with `> -`. - The string must include these words in this order (capitalization doesn't matter): - - `introduced`, `deprecated`, `changed`, `moved`, `recommended` (as in the + - `introduced`, `enabled`, `deprecated`, `changed`, `moved`, `recommended` (as in the [feature flag documentation](../feature_flags.md)), `removed`, or `renamed` - `in` or `to` - `GitLab` @@ -1667,24 +1656,6 @@ If a feature is moved to another tier: > - [Moved](<link-to-issue>) from GitLab Premium to GitLab Free in 12.0. ``` -If a feature is deprecated, include a link to a replacement (when available): - -```markdown -> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). -``` - -You can also describe the replacement in surrounding text, if available. If the -deprecation isn't obvious in existing text, you may want to include a warning: - -```markdown -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 @@ -1784,6 +1755,47 @@ 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. +### Deprecated features + +When a feature is deprecated, add `(DEPRECATED)` to the page title or to +the heading of the section documenting the feature, immediately before +the tier badge: + +```markdown +<!-- Page title example: --> +# Feature A (DEPRECATED) **(ALL TIERS)** + +<!-- Doc section example: --> +## Feature B (DEPRECATED) **(PREMIUM SELF)** +``` + +Add the deprecation to the version history note (you can include a link +to a replacement when available): + +```markdown +> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>). +``` + +You can also describe the replacement in surrounding text, if available. If the +deprecation isn't obvious in existing text, you may want to include a warning: + +```markdown +WARNING: +This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by +[Feature name](link-to-feature-documentation). +``` + +If you add `(DEPRECATED)` to the page's title and the document is linked from the docs +navigation, either remove the page from the nav or update the nav item to include the +same text before the feature name: + +```yaml + - doc_title: (DEPRECATED) Feature A +``` + +In the first major GitLab version after the feature was deprecated, be sure to +remove information about that deprecated feature. + ## Products and features Refer to the information in this section when describing products and features diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 9c375379685..dc3dcba0c95 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -25,6 +25,13 @@ Try to avoid **`@mention`**. Say **mention** instead, and consider linking to th [mentions topic](../../../user/discussions/index.md#mentions). Don't use backticks. +## 2FA, two-factor authentication + +Spell out **two-factor authentication** in sentence case for the first use and in section headings, and **2FA** +thereafter. If the first word in a sentence, do not capitalize `factor` or `authentication`. For example: + +- Two-factor authentication (2FA) helps secure your account. Set up 2FA when you first log in. + ## above Try to avoid using **above** when referring to an example or table in a documentation page. If required, use **previous** instead. For example: @@ -182,6 +189,11 @@ Use **check out** as a verb. For the Git command, use `checkout`. CI/CD is always uppercase. No need to spell it out on first use. +## CI/CD minutes + +Use **CI/CD minutes** instead of **CI minutes**, **pipeline minutes**, **pipeline minutes quota**, or +**CI pipeline minutes**. This decision was made in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/342813). + ## click Do not use **click**. Instead, use **select** with buttons, links, menu items, and lists. @@ -197,11 +209,19 @@ Use **confirmation dialog** to describe the dialog box that asks you to confirm - On the confirmation dialog, select **OK**. +## Container Registry + +Use title case for the GitLab Container Registry. + ## currently Do not use **currently** when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) +## Dependency Proxy + +Use title case for the GitLab Dependency Proxy. + ## deploy board Use lowercase for **deploy board**. @@ -614,6 +634,10 @@ When writing about the Owner role: Do not use **Owner permissions**. A user who is assigned the Owner role has a set of associated permissions. +## Package Registry + +Use title case for the GitLab Package Registry. + ## permissions Do not use [**roles**](#roles) and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. @@ -634,6 +658,10 @@ Use **press** when talking about keyboard keys. For example: Do not use profanity. 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). +## push rules + +Use lowercase for **push rules**. + ## Reporter When writing about the Reporter role: @@ -825,6 +853,10 @@ You **turn on** or **turn off** a toggle. For example: - Turn on the **blah** toggle. +## TFA, two-factor authentication + +Use [**2FA** and **two-factor authentication**](#2fa-two-factor-authentication) instead. + ## type Do not use **type** if you can avoid it. Use **enter** instead. diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 13648a7c710..134183a0e75 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -234,15 +234,8 @@ As a general guideline, the lower the score, the more readable the documentation For example, a page that scores `12` before a set of changes, and `9` after, indicates an iterative improvement to readability. The score is not an exact science, but is meant to help indicate the general complexity level of the page. -The readability score is calculated by using the following formula: - -```plaintext -(.39 x ASL) + (11.8 x ASW) – 15.59 -``` - -- `ASL` is average sentence length (the number of words divided by the number of sentences). -- `ASW` is the average number of syllables per word (the number of syllables divided by the number of words). -- The score excludes headings, code blocks, and lists. +The readability score is calculated based on the number of words per sentence, and the number +of syllables per word. For more information, see [the Vale documentation](https://docs.errata.ai/vale/styles#metric). ### Install linters diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 70d7ea7c1a5..9f705f2c6f1 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -23,7 +23,33 @@ when no license is active. So EE features always should be guarded by `project.feature_available?` or `group.licensed_feature_available?` (or `License.feature_available?` if it is a system-wide feature). -Frontend features should be guarded by pushing a flag from the backend by [using `push_licensed_feature`](licensed_feature_availability.md#restricting-frontend-features), and checked using `this.glFeatures.someFeature` in the frontend. +Frontend features should be guarded by pushing a flag from the backend by [using `push_licensed_feature`](licensed_feature_availability.md#restricting-frontend-features), and checked using `this.glFeatures.someFeature` in the frontend. For example: + +```html +<script> +import glFeatureFlagMixin from '~/vue_shared/mixins/gl_feature_flags_mixin'; + +export default { + mixins: [glFeatureFlagMixin()], + components: { + EEComponent: () => import('ee_component/components/test.vue'), + }, + computed: { + shouldRenderComponent() { + return this.glFeatures.myEEFeature; + } + }, +}; +</script> + +<template> + <div> + <ee-component v-if="shouldRenderComponent"/> + </div> +</template> +``` + +Look in `ee/app/models/license.rb` for the names of the licensed features. CE specs should remain untouched as much as possible and extra specs should be added for EE. Licensed features can be stubbed using the diff --git a/doc/development/emails.md b/doc/development/emails.md index f99b914e2de..811619bb0ff 100644 --- a/doc/development/emails.md +++ b/doc/development/emails.md @@ -139,6 +139,44 @@ These are the only valid legacy formats for an email handler: In GitLab, the handler for the Service Desk feature is `path/to/project`. +### MailRoom Gem updates + +We use [`gitlab-mail_room`](https://gitlab.com/gitlab-org/gitlab-mail_room), a +fork of [`MailRoom`](https://github.com/tpitale/mail_room/), to ensure +that we can make updates quickly to the gem if necessary. We try to upstream +changes as soon as possible and keep the two projects in sync. + +Updating the `gitlab-mail_room` dependency in `Gemfile` is deprecated at +the moment in favor of updating the version in +[Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/master/config/software/mail_room.rb) +(see [example merge request](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5816)) +and Helm Chart configuration (see [example merge request](https://gitlab.com/gitlab-org/build/CNG/-/merge_requests/854)). + +#### Rationale + +This was done because to avoid [thread deadlocks](https://github.com/ruby/net-imap/issues/14), `MailRoom` needs +an updated version of the `net-imap` gem. However, this [version of the net-imap cannot be installed by an unprivileged +user](https://github.com/ruby/net-imap/issues/14) due to [an error installing the digest +gem](https://github.com/ruby/digest/issues/14). [This bug in the Ruby interpreter](https://bugs.ruby-lang.org/issues/17761) was fixed in Ruby +3.0.2. + +Updating the gem directly in the GitLab Rails `Gemfile` caused a [production incident](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/4053) +since Kubernetes pods do not run as privileged users. + +Note that Omnibus GitLab runs `/opt/gitlab/embedded/bin/mail_room` +instead of `bundle exec rake` to avoid loading the older version. With a +Kubernetes install, the MailRoom version has always been explicitly set +in the Helm Chart configuration rather than the `Gemfile`. + +#### Preserving backwards compatibility + +Removing the `Gemfile` would break incoming e-mail processing for source +installs. For now, source installs are advised to upgrade manually to +the version specified in Omnibus and run `bin/mail_room` directly as +done with Omnibus. + +We can reconsider this deprecation once we upgrade to Ruby 3.0. + --- [Return to Development documentation](index.md) diff --git a/doc/development/event_store.md b/doc/development/event_store.md new file mode 100644 index 00000000000..7f2b9c86d27 --- /dev/null +++ b/doc/development/event_store.md @@ -0,0 +1,292 @@ +--- +stage: none +group: unassigned +info: To 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 EventStore + +## Background + +The monolithic GitLab project is becoming larger and more domains are being defined. +As a result, these domains are becoming entangled with each others due to temporal coupling. + +An emblematic example is the [`PostReceive`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/workers/post_receive.rb) +worker where a lot happens across multiple domains. If a new behavior reacts to +a new commit being pushed, then we add code somewhere in `PostReceive` or its sub-components +(`Git::ProcessRefChangesService`, for example). + +This type of architecture: + +- Is a violation of the Single Responsibility Principle. +- Increases the risk of adding code to a codebase you are not familiar with. + There may be nuances you don't know about which may introduce bugs or a performance degradation. +- Violates domain boundaries. Inside a specific namespace (for example `Git::`) we suddenly see + classes from other domains chiming in (like `Ci::` or `MergeRequests::`). + +## What is EventStore? + +`Gitlab:EventStore` is a basic pub-sub system built on top of the existing Sidekiq workers and observability we have today. +We use this system to apply an event-driven approach when modeling a domain while keeping coupling +to a minimum. + +This essentially leaves the existing Sidekiq workers as-is to perform asynchronous work but inverts +the dependency. + +### EventStore example + +When a CI pipeline is created we update the head pipeline for any merge request matching the +pipeline's `ref`. The merge request can then display the status of the latest pipeline. + +#### Without the EventStore + +We change `Ci::CreatePipelineService` and add logic (like an `if` statement) to check if the +pipeline is created. Then we schedule a worker to run some side-effects for the `MergeRequests::` domain. + +This style violates the [Open-Closed Principle](https://en.wikipedia.org/wiki/Open%E2%80%93closed_principle) +and unnecessarily add side-effects logic from other domains, increasing coupling: + +```mermaid +graph LR + subgraph ci[CI] + cp[CreatePipelineService] + end + + subgraph mr[MergeRequests] + upw[UpdateHeadPipelineWorker] + end + + subgraph no[Namespaces::Onboarding] + pow[PipelinesOnboardedWorker] + end + + cp -- perform_async --> upw + cp -- perform_async --> pow +``` + +#### With the EventStore + +`Ci::CreatePipelineService` publishes an event `Ci::PipelineCreatedEvent` and its responsibility stops here. + +The `MergeRequests::` domain can subscribe to this event with a worker `MergeRequests::UpdateHeadPipelineWorker`, so: + +- Side-effects are scheduled asynchronously and don't impact the main business transaction that + emits the domain event. +- More side-effects can be added without modifying the main business transaction. +- We can clearly see what domains are involved and their ownership. +- We can identify what events occur in the system because they are explicitly declared. + +With `Gitlab::EventStore` there is still coupling between the subscriber (Sidekiq worker) and the schema of the domain event. +This level of coupling is much smaller than having the main transaction (`Ci::CreatePipelineService`) coupled to: + +- multiple subscribers. +- multiple ways of invoking subscribers (including conditional invocations). +- multiple ways of passing parameters. + +```mermaid +graph LR + subgraph ci[CI] + cp[CreatePipelineService] + cp -- publish --> e[PipelineCreateEvent] + end + + subgraph mr[MergeRequests] + upw[UpdateHeadPipelineWorker] + end + + subgraph no[Namespaces::Onboarding] + pow[PipelinesOnboardedWorker] + end + + upw -. subscribe .-> e + pow -. subscribe .-> e +``` + +Each subscriber, being itself a Sidekiq worker, can specify any attributes that are related +to the type of work they are responsible for. For example, one subscriber could define +`urgency: high` while another one less critical could set `urgency: low`. + +The EventStore is only an abstraction that allows us to have Dependency Inversion. This helps +separating a business transaction from side-effects (often executed in other domains). + +When an event is published, the EventStore calls `perform_async` on each subscribed worker, +passing in the event information as arguments. This essentially schedules a Sidekiq job on each +subscriber's queue. + +This means that nothing else changes with regards to how subscribers work, as they are just +Sidekiq workers. For example: if a worker (subscriber) fails to execute a job, the job is put +back into Sidekiq to be retried. + +## EventStore advantages + +- Subscribers (Sidekiq workers) can be set to run quicker by changing the worker weight + if the side-effect is critical. +- Automatically enforce the fact that side-effects run asynchronously. + This makes it safe for other domains to subscribe to events without affecting the performance of the + main business transaction. + +## Define an event + +An `Event` object represents a domain event that occurred in a bounded context. +Notify other bounded contexts about something +that happened by publishing events, so that they can react to it. + +Define new event classes under `app/events/<namespace>/` with a name representing something that happened in the past: + +```ruby +class Ci::PipelineCreatedEvent < Gitlab::EventStore::Event + def schema + { + 'type' => 'object', + 'required' => ['pipeline_id'], + 'properties' => { + 'pipeline_id' => { 'type' => 'integer' }, + 'ref' => { 'type' => 'string' } + } + } + end +end +``` + +The schema is validated immediately when we initialize the event object so we can ensure that +publishers follow the contract with the subscribers. + +We recommend using optional properties as much as possible, which require fewer rollouts for schema changes. +However, `required` properties could be used for unique identifiers of the event's subject. For example: + +- `pipeline_id` can be a required property for a `Ci::PipelineCreatedEvent`. +- `project_id` can be a required property for a `Projects::ProjectDeletedEvent`. + +Publish only properties that are needed by the subscribers without tailoring the payload to specific subscribers. +The payload should fully represent the event and not contain loosely related properties. For example: + +```ruby +Ci::PipelineCreatedEvent.new(data: { + pipeline_id: pipeline.id, + # unless all subscribers need merge request IDs, + # this is data that can be fetched by the subscriber. + merge_request_ids: pipeline.all_merge_requests.pluck(:id) +}) +``` + +Publishing events with more properties provides the subscribers with the data +they need in the first place. Otherwise subscribers have to fetch the additional data from the database. +However, this can lead to continuous changes to the schema and possibly adding properties that may not +represent the single source of truth. +It's best to use this technique as a performance optimization. For example: when an event has many +subscribers that all fetch the same data again from the database. + +### Update the schema + +Changes to the schema require multiple rollouts. While the new version is being deployed: + +- Existing publishers can publish events using the old version. +- Existing subscribers can consume events using the old version. +- Events get persisted in the Sidekiq queue as job arguments, so we could have 2 versions of the schema during deployments. + +As changing the schema ultimately impacts the Sidekiq arguments, please refer to our +[Sidekiq style guide](sidekiq_style_guide.md#changing-the-arguments-for-a-worker) with regards to multiple rollouts. + +#### Add properties + +1. Rollout 1: + - Add new properties as optional (not `required`). + - Update the subscriber so it can consume events with and without the new properties. +1. Rollout 2: + - Change the publisher to provide the new property +1. Rollout 3: (if the property should be `required`): + - Change the schema and the subscriber code to always expect it. + +#### Remove properties + +1. Rollout 1: + - If the property is `required`, make it optional. + - Update the subscriber so it does not always expect the property. +1. Rollout 2: + - Remove the property from the event publishing. + - Remove the code from the subscriber that processes the property. + +#### Other changes + +For other changes, like renaming a property, use the same steps: + +1. Remove the old property +1. Add the new property + +## Publish an event + +To publish the event from the [previous example](#define-an-event): + +```ruby +Gitlab::EventStore.publish( + Ci::PipelineCreatedEvent.new(data: { pipeline_id: pipeline.id }) +) +``` + +## Create a subscriber + +A subscriber is a Sidekiq worker that includes the `Gitlab::EventStore::Subscriber` module. +This module takes care of the `perform` method and provides a better abstraction to handle +the event safely via the `handle_event` method. For example: + +```ruby +module MergeRequests + class UpdateHeadPipelineWorker + include ApplicationWorker + include Gitlab::EventStore::Subscriber + + def handle_event(event) + Ci::Pipeline.find_by_id(event.data[:pipeline_id]).try do |pipeline| + # ... + end + end + end +end +``` + +## Register the subscriber to the event + +To subscribe the worker to a specific event in `lib/gitlab/event_store.rb`, +add a line like this to the `Gitlab::EventStore.configure!` method: + +```ruby +module Gitlab + module EventStore + def self.configure! + Store.new.tap do |store| + # ... + + store.subscribe ::MergeRequests::UpdateHeadPipelineWorker, to: ::Ci::PipelineCreatedEvent + + # ... + end + end + end +end +``` + +Subscriptions are stored in memory when the Rails app is loaded and they are immediately frozen. +It's not possible to modify subscriptions at runtime. + +### Conditional dispatch of events + +A subscription can specify a condition when to accept an event: + +```ruby +store.subscribe ::MergeRequests::UpdateHeadPipelineWorker, + to: ::Ci::PipelineCreatedEvent, + if: -> (event) { event.data[:merge_request_id].present? } +``` + +This tells the event store to dispatch `Ci::PipelineCreatedEvent`s to the subscriber if +the condition is met. + +This technique can avoid scheduling Sidekiq jobs if the subscriber is interested in a +small subset of events. + +WARNING: +When using conditional dispatch it must contain only cheap conditions because they are +executed synchronously every time the given event is published. + +For complex conditions it's best to subscribe to all the events and then handle the logic +in the `handle_event` method of the subscriber worker. diff --git a/doc/development/experiment_guide/experimentation.md b/doc/development/experiment_guide/experimentation.md index b242646c549..bb782af80cc 100644 --- a/doc/development/experiment_guide/experimentation.md +++ b/doc/development/experiment_guide/experimentation.md @@ -1,402 +1,9 @@ --- -stage: Growth -group: Activation -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'gitlab_experiment.md' +remove_date: '2022-04-13' --- -# Create an A/B test with `Experimentation Module` +This document was moved to [another location](gitlab_experiment.md). -NOTE: -We recommend using [GLEX](gitlab_experiment.md) for new experiments. - -## Implement the experiment - -1. Add the experiment to the `Gitlab::Experimentation::EXPERIMENTS` hash in - [`experimentation.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib%2Fgitlab%2Fexperimentation.rb): - - ```ruby - EXPERIMENTS = { - other_experiment: { - #... - }, - # Add your experiment here: - signup_flow: { - tracking_category: 'Growth::Activation::Experiment::SignUpFlow' # Used for providing the category when setting up tracking data - } - }.freeze - ``` - -1. Use the experiment in the code. - - Experiments can be performed on a `subject`. The provided `subject` should - respond to `to_global_id` or `to_s`. - The resulting string is bucketed and assigned to either the control or the - experimental group, so you must always provide the same `subject` - for an experiment to have the same experience. - - 1. Use this standard for the experiment in a controller: - - - 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 - ``` - - - 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 - ``` - - 1. Make the experiment available to the frontend in a controller. This example - checks whether the experiment is enabled and pushes the result to the frontend: - - ```ruby - before_action do - push_frontend_experiment(:signup_flow, subject: current_user) - end - ``` - - You can check the state of the feature flag in JavaScript: - - ```javascript - import { isExperimentEnabled } from '~/experimentation'; - - if ( isExperimentEnabled('signupFlow') ) { - // ... - } - ``` - -You can also run an experiment outside of the controller scope, such as in a worker: - -```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 necessary 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 tracking events - -To determine whether the experiment is a success or not, we must implement tracking events -to acquire data for analyzing. We can send events to Snowplow via either the backend or frontend. -Read the [product intelligence guide](https://about.gitlab.com/handbook/product/product-intelligence-guide/) for more details. - -### Track backend events - -The framework provides a helper method that is available in controllers: - -```ruby -before_action do - track_experiment_event(:signup_flow, 'action', 'value', subject: current_user) -end -``` - -To test it: - -```ruby -context 'when the experiment is active and the user is in the experimental group' do - before do - stub_experiment(signup_flow: true) - stub_experiment_for_subject(signup_flow: true) - end - - it 'tracks an event', :snowplow do - subject - - expect_snowplow_event( - category: 'Growth::Activation::Experiment::SignUpFlow', - action: 'action', - value: 'value', - label: 'experimentation_subject_id', - property: 'experimental_group' - ) - end -end -``` - -### Track frontend events - -The framework provides a helper method that is available in controllers: - -```ruby -before_action do - push_frontend_experiment(:signup_flow, subject: current_user) - frontend_experimentation_tracking_data(:signup_flow, 'action', 'value', subject: current_user) -end -``` - -This pushes tracking data to `gon.experiments` and `gon.tracking_data`. - -```ruby -expect(Gon.experiments['signupFlow']).to eq(true) - -expect(Gon.tracking_data).to eq( - { - category: 'Growth::Activation::Experiment::SignUpFlow', - action: 'action', - value: 'value', - label: 'experimentation_subject_id', - property: 'experimental_group' - } -) -``` - -To track it: - -```javascript -import { isExperimentEnabled } from '~/lib/utils/experimentation'; -import Tracking from '~/tracking'; - -document.addEventListener('DOMContentLoaded', () => { - const signupFlowExperimentEnabled = isExperimentEnabled('signupFlow'); - - if (signupFlowExperimentEnabled && gon.tracking_data) { - const { category, action, ...data } = gon.tracking_data; - - Tracking.event(category, action, data); - } -} -``` - -To test it in Jest: - -```javascript -import { withGonExperiment } from 'helpers/experimentation_helper'; -import Tracking from '~/tracking'; - -describe('event tracking', () => { - describe('with tracking data', () => { - withGonExperiment('signupFlow'); - - beforeEach(() => { - jest.spyOn(Tracking, 'event').mockImplementation(() => {}); - - gon.tracking_data = { - category: 'Growth::Activation::Experiment::SignUpFlow', - action: 'action', - value: 'value', - label: 'experimentation_subject_id', - property: 'experimental_group' - }; - }); - - it('should track data', () => { - performAction() - - expect(Tracking.event).toHaveBeenCalledWith( - 'Growth::Activation::Experiment::SignUpFlow', - 'action', - { - value: 'value', - label: 'experimentation_subject_id', - property: 'experimental_group' - }, - ); - }); - }); -}); -``` - -## 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 is then enrolled into a different experience. This happens -when we roll out the experimental experience to a greater percentage of users. - -This data is completely separate from the [events tracking data](#implement-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. New calls to the `record_experiment_user` with newer contexts are merged -deeply into the existing context. - -This data can then be used by data analytics dashboards. - -```ruby -before_action do - record_experiment_user(:signup_flow, foo: 42, bar: { a: 22}) - # context is { "foo" => 42, "bar" => { "a" => 22 }} -end - -# Additional contexts for newer record calls are merged deeply -record_experiment_user(:signup_flow, foo: 40, bar: { b: 2 }, thor: 3) -# context becomes { "foo" => 40, "bar" => { "a" => 22, "b" => 2 }, "thor" => 3} -``` - -## 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 test if the change 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. -Use it to record the conversion event for the current user, regardless of whether -the user is 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](#record-experiment-user) as being part of the experiment. - -## Enable the experiment - -After all merge requests have been merged, use [ChatOps](../../ci/chatops/index.md) in the -[appropriate channel](../feature_flags/controls.md#communicate-the-change) to start the experiment for 10% of the users. -The feature flag should have the name of the experiment with the `_experiment_percentage` suffix appended. -For visibility, share any commands run against production in the `#s_growth` channel: - - ```shell - /chatops run feature set signup_flow_experiment_percentage 10 - ``` - - If you notice issues with the experiment, you can disable the experiment by removing the feature flag: - - ```shell - /chatops run feature delete signup_flow_experiment_percentage - ``` - -## Add user to experiment group manually - -To force the application to add your current user into the experiment group, -add a query string parameter to the path where the experiment runs. If you add the -query string parameter, the experiment works only for this request, and doesn'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> -``` - -## Add user to experiment group with a cookie - -You can force the current user into the experiment group for `<EXPERIMENT_KEY>` -during the browser session by using your browser's developer tools: - -```javascript -document.cookie = "force_experiment=<EXPERIMENT_KEY>; path=/"; -``` - -Use a comma to list more than one experiment to be forced: - -```javascript -document.cookie = "force_experiment=<EXPERIMENT_KEY>,<ANOTHER_EXPERIMENT_KEY>; path=/"; -``` - -To clear the experiments, unset the `force_experiment` cookie: - -```javascript -document.cookie = "force_experiment=; path=/"; -``` - -## Testing and test helpers - -### RSpec - -Use the following in RSpec to mock the experiment: - -```ruby -context 'when the experiment is active' do - before do - stub_experiment(signup_flow: true) - end - - context 'when the user is in the experimental group' do - before do - stub_experiment_for_subject(signup_flow: true) - end - - it { is_expected.to do_experimental_thing } - end - - context 'when the user is in the control group' do - before do - stub_experiment_for_subject(signup_flow: false) - end - - it { is_expected.to do_control_thing } - end -end -``` - -### Jest - -Use the following in Jest to mock the experiment: - -```javascript -import { withGonExperiment } from 'helpers/experimentation_helper'; - -describe('given experiment is enabled', () => { - withGonExperiment('signupFlow'); - - it('should do the experimental thing', () => { - expect(wrapper.find('.js-some-experiment-triggered-element')).toEqual(expect.any(Element)); - }); -}); -``` +<!-- This redirect file can be deleted after <2022-04-13>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/experiment_guide/gitlab_experiment.md b/doc/development/experiment_guide/gitlab_experiment.md index 288823bb41f..36d2a4f6fbf 100644 --- a/doc/development/experiment_guide/gitlab_experiment.md +++ b/doc/development/experiment_guide/gitlab_experiment.md @@ -71,6 +71,8 @@ class Cached cached ## Implement an experiment +[Examples](https://gitlab.com/gitlab-org/growth/growth/-/wikis/GLEX-Framework-code-examples) + Start by generating a feature flag using the `bin/feature-flag` command as you normally would for a development feature flag, making sure to use `experiment` for the type. For the sake of documentation let's name our feature flag (and experiment) diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 9937cb2ebd1..8d62f92e0b9 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -48,10 +48,7 @@ If the experiment is successful and becomes part of the product, any items that For more information, see [Implementing an A/B/n experiment using GLEX](gitlab_experiment.md). -There are still some longer running experiments using the [`Exerimentation Module`](experimentation.md). - -Both approaches use [experiment](../feature_flags/index.md#experiment-type) feature flags. -`GLEX` is the preferred option for new experiments. +This uses [experiment](../feature_flags/index.md#experiment-type) feature flags. ### Add new icons and illustrations for experiments diff --git a/doc/development/fe_guide/style/javascript.md b/doc/development/fe_guide/style/javascript.md index a2035eb1b55..f22e3ea6395 100644 --- a/doc/development/fe_guide/style/javascript.md +++ b/doc/development/fe_guide/style/javascript.md @@ -189,24 +189,6 @@ are loaded dynamically with webpack. Do not use `innerHTML`, `append()` or `html()` to set content. It opens up too many vulnerabilities. -## Avoid single-line conditional statements - -Indentation is important when scanning code as it gives a quick indication of the existence of branches, loops, and return points. -This can help to quickly understand the control flow. - -```javascript -// bad -if (isThingNull) return ''; - -if (isThingNull) - return ''; - -// good -if (isThingNull) { - return ''; -} -``` - ## ESLint ESLint behavior can be found in our [tooling guide](../tooling.md). diff --git a/doc/development/fe_guide/vue3_migration.md b/doc/development/fe_guide/vue3_migration.md index 2b783eb21b7..6e994d5e95d 100644 --- a/doc/development/fe_guide/vue3_migration.md +++ b/doc/development/fe_guide/vue3_migration.md @@ -37,32 +37,8 @@ If you need cross-component communication (between different Vue apps), then per **What to use instead** -Vue documentation recommends using the [mitt](https://github.com/developit/mitt) library. It's relatively small (200 bytes, compressed) and has a clear API: +We have created a factory that you can use to instantiate a new [mitt](https://github.com/developit/mitt)-like event hub. -```javascript -import mitt from 'mitt' - -const emitter = mitt() - -// listen to an event -emitter.on('foo', e => console.log('foo', e) ) - -// listen to all events -emitter.on('*', (type, e) => console.log(type, e) ) - -// fire an event -emitter.emit('foo', { a: 'b' }) - -// working with handler references: -function onFoo() {} - -emitter.on('foo', onFoo) // listen -emitter.off('foo', onFoo) // unlisten -``` - -**Event hub factory** - -We have created a factory that you can use to instantiate a new mitt-based event hub. This makes it easier to migrate existing event hubs to the new recommended approach, or to create new ones. diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index 4843b58c3fd..6bf5be23ace 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -69,7 +69,7 @@ Slack channel for the stage the feature is relevant to. For example, use the `#s_monitor` channel for features developed by the Monitor stage, Health group. -To enable a feature for 25% of all users, run the following in Slack: +To enable a feature for 25% of the time, run the following in Slack: ```shell /chatops run feature set new_navigation_bar 25 --dev @@ -303,6 +303,19 @@ and reduces confidence in our testing suite covering all possible combinations. Additionally, a feature flag overwritten in some of the environments can result in undefined and untested system behavior. +`development` type feature flags should have a short life-cycle because their purpose +is for rolling out a persistent change. `development` feature flags that are older +than 2 milestones are reported to engineering managers. The +[report tool](https://gitlab.com/gitlab-org/gitlab-feature-flag-alert) runs on a +monthly basis. For example, see [the report for December 2021](https://gitlab.com/gitlab-org/quality/triage-reports/-/issues/5480). + +If a `development` feature flag is still present in the codebase after 6 months we should +take one of the following actions: + +- Enable the feature flag by default and remove it. +- Convert it to an instance, group, or project setting. +- Revert the changes if it's still disabled and not needed anymore. + To remove a feature flag, open **one merge request** to make the changes. In the MR: 1. Add the ~"feature flag" label so release managers are aware the changes are hidden behind a feature flag. diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 86dc4c73062..820b4bab802 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -171,6 +171,7 @@ 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. | +| `milestone` | no | Milestone in which the feature was added. | | `group` | no | The [group](https://about.gitlab.com/handbook/product/categories/#devops-stages) that owns the feature flag. | NOTE: diff --git a/doc/development/features_inside_dot_gitlab.md b/doc/development/features_inside_dot_gitlab.md index 3a9decaad69..73ba9cbd674 100644 --- a/doc/development/features_inside_dot_gitlab.md +++ b/doc/development/features_inside_dot_gitlab.md @@ -16,7 +16,7 @@ When implementing new features, please refer to these existing features to avoid - [CODEOWNERS](../user/project/code_owners.md#set-up-code-owners): `.gitlab/CODEOWNERS`. - [Route Maps](../ci/review_apps/#route-maps): `.gitlab/route-map.yml`. - [Customize Auto DevOps Helm Values](../topics/autodevops/customize.md#customize-values-for-helm-chart): `.gitlab/auto-deploy-values.yaml`. -- [GitLab managed apps CI/CD](../user/clusters/applications.md#usage): `.gitlab/managed-apps/config.yaml`. +- [GitLab managed apps CI/CD](../user/clusters/applications.md#prerequisites): `.gitlab/managed-apps/config.yaml`. - [Insights](../user/project/insights/index.md#configure-your-insights): `.gitlab/insights.yml`. - [Service Desk Templates](../user/project/service_desk.md#using-customized-email-templates): `.gitlab/service_desk_templates/`. - [Web IDE](../user/project/web_ide/#web-ide-configuration-file): `.gitlab/.gitlab-webide.yml`. diff --git a/doc/development/geo.md b/doc/development/geo.md index 7d5aae49749..9f5fd674d38 100644 --- a/doc/development/geo.md +++ b/doc/development/geo.md @@ -7,8 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Geo (development) **(PREMIUM SELF)** Geo connects GitLab instances together. One GitLab instance is -designated as a **primary** node and can be run with multiple -**secondary** nodes. Geo orchestrates quite a few components that can be seen on +designated as a **primary** site and can be run with multiple +**secondary** sites. Geo orchestrates quite a few components that can be seen on the diagram below and are described in more detail within this document.  @@ -22,16 +22,16 @@ Geo handles replication for different components: - [Uploaded blobs](#uploads-replication): includes anything from images attached on issues to raw logs and assets from CI. -With the exception of the Database replication, on a *secondary* node, everything is coordinated +With the exception of the Database replication, on a *secondary* site, everything is coordinated by the [Geo Log Cursor](#geo-log-cursor). ### Geo Log Cursor daemon The [Geo Log Cursor daemon](#geo-log-cursor-daemon) is a separate process running on -each **secondary** node. It monitors the [Geo Event Log](#geo-event-log) +each **secondary** site. It monitors the [Geo Event Log](#geo-event-log) for new events and creates background jobs for each specific event type. -For example when a repository is updated, the Geo **primary** node creates +For example when a repository is updated, the Geo **primary** site creates a Geo event with an associated repository updated event. The Geo Log Cursor daemon picks the event up and schedules a `Geo::ProjectSyncWorker` job which will use the `Geo::RepositorySyncService` and `Geo::WikiSyncService` classes @@ -41,7 +41,7 @@ The Geo Log Cursor daemon can operate in High Availability mode automatically. The daemon will try to acquire a lock from time to time and once acquired, it will behave as the *active* daemon. -Any additional running daemons on the same node, will be in standby +Any additional running daemons on the same site, will be in standby mode, ready to resume work if the *active* daemon releases its lock. We use the [`ExclusiveLease`](https://www.rubydoc.info/github/gitlabhq/gitlabhq/Gitlab/ExclusiveLease) lock type with a small TTL, that is renewed at every @@ -53,14 +53,14 @@ the lock, it switches to standby mode. ### Database replication Geo uses [streaming replication](#streaming-replication) to replicate -the database from the **primary** to the **secondary** nodes. This -replication gives the **secondary** nodes access to all the data saved +the database from the **primary** to the **secondary** sites. This +replication gives the **secondary** sites access to all the data saved in the database. So users can log in on the **secondary** and read all -the issues, merge requests, and so on, on the **secondary** node. +the issues, merge requests, and so on, on the **secondary** site. ### Repository replication -Geo also replicates repositories. Each **secondary** node keeps track of +Geo also replicates repositories. Each **secondary** site keeps track of the state of every repository in the [tracking database](#tracking-database). There are a few ways a repository gets replicated by the: @@ -92,7 +92,7 @@ background and it searches the `Geo::ProjectRegistry` model for projects that need updating. Those projects can be: - Unsynced: Projects that have never been synced on the **secondary** - node and so do not exist yet. + site and so do not exist yet. - Updated recently: Projects that have a `last_repository_updated_at` timestamp that is more recent than the `last_repository_successful_sync_at` timestamp in the `Geo::ProjectRegistry` model. @@ -106,7 +106,7 @@ it's successful, we replace the main repository with the newly cloned one. ### Uploads replication -File uploads are also being replicated to the **secondary** node. To +File uploads are also being replicated to the **secondary** site. To track the state of syncing, the `Geo::UploadRegistry` model is used. #### Upload Registry @@ -123,7 +123,7 @@ models respectively. Also similar to the [Repository Sync worker](#repository-sync-worker), there is a `Geo::FileDownloadDispatchWorker` class that is run periodically to sync all uploads that aren't synced to the Geo -**secondary** node yet. +**secondary** site yet. Files are copied via HTTP(s) and initiated via the `/api/v4/geo/transfers/:type/:id` endpoint, @@ -136,18 +136,18 @@ To authenticate file transfers, each `GeoNode` record has two fields: - A public access key (`access_key` field). - A secret access key (`secret_access_key` field). -The **secondary** node authenticates itself via a [JWT request](https://jwt.io/). -When the **secondary** node wishes to download a file, it sends an +The **secondary** site authenticates itself via a [JWT request](https://jwt.io/). +When the **secondary** site wishes to download a file, it sends an HTTP request with the `Authorization` header: ```plaintext Authorization: GL-Geo <access_key>:<JWT payload> ``` -The **primary** node uses the `access_key` field to look up the -corresponding **secondary** node and decrypts the JWT payload, +The **primary** site uses the `access_key` field to look up the +corresponding **secondary** site and decrypts the JWT payload, which contains additional information to identify the file -request. This ensures that the **secondary** node downloads the right +request. This ensures that the **secondary** site downloads the right file for the right database ID. For example, for an LFS object, the request must also include the SHA256 sum of the file. An example JWT payload looks like: @@ -157,7 +157,7 @@ payload looks like: ``` If the requested file matches the requested SHA256 sum, then the Geo -**primary** node sends data via the [X-Sendfile](https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/) +**primary** site sends data via the [X-Sendfile](https://www.nginx.com/resources/wiki/start/topics/examples/xsendfile/) feature, which allows NGINX to handle the file transfer without tying up Rails or Workhorse. @@ -168,34 +168,34 @@ involved, otherwise it may fail with an encryption error. ## Git Push to Geo secondary The Git Push Proxy exists as a functionality built inside the `gitlab-shell` component. -It is active on a **secondary** node only. It allows the user that has cloned a repository -from the secondary node to push to the same URL. +It is active on a **secondary** site only. It allows the user that has cloned a repository +from the secondary site to push to the same URL. -Git `push` requests directed to a **secondary** node will be sent over to the **primary** node, -while `pull` requests will continue to be served by the **secondary** node for maximum efficiency. +Git `push` requests directed to a **secondary** site will be sent over to the **primary** site, +while `pull` requests will continue to be served by the **secondary** site for maximum efficiency. HTTPS and SSH requests are handled differently: -- With HTTPS, we will give the user a `HTTP 302 Redirect` pointing to the project on the **primary** node. +- With HTTPS, we will give the user a `HTTP 302 Redirect` pointing to the project on the **primary** site. The Git client is wise enough to understand that status code and process the redirection. - With SSH, because there is no equivalent way to perform a redirect, we have to proxy the request. This is done inside [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell), by first translating the request - to the HTTP protocol, and then proxying it to the **primary** node. + to the HTTP protocol, and then proxying it to the **primary** site. The [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell) daemon knows when to proxy based on the response from `/api/v4/allowed`. A special `HTTP 300` status code is returned and we execute a "custom action", specified in the response body. The response contains additional data that allows the proxied `push` operation -to happen on the **primary** node. +to happen on the **primary** site. ## Using the Tracking Database Along with the main database that is replicated, a Geo **secondary** -node has its own separate [Tracking database](#tracking-database). +site has its own separate [Tracking database](#tracking-database). -The tracking database contains the state of the **secondary** node. +The tracking database contains the state of the **secondary** site. Any database migration that needs to be run as part of an upgrade -needs to be applied to the tracking database on each **secondary** node. +needs to be applied to the tracking database on each **secondary** site. ### Configuration @@ -223,12 +223,12 @@ projects/attachments/ and so on, in the tracking database and main database. ## Redis -Redis on the **secondary** node works the same as on the **primary** -node. It is used for caching, storing sessions, and other persistent +Redis on the **secondary** site works the same as on the **primary** +site. It is used for caching, storing sessions, and other persistent data. -Redis data replication between **primary** and **secondary** node is -not used, so sessions and so on, aren't shared between nodes. +Redis data replication between **primary** and **secondary** site is +not used, so sessions and so on, aren't shared between sites. ## Object Storage @@ -244,7 +244,7 @@ ignores items in object storage. Either: - The object storage layer should take care of its own geographical replication. -- All secondary nodes should use the same storage node. +- All secondary sites should use the same storage site. ## Verification @@ -252,29 +252,29 @@ ignores items in object storage. Either: Repositories are verified with a checksum. -The **primary** node calculates a checksum on the repository. It +The **primary** site calculates a checksum on the repository. It basically hashes all Git refs together and stores that hash in the `project_repository_states` table of the database. -The **secondary** node does the same to calculate the hash of its -clone, and compares the hash with the value the **primary** node +The **secondary** site does the same to calculate the hash of its +clone, and compares the hash with the value the **primary** site calculated. If there is a mismatch, Geo will mark this as a mismatch and the administrator can see this in the [Geo admin panel](../user/admin_area/geo_nodes.md). ## Glossary -### Primary node +### Primary site -A **primary** node is the single node in a Geo setup that read-write +A **primary** site is the single site in a Geo setup that read-write capabilities. It's the single source of truth and the Geo -**secondary** nodes replicate their data from there. +**secondary** sites replicate their data from there. -In a Geo setup, there can only be one **primary** node. All -**secondary** nodes connect to that **primary**. +In a Geo setup, there can only be one **primary** site. All +**secondary** sites connect to that **primary**. -### Secondary node +### Secondary site -A **secondary** node is a read-only replica of the **primary** node +A **secondary** site is a read-only replica of the **primary** site running in a different geographical location. ### Streaming replication @@ -287,11 +287,11 @@ Streaming replication depends on the Write Ahead Logs, or WAL. Those logs are copied over to the replica and replayed there. Since streaming replication also replicates the schema, the database -migration do not need to run on the secondary nodes. +migration do not need to run on the secondary sites. ### Tracking database -A database on each Geo **secondary** node that keeps state for the node +A database on each Geo **secondary** site that keeps state for the site on which it resides. Read more in [Using the Tracking database](#using-the-tracking-database). ## Geo Event Log @@ -312,7 +312,7 @@ events include: ### Geo Log Cursor -The process running on the **secondary** node that looks for new +The process running on the **secondary** site that looks for new `Geo::EventLog` rows. ## Code features @@ -327,51 +327,51 @@ Many of these methods are cached using the `RequestStore` class, to reduce the performance impact of using the methods throughout the codebase. -#### Current node +#### Current site The class method `.current_node` returns the `GeoNode` record for the -current node. +current site. We use the `host`, `port`, and `relative_url_root` values from -`gitlab.yml` and search in the database to identify which node we are +`gitlab.yml` and search in the database to identify which site we are in (see `GeoNode.current_node`). #### Primary or secondary -To determine whether the current node is a **primary** node or a -**secondary** node use the `.primary?` and `.secondary?` class +To determine whether the current site is a **primary** site or a +**secondary** site use the `.primary?` and `.secondary?` class methods. -It is possible for these methods to both return `false` on a node when -the node is not enabled. See [Enablement](#enablement). +It is possible for these methods to both return `false` on a site when +the site is not enabled. See [Enablement](#enablement). #### Geo Database configured? There is also an additional gotcha when dealing with things that happen during initialization time. In a few places, we use the -`Gitlab::Geo.geo_database_configured?` method to check if the node has +`Gitlab::Geo.geo_database_configured?` method to check if the site has the tracking database, which only exists on the **secondary** -node. This overcomes race conditions that could happen during -bootstrapping of a new node. +site. This overcomes race conditions that could happen during +bootstrapping of a new site. #### Enablement We consider Geo feature enabled when the user has a valid license with the -feature included, and they have at least one node defined at the Geo Nodes +feature included, and they have at least one site defined at the Geo Nodes screen. See `Gitlab::Geo.enabled?` and `Gitlab::Geo.license_allows?` methods. #### Read-only -All Geo **secondary** nodes are read-only. +All Geo **secondary** sites are read-only. The general principle of a [read-only database](verifying_database_capabilities.md#read-only-database) -applies to all Geo **secondary** nodes. So the +applies to all Geo **secondary** sites. So the `Gitlab::Database.read_only?` method will always return `true` on a -**secondary** node. +**secondary** site. -When some write actions are not allowed because the node is a +When some write actions are not allowed because the site is a **secondary**, consider adding the `Gitlab::Database.read_only?` or `Gitlab::Database.read_write?` guard, instead of `Gitlab::Geo.secondary?`. @@ -393,7 +393,7 @@ that need to be taken care of: - Verification. - Cleaner. When sync settings are changed for the secondary site, some resources need to be cleaned up. - Geo Node Status. We need to provide API endpoints as well as some presentation in the GitLab Admin Area. -- Health Check. If we can perform some pre-cheсks and make node unhealthy if something is wrong, we should do that. +- Health Check. If we can perform some pre-cheсks and make site unhealthy if something is wrong, we should do that. The `rake gitlab:geo:check` command has to be updated too. ## History of communication channel @@ -404,7 +404,7 @@ check here historic decisions and why we moved to new implementations. ### Custom code (GitLab 8.6 and earlier) In GitLab versions before 8.6, custom code is used to handle -notification from **primary** node to **secondary** nodes by HTTP +notification from **primary** site to **secondary** sites by HTTP requests. ### System hooks (GitLab 8.7 to 9.5) diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md index 4460e6f66a8..778387986d8 100644 --- a/doc/development/geo/framework.md +++ b/doc/development/geo/framework.md @@ -14,7 +14,7 @@ team to discuss the options. You can contact them in `#g_geo` on Slack or mention `@geo-team` in the issue or merge request. Geo provides an API to make it possible to easily replicate data types -across Geo nodes. This API is presented as a Ruby Domain-Specific +across Geo sites. This API is presented as a Ruby Domain-Specific Language (DSL) and aims to make it possible to replicate data with minimal effort of the engineer who created a data type. @@ -43,7 +43,7 @@ naming conventions: For more detail, see [Data types](../../administration/geo/replication/datatypes.md). - **Geo Replicable**: - A Replicable is a resource Geo wants to sync across Geo nodes. There + A Replicable is a resource Geo wants to sync across Geo sites. There is a limited set of supported data types of replicables. The effort required to implement replication of a resource that belongs to one of the known data types is minimal. @@ -57,7 +57,7 @@ naming conventions: It's tied to the Geo Replicable data type. All replicators have a common interface that can be used to process (that is, produce and consume) events. It takes care of the communication between the - primary node (where events are produced) and the secondary node + primary site (where events are produced) and the secondary site (where events are consumed). The engineer who wants to incorporate Geo in their feature will use the API of replicators to make this happen. @@ -117,7 +117,7 @@ the model code: ```ruby class Packages::PackageFile < ApplicationRecord - include ::Gitlab::Geo::ReplicableModel + include ::Geo::ReplicableModel with_replicator Geo::PackageFileReplicator end diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 5a7a5a6abcb..275e9421983 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -112,10 +112,9 @@ bundle exec rake gitlab:features:disable_rugged Most of this code exists in the `lib/gitlab/git/rugged_impl` directory. 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 does -NOT work on GitLab.com or other GitLab instances that do not use NFS. +You should *not* have 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 does not work on GitLab.com or other GitLab +instances that do not use NFS. ## `TooManyInvocationsError` errors @@ -197,7 +196,7 @@ If you make changes to your local Gitaly in between test runs you need to manually run `make` again. 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. To use a custom Gitaly version in CI, you must update GITALY_SERVER_VERSION as described at the beginning of this section. To use a different Gitaly repository, such as if your changes are present @@ -326,7 +325,7 @@ default value. The default value depends on the GitLab version. To be sure that the flag is set correctly and it goes into Gitaly, you can check the integration by using GDK: -1. The state of the flag must be observable. To check it, you need to enable it +1. The state of the flag must be observable. To check it, you must enable it by fetching the Prometheus metrics: 1. Navigate to GDK's root directory. 1. Make sure you have the proper branch checked out for Gitaly. diff --git a/doc/development/import_project.md b/doc/development/import_project.md index 9872aa239dc..9e236b4cfce 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.md @@ -16,7 +16,7 @@ There are several ways to import a project. ### Importing via UI -The first option is to simply [import the Project tarball file via the GitLab UI](../user/project/settings/import_export.md#import-the-project): +The first option is to simply [import the Project tarball file via the GitLab UI](../user/project/settings/import_export.md#import-a-project-and-its-data): 1. Create the group `qa-perf-testing` 1. Import the [GitLab FOSS project tarball](https://gitlab.com/gitlab-org/quality/performance-data/-/blob/master/projects_export/gitlabhq_export.tar.gz) into the Group. diff --git a/doc/development/index.md b/doc/development/index.md index 1398104abda..197c7f48398 100644 --- a/doc/development/index.md +++ b/doc/development/index.md @@ -164,6 +164,7 @@ the [reviewer values](https://about.gitlab.com/handbook/engineering/workflow/rev ### General - [Directory structure](directory_structure.md) +- [GitLab EventStore](event_store.md) to publish/subscribe to domain events - [GitLab utilities](utilities.md) - [Newlines style guide](newlines_styleguide.md) - [Logging](logging.md) @@ -263,8 +264,7 @@ the [reviewer values](https://about.gitlab.com/handbook/engineering/workflow/rev - [Caching guidelines](caching.md) for using caching in Rails under a GitLab environment. - [Merge request performance guidelines](merge_request_performance_guidelines.md) for ensuring merge requests do not negatively impact GitLab performance -- [Profiling](profiling.md) a URL, measuring performance using Sherlock, or - tracking down N+1 queries using Bullet. +- [Profiling](profiling.md) a URL 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. diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index 3987c6658c3..8a3f64f0a0d 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -54,8 +54,8 @@ To set up the Jenkins project you intend to run your build on, read You can configure your integration between Jenkins and GitLab: -- With the [recommended approach for Jenkins integration](../../integration/jenkins.md#recommended-jenkins-integration). -- [Using a webhook](../../integration/jenkins.md#webhook-integration). +- With the [recommended approach for Jenkins integration](../../integration/jenkins.md#configure-a-jenkins-integration-recommended). +- [Using a webhook](../../integration/jenkins.md#configure-a-webhook). ## Test your setup diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index ca3dc3660ee..fc7204fdd5a 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -89,6 +89,3 @@ To add a [namespace](../../user/group/index.md#namespaces) to Jira: `--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 356e731aa87..147d379cec7 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -327,21 +327,42 @@ You can find the schemas for these scanners here: - [Coverage Fuzzing](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json) - [Secret Detection](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/secret-detection-report-format.json) -### Version +### Enable report validation -This field specifies the version of the [Security Report Schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas) you are using. Please refer to the [releases](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) of the schemas for the specific versions to use. +In GitLab 14.10 and later, report validation against the schemas is enabled. To enable report validation for versions earlier than 14.10, +set [`VALIDATE_SCHEMA`](../../user/application_security/#enable-security-report-validation) to +`"true"`. -### Vulnerabilities +Reports that don't pass validation are not ingested by GitLab, and an error message +displays on the corresponding pipeline. + +You should ensure that reports generated by the scanner pass validation against the schema version +declared in your reports. GitLab uses the +[`json_schemer`](https://www.rubydoc.info/gems/json_schemer) gem to perform validation. + +Ongoing improvements to report validation is tracked [in this epic](https://gitlab.com/groups/gitlab-org/-/epics/6968). + +### Report Fields + +#### Version + +This field specifies which [Security Report Schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas) version you are using. For information about the versions to use, see [releases](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases). + +In GitLab 14.10 and later, GitLab validates your report against the version of the schema specified by this value. +The versions supported by GitLab can be found in +[`gitlab/ee/lib/ee/gitlab/ci/parsers/security/validators/schemas`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/lib/ee/gitlab/ci/parsers/security/validators/schemas). + +#### Vulnerabilities The `vulnerabilities` field of the report is an array of vulnerability objects. -#### ID +##### ID The `id` field is the unique identifier of the vulnerability. It is used to reference a fixed vulnerability from a [remediation objects](#remediations). We recommend that you generate a UUID and use it as the `id` field's value. -#### Category +##### Category The value of the `category` field matches the report type: @@ -351,12 +372,12 @@ The value of the `category` field matches the report type: - `sast` - `dast` -#### Scanner +##### Scanner The `scanner` field is an object that embeds a human-readable `name` and a technical `id`. The `id` should not collide with any other scanner another integrator would provide. -#### Name, message, and description +##### Name, message, and description The `name` and `message` fields contain a short description of the vulnerability. The `description` field provides more details. @@ -400,13 +421,13 @@ It should not repeat the other fields of the vulnerability object. In particular, the `description` should not repeat the `location` (what is affected) or the `solution` (how to mitigate the risk). -#### Solution +##### Solution You can use the `solution` field to instruct users how to fix the identified vulnerability or to mitigate the risk. End-users interact with this field, whereas GitLab automatically processes the `remediations` objects. -#### Identifiers +##### Identifiers The `identifiers` array describes the detected vulnerability. An identifier object's `type` and `value` fields are used to tell if two identifiers are the same. The user interface uses the @@ -440,15 +461,14 @@ 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 saves only the first 20 of them. Note that vulnerabilities in the [Pipeline -Security](../../user/application_security/security_dashboard/#pipeline-security) +the system saves only the first 20 of them. Note that vulnerabilities in the [Pipeline Security](../../user/application_security/security_dashboard/#view-vulnerabilities-in-a-pipeline) tab do not enforce this limit and all identifiers present in the report artifact are displayed. -### Details +#### Details The `details` field is an object that supports many different content elements that are displayed when viewing vulnerability information. An example of the various data elements can be seen in the [security-reports repository](https://gitlab.com/gitlab-examples/security/security-reports/-/tree/master/samples/details-example). -### Location +#### Location The `location` indicates where the vulnerability has been detected. The format of the location depends on the type of scanning. @@ -458,7 +478,7 @@ which is used to track vulnerabilities as new commits are pushed to the repository. The attributes used to generate the location fingerprint also depend on the type of scanning. -#### Dependency Scanning +##### Dependency Scanning The `location` of a Dependency Scanning vulnerability is composed of a `dependency` and a `file`. The `dependency` object describes the affected `package` and the dependency `version`. @@ -488,7 +508,7 @@ combines the `file` and the package `name`, so these attributes are mandatory. All other attributes are optional. -#### Container Scanning +##### Container Scanning Similar to Dependency Scanning, the `location` of a Container Scanning vulnerability has a `dependency` and a `file`. @@ -519,7 +539,7 @@ so these attributes are mandatory. The `image` is also mandatory. All other attributes are optional. -#### Cluster Image Scanning +##### Cluster Image Scanning The `location` of a `cluster_image_scanning` vulnerability has a `dependency` field. It also has an `operating_system` field. For example, here is the `location` object for a vulnerability @@ -553,7 +573,7 @@ as well as the package `name`, so these fields are required. The `image` field i The `cluster_id` and `agent_id` are mutually exclusive, and one of them must be present. All other fields are optional. -#### SAST +##### SAST The `location` of a SAST vulnerability must have a `file` and a `start_line` field, giving the path of the affected file, and the affected line number, respectively. @@ -578,7 +598,7 @@ combines `file`, `start_line`, and `end_line`, so these attributes are mandatory. All other attributes are optional. -### Tracking and merging vulnerabilities +#### Tracking and merging vulnerabilities Users may give feedback on a vulnerability: @@ -606,7 +626,7 @@ and at least one [identifier](#identifiers). Two identifiers are the same if the CWE and WASC identifiers are not considered because they describe categories of vulnerability flaws, but not specific security flaws. -#### Severity and confidence +##### Severity and confidence The `severity` field describes how much the vulnerability impacts the software, whereas the `confidence` field describes how reliable the assessment of the vulnerability is. @@ -623,7 +643,7 @@ Valid values are: `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, and needs to be investigated. We have [provided a chart](../../user/application_security/sast/analyzers.md#analyzers-data) of the available SAST Analyzers and what data is currently available. -### Remediations +#### Remediations The `remediations` field of the report is an array of remediation objects. Each remediation describes a patch that can be applied to @@ -667,28 +687,16 @@ Here is an example of a report that contains remediations. } ``` -#### Summary +##### Summary The `summary` field is an overview of how the vulnerabilities can be fixed. This field is required. -#### Fixed vulnerabilities +##### Fixed vulnerabilities The `fixes` field is an array of objects that reference the vulnerabilities fixed by the remediation. `fixes[].id` contains a fixed vulnerability's [unique identifier](#id). This field is required. -#### Diff +##### Diff The `diff` field is a base64-encoded remediation code diff, compatible with [`git apply`](https://git-scm.com/docs/git-format-patch#_discussion). This field is required. - -## Limitations - -### Container Scanning - -Container Scanning currently has these limitations: - -- Although the Security Dashboard can display scan results from multiple images, if multiple - vulnerabilities have the same fingerprint, only the first instance of that vulnerability is - displayed. We're working on removing this limitation. You can follow our progress on the issue - [Change location fingerprint for Container Scanning](https://gitlab.com/gitlab-org/gitlab/-/issues/215466). -- Different scanners may each report the same vulnerability, resulting in duplicate findings. diff --git a/doc/development/internal_api/index.md b/doc/development/internal_api/index.md index 543c5f40f88..96910892022 100644 --- a/doc/development/internal_api/index.md +++ b/doc/development/internal_api/index.md @@ -703,10 +703,10 @@ Example response: - CustomersDot -## CI minute provisioning +## CI/CD minutes provisioning -The CI Minute endpoints are used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`) -to apply additional packs of CI minutes, for personal namespaces or top-level groups within GitLab.com. +The CI/CD Minutes endpoints are used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`) +to apply additional packs of CI/CD minutes, for personal namespaces or top-level groups within GitLab.com. ### Creating an additional pack @@ -826,6 +826,32 @@ Example response: 200 ``` +### Deleting an `upcoming_reconciliation` + +Use a DELETE command to delete an `upcoming_reconciliation`. + +```plaintext +DELETE /internal/upcoming_reconciliations +``` + +| Attribute | Type | Required | Description | +|:---------------|:--------|:---------|:----------------------------------------------------------------------------------| +| `namespace_id` | integer | yes | The ID of the GitLab.com namespace that no longer has an upcoming reconciliation. | + +Example request: + +```shell +curl --request DELETE \ + --url "http://localhost:3000/api/v4/internal/upcoming_reconciliations?namespace_id=22" \ + --header 'PRIVATE-TOKEN: <admin_access_token>' +``` + +Example response: + +```plaintext +204 +``` + ### Known consumers - CustomersDot diff --git a/doc/development/licensing.md b/doc/development/licensing.md index 23871bf3c68..a50c514733e 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Licensing and Compatibility -[GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/) (CE) is licensed [under the terms of the MIT License](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/LICENSE). [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/) (EE) is licensed under "[The GitLab Enterprise Edition (EE) license](https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE)" wherein there are more restrictions. +[GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/) (CE) is licensed [under the terms of the MIT License](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/LICENSE). [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/) (EE) is licensed under "[The GitLab Enterprise Edition (EE) license](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/LICENSE)" wherein there are more restrictions. ## Automated Testing diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 69e9f7d16e3..106db862122 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -13,9 +13,7 @@ _every_ merge request **should** adhere to the guidelines outlined in this document. There are no exceptions to this rule unless specifically discussed with and agreed upon by backend maintainers and performance specialists. -To measure the impact of a merge request you can use -[Sherlock](profiling.md#sherlock). It's also highly recommended that you read -the following guides: +It's also highly recommended that you read the following guides: - [Performance Guidelines](performance.md) - [Avoiding downtime in migrations](avoiding_downtime_in_migrations.md) diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 0bd9979e790..d85b7372814 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -162,6 +162,9 @@ def down end ``` +Migrations like this are inherently risky and [additional actions](database_review.md#preparation-when-adding-data-migrations) +are required when preparing the migration for review. + ## Atomicity By default, migrations are single transaction. That is, a transaction is opened @@ -769,6 +772,32 @@ to run on a large table, as long as it is only updating a small subset of the rows in the table, but do not ignore that without validating on the GitLab.com staging environment - or asking someone else to do so for you - beforehand. +## Removing a foreign key constraint + +When removing a foreign key constraint, we need to acquire a lock on both tables +that are related to the foreign key. For tables with heavy write patterns, it's a good +idea to use `with_lock_retries`, otherwise you might fail to acquire a lock in time. +You might also run into deadlocks when acquiring a lock, because ordinarily +the application writes in `parent,child` order. However, removing a foreign +key acquires the lock in `child,parent` order. To resolve this, you can +explicitly acquire the lock in `parent,child`, for example: + +```ruby +disable_ddl_transaction! + +def up + with_lock_retries do + execute('lock table ci_pipelines, ci_builds in access exclusive mode') + + remove_foreign_key :ci_builds, to_table: :ci_pipelines, column: :pipeline_id, on_delete: :cascade, name: 'the_fk_name' + end +end + +def down + add_concurrent_foreign_key :ci_builds, :ci_pipelines, column: :pipeline_id, on_delete: :cascade, name: 'the_fk_name' +end +``` + ## Dropping a database table Dropping a database table is uncommon, and the `drop_table` method diff --git a/doc/development/permissions.md b/doc/development/permissions.md index b7079e9fb8e..72e20d31cf8 100644 --- a/doc/development/permissions.md +++ b/doc/development/permissions.md @@ -1,10 +1,10 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab permissions guide +# Implementing permissions There are multiple types of permissions across GitLab, and when implementing anything that deals with permissions, all of them should be considered. diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index c7443032d78..a9c68905095 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -170,10 +170,9 @@ After that, the next pipeline uses the up-to-date `knapsack/report-master.json` ### Flaky tests -Tests that are [known to be flaky](testing_guide/flaky_tests.md#automatic-retries-and-flaky-tests-detection) are: - -- skipped if the `$SKIP_FLAKY_TESTS_AUTOMATICALLY` variable is set to `true` (`false` by default) -- run if `$SKIP_FLAKY_TESTS_AUTOMATICALLY` variable is not set to `true` or if the `~"pipeline:run-flaky-tests"` label is set on the MR +Tests that are [known to be flaky](testing_guide/flaky_tests.md#automatic-retries-and-flaky-tests-detection) are +skipped unless the `$SKIP_FLAKY_TESTS_AUTOMATICALLY` variable is set to `false` or if the `~"pipeline:run-flaky-tests"` +label is set on the MR. ### Monitoring @@ -222,6 +221,13 @@ The `* as-if-jh` jobs are run in addition to the regular EE-context jobs. The `j The intent is to ensure that a change doesn't introduce a failure after the `gitlab-org/gitlab` project is synced to the `gitlab-jh/gitlab` project. +### Corresponding JH branch + +You can create a corresponding JH branch on the `gitlab-jh/gitlab` project by +appending `-jh` to the branch name. If a corresponding JH branch is found, +`* as-if-jh` jobs grab the `jh` folder from the respective branch, +rather than from the default branch. + ## `undercover` RSpec test > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/74859) in GitLab 14.6. @@ -266,318 +272,123 @@ We follow the [PostgreSQL versions shipped with Omnibus GitLab](../administratio ## Pipelines types for merge requests -In general, pipelines for an MR fall into one or more of the following types, -depending on the changes made in the MR: +In general, pipelines for an MR fall into one of the following types (from shorter to longer), depending on the changes made in the MR: + +- [Documentation pipeline](#documentation-pipeline): For MRs that touch documentation. +- [Backend pipeline](#backend-pipeline): For MRs that touch backend code. +- [Frontend pipeline](#frontend-pipeline): For MRs that touch frontend code. +- [End-to-end pipeline](#end-to-end-pipeline): For MRs that touch code in the `qa/` folder. -- [Documentation only MR pipeline](#documentation-only-mr-pipeline): This is typically created for an MR that only changes documentation. -- [Code-only MR pipeline](#code-only-mr-pipeline): This is typically created for an MR that only changes code, either backend or frontend. -- [Frontend-only MR pipeline](#frontend-only-mr-pipeline): This is typically created for an MR that only changes frontend code. -- [QA-only MR pipeline](#qa-only-mr-pipeline): This is typically created for an MR that only changes end to end tests related code. +A "pipeline type" is an abstract term that mostly describes the "critical path" (i.e. the chain of jobs for which the sum +of individual duration equals the pipeline's duration). +We use these "pipeline types" in [metrics dashboards](https://app.periscopedata.com/app/gitlab/858266/GitLab-Pipeline-Durations) +in order to detect what types and jobs need to be optimized first. + +An MR that touches multiple areas would be associated with the longest type applicable. For instance, an MR that touches backend +and frontend would fall into the "Frontend" pipeline type since this type takes longer to finish than the "Backend" pipeline type. We use the [`rules:`](../ci/yaml/index.md#rules) and [`needs:`](../ci/yaml/index.md#needs) keywords extensively to determine the jobs that need to be run in a pipeline. Note that an MR that includes multiple types of changes would have a pipelines that include jobs from multiple types (for example, a combination of docs-only and code-only pipelines). -### Documentation only MR pipeline +Following are graphs of the critical paths for each pipeline type. Jobs that aren't part of the critical path are ommitted. + +### Documentation pipeline -[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/-/pipelines/250546928): +[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/-/pipelines/432049110). ```mermaid graph LR - subgraph "No needed jobs"; - 1-1["danger-review (2.3 minutes)"]; - click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" - 1-2["docs-lint markdown (1.5 minutes)"]; - click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=10224335&udv=0" - 1-3["docs-lint links (5 minutes)"]; - click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356757&udv=0" - 1-4["ui-docs-links lint (2.5 minutes)"]; - click 1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=10823717&udv=1020379" - end + classDef criticalPath fill:#f66; + + 1-3["docs-lint links (5 minutes)"]; + class 1-3 criticalPath; + click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356757&udv=0" ``` -### Code-only MR pipeline +### Backend pipeline -[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/pipelines/136295694) +[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/-/pipelines/433316063). ```mermaid graph RL; classDef criticalPath fill:#f66; - subgraph "No needed jobs"; - 1-1["danger-review (2.3 minutes)"]; - click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" - 1-2["build-qa-image (2 minutes)"]; - click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914325&udv=0" - 1-3["compile-test-assets (6 minutes)"]; - click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914317&udv=0" - 1-4["compile-test-assets as-if-foss (7 minutes)"]; - click 1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356616&udv=0" - 1-5["compile-production-assets (14 minutes)"]; - click 1-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914312&udv=0" - 1-6["setup-test-env (4 minutes)"]; - click 1-6 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914315&udv=0" - 1-7["review-delete-deployment"]; - 1-8["dependency_scanning"]; - 1-9["qa:internal, qa:internal-as-if-foss"]; - 1-11["qa:selectors, qa:selectors-as-if-foss"]; - 1-14["retrieve-tests-metadata (1 minutes)"]; - click 1-14 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356697&udv=0" - 1-15["code_quality"]; - 1-16["brakeman-sast"]; - 1-17["eslint-sast"]; - 1-18["kubesec-sast"]; - 1-20["secrets-sast"]; - 1-21["static-analysis (14 minutes)"]; - click 1-21 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914471&udv=0" - - class 1-3 criticalPath; - class 1-6 criticalPath; - end - - 2_1-1["graphql-verify (2.3 minutes)"]; - click 2_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356715&udv=0" - 2_1-2["memory-static (4.75 minutes)"]; - click 2_1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356721&udv=0" - 2_1-3["run-dev-fixtures (3 minutes)"]; - click 2_1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356729&udv=0" - 2_1-4["run-dev-fixtures-ee (4 minutes)"]; - click 2_1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356731&udv=0" - subgraph "Needs `setup-test-env`"; - 2_1-1 & 2_1-2 & 2_1-3 & 2_1-4 --> 1-6; - end - - 2_2-2["rspec-all frontend_fixture (7 minutes)"]; - class 2_2-2 criticalPath; - click 2_2-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910143&udv=0" - 2_2-4["memory-on-boot (3.5 minutes)"]; - click 2_2-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356727&udv=0" - 2_2-5["webpack-dev-server (4 minutes)"]; - click 2_2-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8404303&udv=0" - subgraph "Needs `setup-test-env` & `compile-test-assets`"; - 2_2-2 & 2_2-4 & 2_2-5 --> 1-6 & 1-3; - end - - 2_3-1["build-assets-image (1.6 minutes)"]; - subgraph "Needs `compile-production-assets`"; - 2_3-1 --> 1-5 - end - - 2_4-1["package-and-qa (manual)"]; - subgraph "Needs `build-qa-image`"; - 2_4-1 --> 1-2; - click 2_4-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914305&udv=0" - end - - 2_5-1["rspec & db jobs (12-22 minutes)"]; - subgraph "Needs `compile-test-assets`, `setup-test-env`, & `retrieve-tests-metadata`"; - 2_5-1 --> 1-3 & 1-6 & 1-14; - class 2_5-1 criticalPath; - click 2_5-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations" - end - - 3_1-1["jest (14.5 minutes)"]; - class 3_1-1 criticalPath; - click 3_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914204&udv=0" - subgraph "Needs `rspec-all frontend_fixture`"; - 3_1-1 --> 2_2-2; - end - - 3_2-1["rspec:coverage (4 minutes)"]; - subgraph "Depends on `rspec` jobs"; - 3_2-1 -.->|"(don't use needs because of limitations)"| 2_5-1; - click 3_2-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7248745&udv=0" - end - - 4_1-1["coverage-frontend (2 minutes)"]; - subgraph "Needs `jest`"; - 4_1-1 --> 3_1-1; - class 4_1-1 criticalPath; - click 4_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910777&udv=0" - end + 1-3["compile-test-assets (6 minutes)"]; + class 1-3 criticalPath; + click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914317&udv=0" + 1-6["setup-test-env (4 minutes)"]; + click 1-6 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914315&udv=0" + 1-14["retrieve-tests-metadata"]; + click 1-14 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356697&udv=0" + 1-15["detect-tests"]; + click 1-15 "https://app.periscopedata.com/app/gitlab/652085/EP---Jobs-Durations?widget=10113603&udv=1005715" + + 2_5-1["rspec & db jobs (24 minutes)"]; + class 2_5-1 criticalPath; + click 2_5-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations" + 2_5-1 --> 1-3 & 1-6 & 1-14 & 1-15; + + 3_2-1["rspec:coverage (5.35 minutes)"]; + class 3_2-1 criticalPath; + click 3_2-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7248745&udv=0" + 3_2-1 -.->|"(don't use needs<br/>because of limitations)"| 2_5-1; + + 4_3-1["rspec:undercoverage (3.5 minutes)"]; + class 4_3-1 criticalPath; + click 4_3-1 "https://app.periscopedata.com/app/gitlab/652085/EP---Jobs-Durations?widget=13446492&udv=1005715" + 4_3-1 --> 3_2-1; + ``` -### Frontend-only MR pipeline +### Frontend pipeline -[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/pipelines/134661039): +[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/-/pipelines/431913287). ```mermaid graph RL; classDef criticalPath fill:#f66; - subgraph "No needed jobs"; - 1-1["danger-review (2.3 minutes)"]; - click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" - 1-2["build-qa-image (2 minutes)"]; - click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914325&udv=0" - 1-3["compile-test-assets (6 minutes)"]; - click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914317&udv=0" - 1-4["compile-test-assets as-if-foss (7 minutes)"]; - click 1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356616&udv=0" - 1-5["compile-production-assets (14 minutes)"]; - click 1-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914312&udv=0" - 1-6["setup-test-env (4 minutes)"]; - click 1-6 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914315&udv=0" - 1-7["review-stop-failed-deployment"]; - 1-8["dependency_scanning"]; - 1-9["qa:internal, qa:internal-as-if-foss"]; - 1-11["qa:selectors, qa:selectors-as-if-foss"]; - 1-14["retrieve-tests-metadata (1 minutes)"]; - click 1-14 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356697&udv=0" - 1-15["code_quality"]; - 1-16["brakeman-sast"]; - 1-17["eslint-sast"]; - 1-18["kubesec-sast"]; - 1-20["secrets-sast"]; - 1-21["static-analysis (14 minutes)"]; - click 1-21 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914471&udv=0" - - class 1-3 criticalPath; - class 1-5 criticalPath; - class 1-6 criticalPath; - end - - 2_1-1["graphql-verify (2.3 minutes)"]; - click 2_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356715&udv=0" - 2_1-2["memory-static (4.75 minutes)"]; - click 2_1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356721&udv=0" - 2_1-3["run-dev-fixtures (3 minutes)"]; - click 2_1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356729&udv=0" - 2_1-4["run-dev-fixtures-ee (4 minutes)"]; - click 2_1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356731&udv=0" - subgraph "Needs `setup-test-env`"; - 2_1-1 & 2_1-2 & 2_1-3 & 2_1-4 --> 1-6; - end - - 2_2-2["rspec-all frontend_fixture (7 minutes)"]; - class 2_2-2 criticalPath; - click 2_2-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910143&udv=0" - 2_2-4["memory-on-boot (3.5 minutes)"]; - click 2_2-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356727&udv=0" - 2_2-5["webpack-dev-server (4 minutes)"]; - click 2_2-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8404303&udv=0" - subgraph "Needs `setup-test-env` & `compile-test-assets`"; - 2_2-2 & 2_2-4 & 2_2-5 --> 1-6 & 1-3; - end - - 2_3-1["build-assets-image (1.6 minutes)"]; + 1-2["build-qa-image (2 minutes)"]; + click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914325&udv=0" + 1-5["compile-production-assets (16 minutes)"]; + class 1-5 criticalPath; + click 1-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914312&udv=0" + + 2_3-1["build-assets-image (1.3 minutes)"]; class 2_3-1 criticalPath; - subgraph "Needs `compile-production-assets`"; - 2_3-1 --> 1-5 - end - - 2_4-1["package-and-qa (manual)"]; - subgraph "Needs `build-qa-image` & `build-assets-image`"; - 2_4-1 --> 1-2 & 2_3-1; - click 2_4-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914305&udv=0" - end - - 2_5-1["rspec & db jobs (12-22 minutes)"]; - subgraph "Needs `compile-test-assets`, `setup-test-env, & `retrieve-tests-metadata`"; - 2_5-1 --> 1-3 & 1-6 & 1-14; - class 2_5-1 criticalPath; - click 2_5-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations" - end - - 2_6-1["review-build-cng (27 minutes)"]; - subgraph "Needs `build-assets-image`"; - 2_6-1 --> 2_3-1; - class 2_6-1 criticalPath; - click 2_6-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914314&udv=0" - end - - 3_1-1["jest (14.5 minutes)"]; - class 3_1-1 criticalPath; - click 3_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914204&udv=0" - subgraph "Needs `rspec-all frontend_fixture`"; - 3_1-1 --> 2_2-2; - end - - 3_2-1["rspec:coverage (4 minutes)"]; - subgraph "Depends on `rspec` jobs"; - 3_2-1 -.->|"(don't use needs because of limitations)"| 2_5-1; - click 3_2-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7248745&udv=0" - end - - 4_1-1["coverage-frontend (2 minutes)"]; - subgraph "Needs `jest`"; - 4_1-1 --> 3_1-1; - class 4_1-1 criticalPath; - click 4_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=7910777&udv=0" - end - - 3_3-1["review-deploy (9 minutes)"]; - subgraph "Played by `review-build-cng`"; - 3_3-1 --> 2_6-1; - class 3_3-1 criticalPath; - click 3_3-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6721130&udv=0" - end - - 4_2-1["review-qa-smoke (7.4 minutes)"]; - click 4_2-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6729805&udv=0" - 4_2-2["review-performance (2.5 minutes)"]; - click 4_2-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356817&udv=0" - subgraph "Played by `review-deploy`"; - 4_2-1 & 4_2-2 --> 3_3-1; - end + 2_3-1 --> 1-5 + + 2_6-1["start-review-app-pipeline (49 minutes)"]; + class 2_6-1 criticalPath; + click 2_6-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations" + 2_6-1 --> 2_3-1 & 1-2; ``` -### QA-only MR pipeline +### End-to-end pipeline -[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/pipelines/134645109): +[Reference pipeline](https://gitlab.com/gitlab-org/gitlab/-/pipelines/431918463). ```mermaid graph RL; classDef criticalPath fill:#f66; - subgraph "No needed jobs"; - 1-1["danger-review (2.3 minutes)"]; - click 1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8100542&udv=0" - 1-2["build-qa-image (2 minutes)"]; - click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914325&udv=0" - 1-3["compile-test-assets (6 minutes)"]; - click 1-3 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914317&udv=0" - 1-4["compile-test-assets as-if-foss (7 minutes)"]; - click 1-4 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356616&udv=0" - 1-5["compile-production-assets (14 minutes)"]; - click 1-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914312&udv=0" - 1-6["setup-test-env (4 minutes)"]; - click 1-6 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914315&udv=0" - 1-7["review-stop-failed-deployment"]; - 1-8["dependency_scanning"]; - 1-9["qa:internal, qa:internal-as-if-foss"]; - 1-11["qa:selectors, qa:selectors-as-if-foss"]; - 1-14["retrieve-tests-metadata (1 minutes)"]; - click 1-14 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356697&udv=0" - 1-15["code_quality"]; - 1-16["brakeman-sast"]; - 1-17["eslint-sast"]; - 1-18["kubesec-sast"]; - 1-20["secrets-sast"]; - 1-21["static-analysis (14 minutes)"]; - click 1-21 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914471&udv=0" - - class 1-5 criticalPath; - end - - 2_1-1["graphql-verify (2.3 minutes)"]; - click 2_1-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=8356715&udv=0" - subgraph "Needs `setup-test-env`"; - 2_1-1 --> 1-6; - end - - 2_3-1["build-assets-image (1.6 minutes)"]; - subgraph "Needs `compile-production-assets`"; - 2_3-1 --> 1-5 - class 2_3-1 criticalPath; - end - - 2_4-1["package-and-qa (113 minutes)"]; - subgraph "Needs `build-qa-image` & `build-assets-image`"; - 2_4-1 --> 1-2 & 2_3-1; - class 2_4-1 criticalPath; - click 2_4-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914305&udv=0" - end + 1-2["build-qa-image (2 minutes)"]; + click 1-2 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914325&udv=0" + 1-5["compile-production-assets (16 minutes)"]; + class 1-5 criticalPath; + click 1-5 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914312&udv=0" + 1-15["detect-tests"]; + click 1-15 "https://app.periscopedata.com/app/gitlab/652085/EP---Jobs-Durations?widget=10113603&udv=1005715" + + 2_3-1["build-assets-image (1.3 minutes)"]; + class 2_3-1 criticalPath; + 2_3-1 --> 1-5 + + 2_4-1["package-and-qa (102 minutes)"]; + class 2_4-1 criticalPath; + click 2_4-1 "https://app.periscopedata.com/app/gitlab/652085/Engineering-Productivity---Pipeline-Build-Durations?widget=6914305&udv=0" + 2_4-1 --> 1-2 & 2_3-1 & 1-15; ``` ## CI configuration internals diff --git a/doc/development/policies.md b/doc/development/policies.md index 9a977a49329..61cc6e0edf5 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/development/profiling.md b/doc/development/profiling.md index 656b30402a6..789e0640933 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -108,20 +108,6 @@ Find more information about different sampling modes in the [Stackprof docs](htt This is enabled for all users that can access the performance bar. -## Sherlock - -Sherlock is a custom profiling tool built into GitLab. Sherlock is _only_ -available when running GitLab in development mode _and_ when setting the -environment variable `ENABLE_SHERLOCK` to a non empty value. For example: - -```shell -ENABLE_SHERLOCK=1 bundle exec rails s -``` - -Sherlock is also [available though the GitLab GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/sherlock.md). - -Recorded transactions can be found by navigating to `/sherlock/transactions`. - ## Bullet Bullet is a Gem that can be used to track down N+1 query problems. Bullet section is diff --git a/doc/development/redis/new_redis_instance.md b/doc/development/redis/new_redis_instance.md index 37ee51ebb82..dcd79be0e5c 100644 --- a/doc/development/redis/new_redis_instance.md +++ b/doc/development/redis/new_redis_instance.md @@ -110,6 +110,131 @@ documentation for feature flags. When we have been using the new instance 100% of the time in production for a while and there are no issues, we can proceed. +### Proposed solution: Migrate data by using MultiStore with the fallback strategy + +We need a way to migrate users to a new Redis store without causing any inconveniences from UX perspective. +We also want the ability to fall back to the "old" Redis instance if something goes wrong with the new instance. + +Migration Requirements: + +- No downtime. +- No loss of stored data until the TTL for storing data expires. +- Partial rollout using Feature Flags or ENV vars or combinations of both. +- Monitoring of the switch. +- Prometheus metrics in place. +- Easy rollback without downtime in case the new instance or logic does not behave as expected. + +It is somewhat similar to the zero-downtime DB table rename. +We need to write data into both Redis instances (old + new). +We read from the new instance, but we need to fall back to the old instance when pre-fetching from the new dedicated Redis instance that failed. +We need to log any issues or exceptions with a new instance, but still fall back to the old instance. + +The proposed migration strategy is to implement and use the [MultiStore](https://gitlab.com/gitlab-org/gitlab/-/blob/fcc42e80ed261a862ee6ca46b182eee293ae60b6/lib/gitlab/redis/multi_store.rb). +We used this approach with [adding new dedicated Redis instance for session keys](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/579). +Also MultiStore comes with corresponding [specs](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/lib/gitlab/redis/multi_store_spec.rb). + +The MultiStore looks like a `redis-rb ::Redis` instance. + +In the new Redis instance class you added in [Step 1](#step-1-support-configuring-the-new-instance), +override the [Redis](https://gitlab.com/gitlab-org/gitlab/-/blob/fcc42e80ed261a862ee6ca46b182eee293ae60b6/lib/gitlab/redis/sessions.rb#L20-28) method from the `::Gitlab::Redis::Wrapper` + +```ruby +module Gitlab + module Redis + class Foo < ::Gitlab::Redis::Wrapper + ... + def self.redis + # Don't use multistore if redis.foo configuration is not provided + return super if config_fallback? + + primary_store = ::Redis.new(params) + secondary_store = ::Redis.new(config_fallback.params) + + MultiStore.new(primary_store, secondary_store, store_name) + end + end + end +end +``` + +MultiStore is initialized by providing the new Redis instance as a primary store, and [old (fallback-instance)](#fallback-instance) as a secondary store. +The third argument is `store_name` which is used for logs, metrics and feature flag names, in case we use MultiStore implementation for different Redis stores at the same time. + +By default, the MultiStore reads and writes only from the default Redis store. +The default Redis store is `secondary_store` (the old fallback-instance). +This allows us to introduce MultiStore without changing the default behavior. + +MultiStore uses two feature flags to control the actual migration: + +- `use_primary_and_secondary_stores_for_[store_name]` +- `use_primary_store_as_default_for_[store_name]` + +For example, if our new Redis instance is called `Gitlab::Redis::Foo`, we can [create](../../../ee/development/feature_flags/#create-a-new-feature-flag) two feature flags by executing: + +```shell +bin/feature-flag use_primary_and_secondary_stores_for_foo +bin/feature-flag use_primary_store_as_default_for_foo +``` + +By enabling `use_primary_and_secondary_stores_for_foo` feature flag, our `Gitlab::Redis::Foo` will use `MultiStore` to write to both new Redis instance +and the [old (fallback-instance)](#fallback-instance). +If we fail to fetch data from the new instance, we will fallback and read from the old Redis instance. + +We can monitor logs for `Gitlab::Redis::MultiStore::ReadFromPrimaryError`, and also the Prometheus counter `gitlab_redis_multi_store_read_fallback_total`. +Once we stop seeing them, this means that we are no longer relying on the data stored on the old Redis store. +At this point, we are probably safe to move the traffic to the new Redis store. + +By enabling `use_primary_store_as_default_for_foo` feature flag, the `MultiStore` will use `primary_store` (new instance) as default Redis store. + +Once this feature flag is enabled, we can disable `use_primary_and_secondary_stores_for_foo` feature flag. +This will allow the MultiStore to read and write only from the primary Redis store (new store), moving all the traffic to the new Redis store. + +Once we have moved all our traffic to the primary store, our data migration is complete. +We can safely remove the MultiStore implementation and continue to use newly introduced Redis store instance. + +#### Implementation details + +MultiStore implements read and write Redis commands separately. + +##### Read commands + +- `get` +- `mget` +- `smembers` +- `scard` + +##### Write commands + +- `set` +- `setnx` +- `setex` +- `sadd` +- `srem` +- `del` +- `pipelined` +- `flushdb` + +When a command outside of the supported list is used, `method_missing` will pass it to the old Redis instance and keep track of it. +This ensures that anything unexpected behaves like it would before. + +NOTE: +By tracking `gitlab_redis_multi_store_method_missing_total` counter and `Gitlab::Redis::MultiStore::MethodMissingError`, +a developer will need to add an implementation for missing Redis commands before proceeding with the migration. + +##### Errors + +| error | message | +|-------------------------------------------------|-----------------------------------------------------------------------| +| `Gitlab::Redis::MultiStore::ReadFromPrimaryError` | Value not found on the Redis primary store. Read from the Redis secondary store successful. | +| `Gitlab::Redis::MultiStore::MethodMissingError` | Method missing. Falling back to execute method on the Redis secondary store. | + +##### Metrics + +| metrics name | type | labels | description | +|-------------------------------------------------|--------------------|------------------------|----------------------------------------------------| +| gitlab_redis_multi_store_read_fallback_total | Prometheus Counter | command, instance_name | Client side Redis MultiStore reading fallback total| +| gitlab_redis_multi_store_method_missing_total | Prometheus Counter | command, instance_name | Client side Redis MultiStore method missing total | + ## Step 4: clean up after the migration <!-- markdownlint-disable MD044 --> diff --git a/doc/development/secure_coding_guidelines.md b/doc/development/secure_coding_guidelines.md index 21655d6a8fb..51d3338e5ed 100644 --- a/doc/development/secure_coding_guidelines.md +++ b/doc/development/secure_coding_guidelines.md @@ -767,3 +767,354 @@ In the example above, the `is_admin?` method is overwritten when passing it to t - If you must, be **very** confident that you've sanitized the values correctly. Consider creating an allowlist of values, and validating the user input against that. - When extending classes that use metaprogramming, make sure you don't inadvertently override any method definition safety checks. + +## Working with archive files + +Working with archive files like `zip`, `tar`, `jar`, `war`, `cpio`, `apk`, `rar` and `7z` presents an area where potentially critical security vulnerabilities can sneak into an application. + +### Zip Slip + +In 2018, the security company Snyk [released a blog post](https://snyk.io/research/zip-slip-vulnerability) describing research into a widespread and critical vulnerability present in many libraries and applications which allows an attacker to overwrite arbitrary files on the server file system which, in many cases, can be leveraged to achieve remote code execution. The vulnerability was dubbed Zip Slip. + +A Zip Slip vulnerability happens when an application extracts an archive without validating and sanitizing the filenames inside the archive for directory traversal sequences that change the file location when the file is extracted. + +Example malicious file names: + +- `../../etc/passwd` +- `../../root/.ssh/authorized_keys` +- `../../etc/gitlab/gitlab.rb` + +If a vulnerable application extracts an archive file with any of these file names, the attacker can overwrite these files with arbitrary content. + +### Insecure archive extraction examples + +#### Ruby + +For zip files, the [rubyzip](https://rubygems.org/gems/rubyzip) Ruby gem is already patched against the Zip Slip vulnerability and will refuse to extract files that try to perform directory traversal, so for this vulnerable example we will extract a `tar.gz` file with `Gem::Package::TarReader`: + +```ruby +# Vulnerable tar.gz extraction example! + +begin + tar_extract = Gem::Package::TarReader.new(Zlib::GzipReader.open("/tmp/uploaded.tar.gz")) +rescue Errno::ENOENT + STDERR.puts("archive file does not exist or is not readable") + exit(false) +end +tar_extract.rewind + +tar_extract.each do |entry| + next unless entry.file? # Only process files in this example for simplicity. + + destination = "/tmp/extracted/#{entry.full_name}" # Oops! We blindly use the entry file name for the destination. + File.open(destination, "wb") do |out| + out.write(entry.read) + end +end +``` + +#### Go + +```golang +// unzip INSECURELY extracts source zip file to destination. +func unzip(src, dest string) error { + r, err := zip.OpenReader(src) + if err != nil { + return err + } + defer r.Close() + + os.MkdirAll(dest, 0750) + + for _, f := range r.File { + if f.FileInfo().IsDir() { // Skip directories in this example for simplicity. + continue + } + + rc, err := f.Open() + if err != nil { + return err + } + defer rc.Close() + + path := filepath.Join(dest, f.Name) // Oops! We blindly use the entry file name for the destination. + os.MkdirAll(filepath.Dir(path), f.Mode()) + f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, f.Mode()) + if err != nil { + return err + } + defer f.Close() + + if _, err := io.Copy(f, rc); err != nil { + return err + } + } + + return nil +} +``` + +#### Best practices + +Always expand the destination file path by resolving all potential directory traversals and other sequences that can alter the path and refuse extraction if the final destination path does not start with the intended destination directory. + +##### Ruby + +```ruby +# tar.gz extraction example with protection against Zip Slip attacks. + +begin + tar_extract = Gem::Package::TarReader.new(Zlib::GzipReader.open("/tmp/uploaded.tar.gz")) +rescue Errno::ENOENT + STDERR.puts("archive file does not exist or is not readable") + exit(false) +end +tar_extract.rewind + +tar_extract.each do |entry| + next unless entry.file? # Only process files in this example for simplicity. + + # safe_destination will raise an exception in case of Zip Slip / directory traversal. + destination = safe_destination(entry.full_name, "/tmp/extracted") + + File.open(destination, "wb") do |out| + out.write(entry.read) + end +end + +def safe_destination(filename, destination_dir) + raise "filename cannot start with '/'" if filename.start_with?("/") + + destination_dir = File.realpath(destination_dir) + destination = File.expand_path(filename, destination_dir) + + raise "filename is outside of destination directory" unless + destination.start_with?(destination_dir + "/")) + + destination +end +``` + +```ruby +# zip extraction example using rubyzip with built-in protection against Zip Slip attacks. +require 'zip' + +Zip::File.open("/tmp/uploaded.zip") do |zip_file| + zip_file.each do |entry| + # Extract entry to /tmp/extracted directory. + entry.extract("/tmp/extracted") + end +end +``` + +##### Go + +You are encouraged to use the secure archive utilities provided by [LabSec](https://gitlab.com/gitlab-com/gl-security/appsec/labsec) which will handle Zip Slip and other types of vulnerabilities for you. The LabSec utilities are also context aware which makes it possible to cancel or timeout extractions: + +```golang +package main + +import "gitlab-com/gl-security/appsec/labsec/archive/zip" + +func main() { + f, err := os.Open("/tmp/uploaded.zip") + if err != nil { + panic(err) + } + defer f.Close() + + fi, err := f.Stat() + if err != nil { + panic(err) + } + + if err := zip.Extract(context.Background(), f, fi.Size(), "/tmp/extracted"); err != nil { + panic(err) + } +} +``` + +In case the LabSec utilities do not fit your needs, here is an example for extracting a zip file with protection against Zip Slip attacks: + +```golang +// unzip extracts source zip file to destination with protection against Zip Slip attacks. +func unzip(src, dest string) error { + r, err := zip.OpenReader(src) + if err != nil { + return err + } + defer r.Close() + + os.MkdirAll(dest, 0750) + + for _, f := range r.File { + if f.FileInfo().IsDir() { // Skip directories in this example for simplicity. + continue + } + + rc, err := f.Open() + if err != nil { + return err + } + defer rc.Close() + + path := filepath.Join(dest, f.Name) + + // Check for Zip Slip / directory traversal + if !strings.HasPrefix(path, filepath.Clean(dest) + string(os.PathSeparator)) { + return fmt.Errorf("illegal file path: %s", path) + } + + os.MkdirAll(filepath.Dir(path), f.Mode()) + f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, f.Mode()) + if err != nil { + return err + } + defer f.Close() + + if _, err := io.Copy(f, rc); err != nil { + return err + } + } + + return nil +} +``` + +### Symlink attacks + +Symlink attacks makes it possible for an attacker to read the contents of arbitrary files on the server of a vulnerable application. While it is a high-severity vulnerability that can often lead to remote code execution and other critical vulnerabilities, it is only exploitable in scenarios where a vulnerable application accepts archive files from the attacker and somehow displays the extracted contents back to the attacker without any validation or sanitization of symbolic links inside the archive. + +### Insecure archive symlink extraction examples + +#### Ruby + +For zip files, the [rubyzip](https://rubygems.org/gems/rubyzip) Ruby gem is already patched against symlink attacks as it simply ignores symbolic links, so for this vulnerable example we will extract a `tar.gz` file with `Gem::Package::TarReader`: + +```ruby +# Vulnerable tar.gz extraction example! + +begin + tar_extract = Gem::Package::TarReader.new(Zlib::GzipReader.open("/tmp/uploaded.tar.gz")) +rescue Errno::ENOENT + STDERR.puts("archive file does not exist or is not readable") + exit(false) +end +tar_extract.rewind + +# Loop over each entry and output file contents +tar_extract.each do |entry| + next if entry.directory? + + # Oops! We don't check if the file is actually a symbolic link to a potentially sensitive file. + puts entry.read +end +``` + +#### Go + +```golang +// printZipContents INSECURELY prints contents of files in a zip file. +func printZipContents(src string) error { + r, err := zip.OpenReader(src) + if err != nil { + return err + } + defer r.Close() + + // Loop over each entry and output file contents + for _, f := range r.File { + if f.FileInfo().IsDir() { + continue + } + + rc, err := f.Open() + if err != nil { + return err + } + defer rc.Close() + + // Oops! We don't check if the file is actually a symbolic link to a potentially sensitive file. + buf, err := ioutil.ReadAll(rc) + if err != nil { + return err + } + + fmt.Println(buf.String()) + } + + return nil +} +``` + +#### Best practices + +Always check the type of the archive entry before reading the contents and ignore entries that are not plain files. If you absolutely must support symbolic links, ensure that they only point to files inside the archive and nowhere else. + +##### Ruby + +```ruby +# tar.gz extraction example with protection against symlink attacks. + +begin + tar_extract = Gem::Package::TarReader.new(Zlib::GzipReader.open("/tmp/uploaded.tar.gz")) +rescue Errno::ENOENT + STDERR.puts("archive file does not exist or is not readable") + exit(false) +end +tar_extract.rewind + +# Loop over each entry and output file contents +tar_extract.each do |entry| + next if entry.directory? + + # By skipping symbolic links entirely, we are sure they can't cause any trouble! + next if entry.symlink? + + puts entry.read +end +``` + +##### Go + +You are encouraged to use the secure archive utilities provided by [LabSec](https://gitlab.com/gitlab-com/gl-security/appsec/labsec) which will handle Zip Slip and symlink vulnerabilities for you. The LabSec utilities are also context aware which makes it possible to cancel or timeout extractions. + +In case the LabSec utilities do not fit your needs, here is an example for extracting a zip file with protection against symlink attacks: + +```golang +// printZipContents prints contents of files in a zip file with protection against symlink attacks. +func printZipContents(src string) error { + r, err := zip.OpenReader(src) + if err != nil { + return err + } + defer r.Close() + + // Loop over each entry and output file contents + for _, f := range r.File { + if f.FileInfo().IsDir() { + continue + } + + // By skipping all irregular file types (including symbolic links), we are sure they can't cause any trouble! + if !zf.Mode().IsRegular() { + continue + } + + rc, err := f.Open() + if err != nil { + return err + } + defer rc.Close() + + buf, err := ioutil.ReadAll(rc) + if err != nil { + return err + } + + fmt.Println(buf.String()) + } + + return nil +} +``` diff --git a/doc/development/service_ping/index.md b/doc/development/service_ping/index.md index 1f751eea4d8..315ff2b090c 100644 --- a/doc/development/service_ping/index.md +++ b/doc/development/service_ping/index.md @@ -311,7 +311,8 @@ The following is example content of the Service Ping payload. "database": { "adapter": "postgresql", "version": "9.6.15", - "pg_system_id": 6842684531675334351 + "pg_system_id": 6842684531675334351, + "flavor": "Cloud SQL for PostgreSQL" }, "analytics_unique_visits": { "g_analytics_contribution": 999, @@ -435,6 +436,10 @@ The following is example content of the Service Ping payload. ## Notable changes +In GitLab 14.6, [`flavor`](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75587) was added to try to detect the underlying managed database variant. +Possible values are "Amazon Aurora PostgreSQL", "PostgreSQL on Amazon RDS", "Cloud SQL for PostgreSQL", +"Azure Database for PostgreSQL - Flexible Server", or "null". + In GitLab 13.5, `pg_system_id` was added to send the [PostgreSQL system identifier](https://www.2ndquadrant.com/en/blog/support-for-postgresqls-system-identifier-in-barman/). ## Export Service Ping SQL queries and definitions diff --git a/doc/development/service_ping/metrics_instrumentation.md b/doc/development/service_ping/metrics_instrumentation.md index 6fdbd1eea31..c98b0df92aa 100644 --- a/doc/development/service_ping/metrics_instrumentation.md +++ b/doc/development/service_ping/metrics_instrumentation.md @@ -33,6 +33,12 @@ We have built a domain-specific language (DSL) to define the metrics instrumenta ## Database metrics +- `operation`: Operations for the given `relation`, one of `count`, `distinct_count`. +- `relation`: `ActiveRecord::Relation` for the objects we want to perform the `operation`. +- `start`: Specifies the start value of the batch counting, by default is `relation.minimum(:id)`. +- `finish`: Specifies the end value of the batch counting, by default is `relation.maximum(:id)`. +- `cache_start_and_finish_as`: Specifies the cache key for `start` and `finish` values and sets up caching them. Use this call when `start` and `finish` are expensive queries that should be reused between different metric calculations. + [Example of a merge request that adds a database metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60022). ```ruby diff --git a/doc/development/service_ping/performance_indicator_metrics.md b/doc/development/service_ping/performance_indicator_metrics.md new file mode 100644 index 00000000000..48c123171fa --- /dev/null +++ b/doc/development/service_ping/performance_indicator_metrics.md @@ -0,0 +1,17 @@ +--- +stage: Growth +group: Product Intelligence +info: To 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 Indicator Metrics guide + +This guide describes how to use metrics definitions to define [performance indicator](https://about.gitlab.com/handbook/product/product-intelligence-guide/#implementing-product-performance-indicators) metrics. + +To use a metric definition to manage a performance indicator: + +1. Create a new issue and use the [Performance Indicator Metric issue template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Performance%20Indicator%20Metric). +1. Use labels `~"product intelligence"`, `"~Data Warehouse::Impact Check"`. +1. Create a merge request that includes changes related only to the metric performance indicator. +1. Update the metric definition `performance_indicator_type` [field](metrics_dictionary.md#metrics-definition-and-validation). +1. Create an issue in GitLab Data Team project with the [Product Performance Indicator template](https://gitlab.com/gitlab-data/analytics/-/issues/new?issuable_template=Product%20Performance%20Indicator%20Template). diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index 2137a7d83e6..af994e7138d 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -13,7 +13,7 @@ modifying Sidekiq workers. All workers should include `ApplicationWorker` instead of `Sidekiq::Worker`, which adds some convenience methods and automatically sets the queue based on -the worker's name. +the [routing rules](../administration/operations/extra_sidekiq_routing.md#queue-routing-rules). ## Retries @@ -45,19 +45,26 @@ Each retry for a worker is counted as a failure in our metrics. A worker which always fails 9 times and succeeds on the 10th would have a 90% error rate. -## Dedicated Queues +## Sidekiq Queues -All workers should use their own queue, which is automatically set based on the +Previously, each worker had its own queue, which was automatically set based on the worker class name. For a worker named `ProcessSomethingWorker`, the queue name -would be `process_something`. If you're not sure what queue a worker uses, +would be `process_something`. You can now route workers to a specific queue using +[queue routing rules](../administration/operations/extra_sidekiq_routing.md#queue-routing-rules). +In GDK, new workers are routed to a queue named `default`. + +If you're not sure what queue a worker uses, you can find it using `SomeWorker.queue`. There is almost never a reason to manually override the queue name using `sidekiq_options queue: :some_queue`. -After adding a new queue, run `bin/rake +After adding a new worker, 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) +in installations that don't use routing rules. To learn more about potential changes, +read [Use routing rules by default and deprecate queue selectors for self-managed](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/596). + Additionally, run `bin/rake gitlab:sidekiq:sidekiq_queues_yml:generate` to regenerate `config/sidekiq_queues.yml`. diff --git a/doc/development/snowplow/dictionary.md b/doc/development/snowplow/dictionary.md deleted file mode 100644 index 02e9ba5ce20..00000000000 --- a/doc/development/snowplow/dictionary.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -redirect_to: 'https://metrics.gitlab.com/snowplow.html' -remove_date: '2021-12-28' ---- diff --git a/doc/development/snowplow/implementation.md b/doc/development/snowplow/implementation.md index 6da4896c7e7..439485c9e73 100644 --- a/doc/development/snowplow/implementation.md +++ b/doc/development/snowplow/implementation.md @@ -397,6 +397,7 @@ Before you test frontend events in development, you must: All URLs are pseudonymized. The entity identifier [replaces](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/javascript-tracker/javascript-tracker-v2/tracker-setup/other-parameters-2/#Setting_a_custom_page_URL_and_referrer_URL) personally identifiable information (PII). PII includes usernames, group, and project names. +Page titles are hardcoded as `GitLab` for the same reason. #### Snowplow Analytics Debugger Chrome Extension diff --git a/doc/development/snowplow/schemas.md b/doc/development/snowplow/schemas.md index f66e0566a9c..eb57e7d98a5 100644 --- a/doc/development/snowplow/schemas.md +++ b/doc/development/snowplow/schemas.md @@ -19,6 +19,7 @@ The [`StandardContext`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/g | `project_id` | **{dotted-circle}** | integer | | | `namespace_id` | **{dotted-circle}** | integer | | | `user_id` | **{dotted-circle}** | integer | User database record ID attribute. This file undergoes a pseudonymization process at the collector level. | +| `context_generated_at` | **{dotted-circle}** | string (date time format) | Timestamp indicating when context was generated. | | `environment` | **{check-circle}** | string (max 32 chars) | Name of the source environment, such as `production` or `staging` | | `source` | **{check-circle}** | string (max 32 chars) | Name of the source application, such as `gitlab-rails` or `gitlab-javascript` | | `plan` | **{dotted-circle}** | string (max 32 chars) | Name of the plan for the namespace, such as `free`, `premium`, or `ultimate`. Automatically picked from the `namespace`. | @@ -30,6 +31,7 @@ The [`StandardContext`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/g Frontend events include a [web-specific schema](https://docs.snowplowanalytics.com/docs/understanding-your-pipeline/canonical-event/#Web-specific_fields) provided by Snowplow. All URLs are pseudonymized. The entity identifier [replaces](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/javascript-tracker/javascript-tracker-v2/tracker-setup/other-parameters-2/#Setting_a_custom_page_URL_and_referrer_URL) personally identifiable information (PII). PII includes usernames, group, and project names. +Page titles are hardcoded as `GitLab` for the same reason. | Field Name | Required | Type | Description | |--------------------------|---------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------| @@ -105,7 +107,7 @@ information (PII). PII includes usernames, group, and project names. | `os_name` | **{dotted-circle}** | string | Name of operating system | | `os_timezone` | **{dotted-circle}** | string | Client operating system time zone | | `page_referrer` | **{dotted-circle}** | string | Referrer URL | -| `page_title` | **{dotted-circle}** | string | Page title | +| `page_title` | **{dotted-circle}** | string | To not expose personal identifying information, the page title is hardcoded as `GitLab` | | `page_url` | **{dotted-circle}** | string | Page URL | | `page_urlfragment` | **{dotted-circle}** | string | Fragment aka anchor | | `page_urlhost` | **{dotted-circle}** | string | Host aka domain | diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 0f768a51b66..fe0c4c13ba2 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -642,6 +642,11 @@ should either: It takes around one second to load tests that are using `fast_spec_helper` instead of 30+ seconds in case of a regular `spec_helper`. +WARNING: +To verify that code and its specs are well-isolated from Rails, run the spec +individually via `bin/rspec`. Don't use `bin/spring rspec` as it loads +`spec_helper` automatically. + ### `subject` and `let` variables The GitLab RSpec suite has made extensive use of `let`(along with its strict, non-lazy diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md deleted file mode 100644 index de024084c9c..00000000000 --- a/doc/development/testing_guide/ci.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../pipelines.md' -remove_date: '2022-01-12' ---- - -This file was moved to [another location](../pipelines.md). - -<!-- This redirect file can be deleted after <2022-01-12>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> 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 de34e6a1872..48157a961e1 100644 --- a/doc/development/testing_guide/end_to_end/feature_flags.md +++ b/doc/development/testing_guide/end_to_end/feature_flags.md @@ -118,6 +118,32 @@ view 'app/views/devise/passwords/new_edit_behind_ff.html.haml' do end ``` +## Working with resource classes + +If a resource class must behave differently when a feature flag is active, toggle a +variable with the name of the feature flag inside the class. This variable and condition +ensure all actions are handled appropriately. + +You can set this variable inside the `fabricate_via_api` call. For a consistent approach: + +- Use an `activated` check, not a deactivated one. +- Add the word `activated` to the end of a variable's name. +- Inside the `initialize` method, set the variable's default value. + +For example: + +```ruby +def initialize + name_of_the_future_flag_activated = false + ... +end +``` + +### Cleanup + +After the feature flag is removed, clean up the resource class and delete the variable. +All methods should use the condition procedures of the now-default state. + ## Running a scenario with a feature flag enabled It's also possible to run an entire scenario with a feature flag enabled, without having to edit diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index 57c8c3bf59c..1fc9bc8258a 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -170,6 +170,35 @@ Helm chart](https://gitlab.com/gitlab-org/charts/gitlab/), itself deployed with See [Review Apps](../review_apps.md) for more details about Review Apps. +### Run tests in parallel + +To run tests in parallel on CI, the [Knapsack](https://github.com/KnapsackPro/knapsack) +gem is used. Knapsack reports are generated automatically and stored in the `GCS` bucket +`knapsack-reports` in the `gitlab-qa-resources` project. The [`KnapsackReport`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/tools/knapsack_report.rb) +helper handles automated report generation and upload. + +## Test metrics + +For additional test health visibility, use a custom setup to export test execution +results to your [InfluxDb](https://influxdb.quality.gitlab.net/) instance, and visualize +results as [Grafana](https://dashboards.quality.gitlab.net/) dashboards. + +### Provisioning + +Provisioning of all components is performed by the +[`engineering-productivity-infrastructure`](https://gitlab.com/gitlab-org/quality/engineering-productivity-infrastructure) project. + +### Exporting metrics in CI + +Use these environment variables to configure metrics export: + +| Variable | Required | Information | +| -------- | -------- | ----------- | +| `QA_INFLUXDB_URL` | `true` | Should be set to `https://influxdb.quality.gitlab.net`. No default value. | +| `QA_INFLUXDB_TOKEN` | `true` | InfluxDB write token that can be found under `Influxdb auth tokens` document in `Gitlab-QA` `1Password` vault. No default value. | +| `QA_RUN_TYPE` | `false` | Arbitrary name for test execution, like `package-and-qa`. Automatically inferred from the project name for live environment test executions. No default value. | +| `QA_EXPORT_TEST_METRICS` | `false` | Flag to enable or disable metrics export. Defaults to `true`. | + ## Test reports ### Allure report 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 cb15dbe023f..bb214976926 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 @@ -34,7 +34,7 @@ This is a partial list of the [RSpec metadata](https://relishapp.com/rspec/rspec | `:packages` | The test requires a GitLab instance that has the [Package Registry](../../../administration/packages/#gitlab-package-registry-administration) enabled. | | `: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 in a specific context](execution_context_selection.md#quarantine-a-test-for-a-specific-environment). | | `:relative_url` | The test requires a GitLab instance to be installed under a [relative URL](../../../install/relative_url.md). | -| `: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. | +| `:reliable` | The test has been [promoted to a reliable test](https://about.gitlab.com/handbook/engineering/quality/quality-engineering/reliable-tests/#promoting-an-existing-test-to-reliable) meaning it passes consistently in all pipelines, including merge requests. | | `: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. | | `:requires_admin` | The test requires an administrator account. Tests with the tag are excluded when run against Canary and Production environments. | | `:requires_git_protocol_v2` | The test requires that Git protocol version 2 is enabled on the server. It's assumed to be enabled by default but if not the test can be skipped by setting `QA_CAN_TEST_GIT_PROTOCOL_V2` to `false`. | @@ -46,4 +46,4 @@ 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. | | `:testcase` | The link to the test case issue in the [GitLab Project Test Cases](https://gitlab.com/gitlab-org/gitlab/-/quality/test_cases). | | `:transient` | The test tests transient bugs. It is excluded by default. | -| `:issue`, `:issue_${num}` | Optional links to issues which might be related to the spec. Helps keeping track of related issues and can also be used by tools that create test reports. Currently added automatically to `Allure` test report. Multiple tags can be used by adding optional number postfix like `issue_1`, `issue_2` etc. | +| `:issue`, `:issue_${num}` | Optional links to issues which might be related to the spec. Helps keep track of related issues and can also be used by tools that create test reports. Currently added automatically to `Allure` test report. Multiple tags can be used by adding an optional numeric suffix like `issue_1`, `issue_2` etc. | diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 31a807697c5..aef83109b9b 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -14,6 +14,7 @@ For any of the following scenarios, the `start-review-app-pipeline` job would be - for merge requests with CI config changes - for merge requests with frontend changes +- for merge requests with changes to `{,ee/,jh/}{app/controllers}/**/*` - for merge requests with QA changes - for scheduled pipelines - the MR has the `pipeline:run-review-app` label set @@ -21,13 +22,13 @@ For any of the following scenarios, the `start-review-app-pipeline` job would be ## QA runs on Review Apps On every [pipeline](https://gitlab.com/gitlab-org/gitlab/pipelines/125315730) in the `qa` stage (which comes after the -`review` stage), the `review-qa-smoke` job is automatically started and it runs -the QA smoke suite. +`review` stage), the `review-qa-smoke` and `review-qa-reliable` jobs are automatically started. The `review-qa-smoke` runs +the QA smoke suite and the `review-qa-reliable` executes E2E tests identified as [reliable](https://about.gitlab.com/handbook/engineering/quality/quality-engineering/reliable-tests). You can also manually start the `review-qa-all`: it runs the full QA suite. After the end-to-end test runs have finished, [Allure reports](https://github.com/allure-framework/allure2) are generated and published by -the `allure-report-qa-smoke` and `allure-report-qa-all` jobs. A comment with links to the reports are added to the merge request. +the `allure-report-qa-smoke`, `allure-report-qa-reliable`, and `allure-report-qa-all` jobs. A comment with links to the reports are added to the merge request. ## Performance Metrics @@ -121,7 +122,7 @@ graph TD B[review-build-cng]; C[review-deploy]; D[CNG-mirror]; - E[review-qa-smoke]; + E[review-qa-smoke, review-qa-reliable]; A -->|once the `prepare` stage is done| B B -.->|triggers a CNG-mirror pipeline and wait for it to be done| D @@ -142,7 +143,7 @@ subgraph "3. gitlab `review` stage" end subgraph "4. gitlab `qa` stage" - E[review-qa-smoke<br><br>gitlab-qa runs the smoke suite against the Review App.] + E[review-qa-smoke, review-qa-reliable<br><br>gitlab-qa runs the smoke and reliable suites against the Review App.] end subgraph "CNG-mirror pipeline" @@ -196,7 +197,7 @@ subgraph "CNG-mirror pipeline" issue with a link to your merge request. Note that the deployment failure can reveal an actual problem introduced in your merge request (that is, this isn't necessarily a transient failure)! -- If the `review-qa-smoke` job keeps failing (note that we already retry it twice), +- If the `review-qa-smoke` or `review-qa-reliable` job keeps failing (note that we already retry them once), please check the job's logs: you could discover an actual problem introduced in your merge request. You can also download the artifacts to see screenshots of the page at the time the failures occurred. If you don't find the cause of the @@ -250,7 +251,7 @@ Leading indicators may be health check failures leading to restarts or majority The [Review Apps Overview dashboard](https://console.cloud.google.com/monitoring/classic/dashboards/6798952013815386466?project=gitlab-review-apps&timeDomain=1d) aids in identifying load spikes on the cluster, and if nodes are problematic or the entire cluster is trending towards unhealthy. -### Database related errors in `review-deploy` or `review-qa-smoke` +### Database related errors in `review-deploy`, `review-qa-smoke`, or `review-qa-reliable` Occasionally the state of a Review App's database could diverge from the database schema. This could be caused by changes to migration files or schema, such as a migration being renamed or deleted. This typically manifests in migration errors such as: diff --git a/doc/development/wikis.md b/doc/development/wikis.md index 994312da98e..deea3d38470 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -1,5 +1,4 @@ --- -type: reference, dev 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 @@ -91,8 +90,6 @@ Only some data is persisted in the database: The web UI uploads attachments through the REST API, which stores the files as commits in the wiki repository. -Prior to GitLab 11.3 attachments were stored outside of the repository, [see this issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475). - ## Related topics - [Gollum installation instructions](https://github.com/gollum/gollum/wiki/Installation) diff --git a/doc/gitlab-basics/command-line-commands.md b/doc/gitlab-basics/command-line-commands.md index fe69346c316..02e9117fa3a 100644 --- a/doc/gitlab-basics/command-line-commands.md +++ b/doc/gitlab-basics/command-line-commands.md @@ -1,15 +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/#assignments" -type: howto, reference +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Edit files through the command line **(FREE)** When [working with Git from the command line](start-using-git.md), you need to use more than just the Git commands. There are several basic commands that you should -learn, in order to make full use of the command line. +learn to make full use of the command line. ## Start working on your project diff --git a/doc/install/aws/gitlab_hybrid_on_aws.md b/doc/install/aws/gitlab_hybrid_on_aws.md index dbd23ff2b30..2183f351efd 100644 --- a/doc/install/aws/gitlab_hybrid_on_aws.md +++ b/doc/install/aws/gitlab_hybrid_on_aws.md @@ -238,7 +238,7 @@ If EKS node autoscaling is employed, it is likely that your average loading will **Deploy Now** -Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Meterials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. +Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Materials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. - **[Deploy Now: AWS Quick Start for 2 AZs](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-5K-Users-2AZs¶m_NumberOfAZs=2¶m_NodeInstanceType=c5.2xlarge¶m_NumberOfNodes=5¶m_MaxNumberOfNodes=5¶m_DBInstanceClass=db.r6g.2xlarge¶m_CacheNodes=2¶m_CacheNodeType=cache.m6g.xlarge¶m_GitalyInstanceType=m5.2xlarge¶m_NumberOfGitalyReplicas=2¶m_PraefectInstanceType=c5.large¶m_NumberOfPraefectReplicas=2)** - **[Deploy Now: AWS Quick Start for 3 AZs](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-5K-Users-3AZs¶m_NumberOfAZs=3¶m_NodeInstanceType=c5.2xlarge¶m_NumberOfNodes=5¶m_MaxNumberOfNodes=5¶m_DBInstanceClass=db.r6g.2xlarge¶m_CacheNodes=3¶m_CacheNodeType=cache.m6g.xlarge¶m_GitalyInstanceType=m5.2xlarge¶m_NumberOfGitalyReplicas=3¶m_PraefectInstanceType=c5.large¶m_NumberOfPraefectReplicas=3)** @@ -292,7 +292,7 @@ If EKS node autoscaling is employed, it is likely that your average loading will **Deploy Now** -Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Meterials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. +Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Materials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. - **[Deploy Now: AWS Quick Start for 3 AZs](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-10K-Users-3AZs¶m_NumberOfAZs=3¶m_NodeInstanceType=c5.4xlarge¶m_NumberOfNodes=9¶m_MaxNumberOfNodes=9¶m_DBInstanceClass=db.r6g.2xlarge¶m_CacheNodes=3¶m_CacheNodeType=cache.m6g.2xlarge¶m_GitalyInstanceType=m5.4xlarge¶m_NumberOfGitalyReplicas=3¶m_PraefectInstanceType=c5.large¶m_NumberOfPraefectReplicas=3)** @@ -345,7 +345,7 @@ If EKS node autoscaling is employed, it is likely that your average loading will **Deploy Now** -Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Meterials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. +Deploy Now links leverage the AWS Quick Start automation and only prepopulate the number of instances and instance types for the Quick Start based on the Bill of Materials below. You must provide appropriate input for all other parameters by following the guidance in the [Quick Start documentation's Deployment steps](https://aws-quickstart.github.io/quickstart-eks-gitlab/#_deployment_steps) section. - **[Deploy Now: AWS Quick Start for 3 AZs - 1/4 Scale EKS](https://us-east-2.console.aws.amazon.com/cloudformation/home?region=us-east-2#/stacks/quickcreate?templateUrl=https://aws-quickstart.s3.us-east-1.amazonaws.com/quickstart-eks-gitlab/templates/gitlab-entry-new-vpc.template.yaml&stackName=Gitlab-EKS-50K-Users-3AZs¶m_NumberOfAZs=3¶m_NodeInstanceType=c5.4xlarge¶m_NumberOfNodes=7¶m_MaxNumberOfNodes=9¶m_DBInstanceClass=db.r6g.8xlarge¶m_CacheNodes=3¶m_CacheNodeType=cache.m6g.2xlarge¶m_GitalyInstanceType=m5.16xlarge¶m_NumberOfGitalyReplicas=3¶m_PraefectInstanceType=c5.xlarge¶m_NumberOfPraefectReplicas=3)** diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index bec1f3e1142..8dbda7420b0 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -43,6 +43,7 @@ The following repository is self-contained in regard to enabling this pattern: [ - Using GitLab and AWS together. - Running GitLab infrastructure on AWS. +- Retrieving temporary credentials for access to AWS services. ## AWS known issues list @@ -62,7 +63,7 @@ When deploying a GitLab instance using the official AMI, the root password to th Instances running on Community Edition (CE) require a migration to Enterprise Edition (EE) in order to subscribe to the GitLab Premium or Ultimate plan. If you want to pursue a subscription, using the Free-forever plan of Enterprise Edition is the least disruptive method. NOTE: -Since any given GitLab upgrade might involve data disk updates or database schema upgrades, simply swapping out the AMI is not sufficent for taking upgrades. +Since any given GitLab upgrade might involve data disk updates or database schema upgrades, simply swapping out the AMI is not sufficent for taking upgrades. 1. Log in to the AWS Web Console, so that clicking the links in the following step take you directly to the AMI list. 1. Pick the edition you want: diff --git a/doc/install/aws/manual_install_aws.md b/doc/install/aws/manual_install_aws.md index 6dacd8df3e4..531a006dbf3 100644 --- a/doc/install/aws/manual_install_aws.md +++ b/doc/install/aws/manual_install_aws.md @@ -268,8 +268,7 @@ On the EC2 dashboard, look for Load Balancer in the left navigation bar: 1. Click **Configure Health Check** and set up a health check for your EC2 instances. 1. For **Ping Protocol**, select HTTP. 1. For **Ping Port**, enter 80. - 1. For **Ping Path**, enter `/users/sign_in`. (We use `/users/sign_in` as it's a public endpoint that does - not require authentication.) + 1. For **Ping Path** - we recommend that you [use the Readiness check endpoint](../../administration/load_balancer.md#readiness-check). You'll need to add [the VPC IP Adddress Range (CIDR)](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-groups.html#elb-vpc-nacl) to the [IP Allowlist](../../administration/monitoring/ip_whitelist.md) for the [Health Check endpoints](../../user/admin_area/monitoring/health_check.md) 1. Keep the default **Advanced Details** or adjust them according to your needs. 1. Click **Add EC2 Instances** - don't add anything as we will create an Auto Scaling Group later to manage instances for us. 1. Click **Add Tags** and add any tags you need. diff --git a/doc/install/docker.md b/doc/install/docker.md index 2efe6a3640b..ed5e1dda5d5 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -141,23 +141,25 @@ install, and upgrade your Docker-based GitLab installation: 1. Create a `docker-compose.yml` file (or [download an example](https://gitlab.com/gitlab-org/omnibus-gitlab/raw/master/docker/docker-compose.yml)): ```yaml - web: - image: 'gitlab/gitlab-ee:latest' - restart: always - hostname: 'gitlab.example.com' - environment: - GITLAB_OMNIBUS_CONFIG: | - external_url 'https://gitlab.example.com' - # Add any other gitlab.rb configuration here, each on its own line - ports: - - '80:80' - - '443:443' - - '22:22' - volumes: - - '$GITLAB_HOME/config:/etc/gitlab' - - '$GITLAB_HOME/logs:/var/log/gitlab' - - '$GITLAB_HOME/data:/var/opt/gitlab' - shm_size: '256m' + version: '3.6' + services: + web: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + external_url 'https://gitlab.example.com' + # Add any other gitlab.rb configuration here, each on its own line + ports: + - '80:80' + - '443:443' + - '22:22' + volumes: + - '$GITLAB_HOME/config:/etc/gitlab' + - '$GITLAB_HOME/logs:/var/log/gitlab' + - '$GITLAB_HOME/data:/var/opt/gitlab' + shm_size: '256m' ``` 1. Make sure you are in the same directory as `docker-compose.yml` and start @@ -176,22 +178,24 @@ HTTP and SSH port. Notice how the `GITLAB_OMNIBUS_CONFIG` variables match the `ports` section: ```yaml -web: - image: 'gitlab/gitlab-ee:latest' - restart: always - hostname: 'gitlab.example.com' - environment: - GITLAB_OMNIBUS_CONFIG: | - external_url 'http://gitlab.example.com:8929' - gitlab_rails['gitlab_shell_ssh_port'] = 2224 - ports: - - '8929:8929' - - '2224:22' - volumes: - - '$GITLAB_HOME/config:/etc/gitlab' - - '$GITLAB_HOME/logs:/var/log/gitlab' - - '$GITLAB_HOME/data:/var/opt/gitlab' - shm_size: '256m' +version: '3.6' +services: + web: + image: 'gitlab/gitlab-ee:latest' + restart: always + hostname: 'gitlab.example.com' + environment: + GITLAB_OMNIBUS_CONFIG: | + external_url 'http://gitlab.example.com:8929' + gitlab_rails['gitlab_shell_ssh_port'] = 2224 + ports: + - '8929:8929' + - '2224:22' + volumes: + - '$GITLAB_HOME/config:/etc/gitlab' + - '$GITLAB_HOME/logs:/var/log/gitlab' + - '$GITLAB_HOME/data:/var/opt/gitlab' + shm_size: '256m' ``` This is the same as using `--publish 8929:8929 --publish 2224:22`. @@ -653,3 +657,15 @@ purpose. ### Docker containers exhausts space due to the `json-file` Docker's [default logging driver is `json-file`](https://docs.docker.com/config/containers/logging/configure/#configure-the-default-logging-driver), which performs no log rotation by default. As a result of this lack of rotation, log files stored by the `json-file` driver can consume a significant amount of disk space for containers that generate a lot of output. This can lead to disk space exhaustion. To address this, use [`journald`](https://docs.docker.com/config/containers/logging/journald/) as the logging driver when available, or [another supported driver](https://docs.docker.com/config/containers/logging/configure/#supported-logging-drivers) with native rotation support. + +### Buffer overflow error when starting Docker + +If you receive this buffer overflow error, you should purge old log files in +`/var/log/gitlab`: + +```plaintext +buffer overflow detected : terminated +xargs: tail: terminated by signal 6 +``` + +Removing old log files helps fix the error, and ensures a clean startup of the instance. diff --git a/doc/install/next_steps.md b/doc/install/next_steps.md index b5cfbfc9bbb..1db2bf9b7b6 100644 --- a/doc/install/next_steps.md +++ b/doc/install/next_steps.md @@ -20,9 +20,11 @@ installation. 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 - GitLab Container Registry, every project can have its own space to store Docker +- [GitLab Registry](../administration/packages/container_registry.md): Set up the + GitLab Container Registry so every project can have its own space to store Docker images. +- [GitLab Dependency Proxy](../administration/packages/dependency_proxy.md): Set up the dependency + proxy so you can cache container images from Docker Hub for faster, more reliable builds. ## Security diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 037fbd7063d..665e80e6e00 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -4,10 +4,10 @@ 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 --- -# Installation requirements **(FREE SELF)** +# GitLab installation minimum requirements **(FREE SELF)** -This page includes useful information on the supported Operating Systems as well -as the hardware requirements that are needed to install and use GitLab. +This page includes information about both the supported operating systems and +the minimum requirements needed to install and use GitLab. ## Operating Systems @@ -15,12 +15,13 @@ as the hardware requirements that are needed to install and use GitLab. - Ubuntu (16.04/18.04/20.04) - Debian (9/10) -- CentOS (7/8) +- AlmaLinux (8) +- CentOS (7) - openSUSE Leap (15.2) - SUSE Linux Enterprise Server (12 SP2/12 SP5) -- Red Hat Enterprise Linux (please use the CentOS packages and instructions) -- Scientific Linux (please use the CentOS packages and instructions) -- Oracle Linux (please use the CentOS packages and instructions) +- Red Hat Enterprise Linux (use the AlmaLinux or CentOS instructions) +- Scientific Linux (use the CentOS instructions) +- Oracle Linux (use the CentOS instructions) For the installation options, see [the main installation page](index.md). diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index db7e7d74efe..2fc80aa1769 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -6,10 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Integrate your GitLab server with Bitbucket Cloud **(FREE SELF)** -NOTE: -Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an -earlier version, you must explicitly enable it. - You can set up Bitbucket.org as an OAuth 2.0 provider to use your Bitbucket.org account credentials to sign in to GitLab. You can also import your projects from Bitbucket.org. diff --git a/doc/integration/datadog.md b/doc/integration/datadog.md index 89e08d330e8..4be0089703a 100644 --- a/doc/integration/datadog.md +++ b/doc/integration/datadog.md @@ -32,9 +32,11 @@ project, group, or instance level: 1. Scroll to **Add an integration**, and select **Datadog**. 1. Select **Active** to enable the integration. 1. Specify the [**Datadog site**](https://docs.datadoghq.com/getting_started/site/) to send data to. +1. Provide your Datadog **API key**. +<!-- 1. Optional. Select **Enable logs collection** to enable logs collection for the output of jobs. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346339) in GitLab 14.8.) --> +<!-- TODO: uncomment the archive_trace_events field once :datadog_integration_logs_collection is rolled out. Rollout issue: https://gitlab.com/gitlab-org/gitlab/-/issues/346339 --> 1. Optional. To override the API URL used to send data directly, provide an **API URL**. Used only in advanced scenarios. -1. Provide your Datadog **API key**. 1. Optional. If you use more than one GitLab instance, provide a unique **Service** name to differentiate between your GitLab instances. 1. Optional. If you use groups of GitLab instances (such as staging and production diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 8461aca8c8d..7356574a33e 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -478,6 +478,8 @@ The following are some available Rake tasks: | [`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. | | [`sudo gitlab-rake gitlab:elastic:list_pending_migrations`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | List pending migrations. Pending migrations include those that have not yet started, have started but not finished, and those that are halted. | | [`sudo gitlab-rake gitlab:elastic:estimate_cluster_size`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Get an estimate of cluster size based on the total repository size. | +| [`sudo gitlab-rake gitlab:elastic:enable_search_with_elasticsearch`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Enable advanced search with Elasticsearch. | +| [`sudo gitlab-rake gitlab:elastic:disable_search_with_elasticsearch`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/tasks/gitlab/elastic.rake) | Disables advanced search with Elasticsearch. | ### Environment variables diff --git a/doc/integration/jenkins.md b/doc/integration/jenkins.md index 822530775e5..bae52622966 100644 --- a/doc/integration/jenkins.md +++ b/doc/integration/jenkins.md @@ -4,100 +4,80 @@ group: Integrations info: To 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 **(FREE)** +# Jenkins integration **(FREE)** > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/246756) to GitLab Free in 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. +You can trigger a build in Jenkins when you push code to your repository or +create a merge request in GitLab. The Jenkins pipeline status displays on merge +requests widgets and on the GitLab project's home page. -To better understand the GitLab Jenkins integration, watch the following video: +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview of the Jenkins integration for GitLab, see +[GitLab workflow with Jira issues and Jenkins pipelines](https://youtu.be/Jn-_fyra7xQ). -- [GitLab workflow with Jira issues and Jenkins pipelines](https://youtu.be/Jn-_fyra7xQ) +Use the Jenkins integration when: -Use the Jenkins integration with GitLab when: - -- You plan to migrate your CI from Jenkins to [GitLab CI/CD](../ci/index.md) in the future, but -need an interim solution. -- You're invested in [Jenkins Plugins](https://plugins.jenkins.io/) and choose to keep using Jenkins -to build your apps. - -For a real use case, read the blog post [Continuous integration: From Jenkins to GitLab using Docker](https://about.gitlab.com/blog/2017/07/27/docker-my-precious/). - -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/). +- You plan to migrate your CI from Jenkins to [GitLab CI/CD](../ci/index.md) + in the future, but need an interim solution. +- You're invested in [Jenkins plugins](https://plugins.jenkins.io/) and choose + to keep using Jenkins to build your apps. NOTE: -This documentation focuses only on how to **configure** a Jenkins *integration* with +This documentation focuses only on how to configure a Jenkins *integration* with GitLab. Learn how to set up Jenkins [on your local machine](../development/integrations/jenkins.md) -in our developer documentation, and how to **migrate** from Jenkins to GitLab CI/CD in our +in the developer documentation, and how to migrate from Jenkins to GitLab CI/CD in the [Migrating from Jenkins](../ci/migration/jenkins.md) documentation. -## Configure GitLab integration with 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. - -### GitLab requirements - -- [Grant Jenkins permission to GitLab project](#grant-jenkins-access-to-gitlab-project) -- [Configure GitLab API access](#configure-gitlab-api-access) -- [Configure the GitLab project](#configure-the-gitlab-project) - -### Jenkins requirements +The Jenkins integration requires configuration in both GitLab and Jenkins. -- [Configure the Jenkins server](#configure-the-jenkins-server) -- [Configure the Jenkins project](#configure-the-jenkins-project) +## Grant Jenkins access to the GitLab project -## Grant Jenkins access to GitLab project - -Grant a GitLab user access to the select GitLab projects. +Grant a GitLab user access to the relevant GitLab projects. 1. Create a new GitLab user, or choose an existing GitLab user. 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 stops working. + deleted, the Jenkins integration stops working. 1. Grant the user permission to the GitLab projects. - If you're integrating Jenkins with many GitLab projects, consider granting the user the global - Administrator role. Otherwise, add the user to each project, and grant the Developer role. + If you're integrating Jenkins with many GitLab projects, consider granting the + user the administrator access level. Otherwise, add the user to each project + and grant the Developer role. -## Configure GitLab API access +## Grant Jenkins access to the GitLab API -Create a personal access token to authorize Jenkins' access to GitLab. +Create a personal access token to authorize Jenkins to access GitLab. 1. Sign in to GitLab as the user to be used with Jenkins. -1. In the top-right corner, select your avatar. +1. On the top bar, in the top right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Access Tokens**. -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) section. +1. Create a [personal access token](../user/profile/personal_access_tokens.md) and + select the **API** scope. +1. Copy the personal access token. You need it to [configure the Jenkins server](#configure-the-jenkins-server). ## Configure the Jenkins server 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**. +1. On the Jenkins server, select **Manage Jenkins > Manage Plugins**. 1. Install the [Jenkins GitLab Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+Plugin). -1. Go to **Manage Jenkins > Configure System**. -1. In the **GitLab** section, check the **Enable authentication for '/project' end-point** checkbox. -1. Click **Add**, then choose **Jenkins Credential Provider**. -1. Choose **GitLab API token** as the token type. -1. Enter the GitLab personal access token's value in the **API Token** field and click **Add**. -1. Enter the GitLab server's URL in the **GitLab host URL** field. -1. Click **Test Connection**, ensuring the connection is successful before proceeding. - -For more information, see GitLab Plugin documentation about -[Jenkins-to-GitLab authentication](https://github.com/jenkinsci/gitlab-plugin#jenkins-to-gitlab-authentication). +1. Select **Manage Jenkins > Configure System**. +1. In the **GitLab** section, select **Enable authentication for '/project' end-point**. +1. Select **Add**, then choose **Jenkins Credential Provider**. +1. Select **GitLab API token** as the token type. +1. Enter the GitLab personal access token's value in **API Token** and select **Add**. +1. Enter the GitLab server's URL in **GitLab host URL**. +1. To test the connection, select **Test Connection**. - +  + +For more information, see +[Jenkins-to-GitLab authentication](https://github.com/jenkinsci/gitlab-plugin#jenkins-to-gitlab-authentication). ## Configure the Jenkins project @@ -105,15 +85,15 @@ 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 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. -1. Check the following checkboxes: +1. Select **Freestyle** or **Pipeline** and select **OK**. + 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 list. +1. Select **Build when a change is pushed to GitLab**. +1. Select the following checkboxes: - **Accepted Merge Request Events** - **Closed Merge Request Events** -1. Specify how build status is reported to GitLab: +1. Specify how the build status is reported to GitLab: - If you created a **Freestyle** project, in the **Post-build Actions** section, choose **Publish build status to GitLab**. - If you created a **Pipeline** project, you must use a Jenkins Pipeline script to update the status on @@ -143,39 +123,49 @@ Set up the Jenkins project you intend to run your build on. Configure the GitLab integration with Jenkins in one of the following ways. -### Recommended Jenkins integration +### Configure a Jenkins integration (recommended) GitLab recommends this approach for Jenkins integrations because it is easier to configure -than the [webhook integration](#webhook-integration). +than the [webhook integration](#configure-a-webhook). -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. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Jenkins**. +1. Select the **Active** checkbox. 1. Select the events you want GitLab to trigger a Jenkins build for: - Push - Merge request - Tag push -1. Enter the **Jenkins URL**. +1. Enter the **Jenkins server URL**. 1. Enter the **Project name**. The project name should be URL-friendly, where spaces are replaced with underscores. To ensure the project name is valid, copy it from your browser's address bar while viewing the Jenkins project. -1. Enter the **Username** and **Password** if your Jenkins server requires - authentication. -1. Click **Test settings and save changes**. GitLab tests the connection to Jenkins. +1. If your Jenkins server requires + authentication, enter the **Username** and **Password**. +1. To test the connection to Jenkins, select **Test settings**. +1. Select **Save changes**. -### Webhook integration +### Configure a 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 the configuration of your Jenkins job, in the GitLab configuration section, select **Advanced**. +1. Under **Secret Token**, select **Generate**. +1. Copy the token, and save the job configuration. 1. In GitLab, create a webhook for your project, enter the trigger URL - (such as `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. + (such as `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in **Secret Token**. +1. To test the webhook, select **Test**. + +## Related topics + +- For a real use case, read the blog post + [Continuous integration: From Jenkins to GitLab using Docker](https://about.gitlab.com/blog/2017/07/27/docker-my-precious/). +- See the ['GitLab vs. Jenkins' comparison page](https://about.gitlab.com/devops-tools/jenkins-vs-gitlab/) + for information on how moving to a single application for the entire software development + lifecycle can decrease hours spent on maintaining toolchains by 10% or more. ## Troubleshooting @@ -188,24 +178,31 @@ If you get this error message while configuring GitLab, the following are possib - The Jenkins instance is at a local address and is not included in the [GitLab installation's allowlist](../security/webhooks.md#allowlist-for-local-requests). - The credentials for the Jenkins instance do not have sufficient access or are invalid. -- The **Enable authentication for ‘/project’ end-point checkbox** is not selected in your [Jenkin's plugin configuration](#configure-the-jenkins-server). +- The **Enable authentication for ‘/project’ end-point** checkbox is not selected in your [Jenkin's plugin configuration](#configure-the-jenkins-server). ### Error in merge requests - "Could not connect to the CI server" -This integration relies on Jenkins reporting the build status back to GitLab via -the [Commit Status API](../api/commits.md#commit-status). +You might get the `Could not connect to the CI server` error if GitLab did not +receive a build status update from Jenkins via the [Commit Status API](../api/commits.md#commit-status). + +This issue occurs when Jenkins is not properly +configured or there is an error reporting the status via the API. -The error 'Could not connect to the CI server' usually means that GitLab did not -receive a build status update via the API. Either Jenkins was not properly -configured or there was an error reporting the status via the API. +To fix this issue, ensure you: -1. [Configure the Jenkins server](#configure-the-jenkins-server) for GitLab API access +1. [Configure the Jenkins server](#configure-the-jenkins-server) for GitLab API access. 1. [Configure the Jenkins project](#configure-the-jenkins-project), including the 'Publish build status to GitLab' post-build action. -### Merge Request event does not trigger a Jenkins Pipeline +### Merge request event does not trigger a Jenkins pipeline -Check [service hook logs](../user/project/integrations/overview.md#troubleshooting-integrations) for request failures or check the `/var/log/gitlab/gitlab-rails/production.log` file for messages like: +This issue can occur when the request exceeds the +[webhook timeout](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered), +which is set to 10 seconds by default. + +Check the [service hook logs](../user/project/integrations/overview.md#troubleshooting-integrations) +for request failures or check the `/var/log/gitlab/gitlab-rails/production.log` +file for messages like: ```plaintext WebHook Error => Net::ReadTimeout @@ -217,30 +214,38 @@ or WebHook Error => execution expired ``` -If those are present, the request is exceeding the -[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 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`), -[webhook requests may be timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered): +Or check for duplicate messages in `/var/log/gitlab/gitlab-rail`, like: ```plaintext 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start ``` +To fix this issue: + +1. Increase the `gitlab_rails['webhook_timeout']` value in the `gitlab.rb` + configuration file. +1. [Restart](../administration/restart_gitlab.md) GitLab: + + ```shell + gitlab-ctl reconfigure + ``` + ### Enable job logs in Jenkins -When troubleshooting an integration issue, it is useful to enable job logs in Jenkins to see more details about what is happening under the hood. +To troubleshoot an integration issue, you can enable job logs in Jenkins to get +more details about your builds. + To enable job logs in Jenkins: 1. Go to **Dashboard > Manage Jenkins > System Log**. 1. Select **Add new log recorder**. 1. Enter a name for the log recorder. -1. On the next screen, select **Add** and enter `org.jenkinsci.plugins.workflow.job` in the text field. +1. On the next screen, select **Add** and enter `org.jenkinsci.plugins.workflow.job`. 1. Make sure that the Log Level is **All** and select **Save**. -Now, after you run a build, you can go to the loggers page (**Dashboard > Manage Jenkins > System Log**), select your logger, and check the logs. +To view your logs: + +1. Run a build. +1. Go to **Dashboard > Manage Jenkins > System Log**. +1. Select your logger and check the logs. diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 0f9bf3ba1d1..04a02b8fa68 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" --- @@ -9,9 +9,8 @@ info: "To determine the technical writer assigned to the Stage/Group associated GitLab can integrate with [Kerberos](https://web.mit.edu/kerberos/) as an authentication mechanism. WARNING: -GitLab CI/CD does not work with a Kerberos-enabled GitLab instance due to an unresolved -[bug in Git CLI](https://lore.kernel.org/git/YKNVop80H8xSTCjz@coredump.intra.peff.net/T/#mab47fd7dcb61fee651f7cc8710b8edc6f62983d5) -that fails to use job token authentication from the GitLab Runners. +GitLab CI/CD doesn't work with a Kerberos-enabled GitLab instance unless the integration is +[set to use a dedicated port](#http-git-access-with-kerberos-token-passwordless-authentication). ## Overview @@ -235,19 +234,23 @@ know the `libcurl` version installed, run `curl-config --version`. ### HTTP Git access with Kerberos token (passwordless authentication) -#### Support for Git before 2.4 - -Until Git version 2.4, the `git` command uses only the `negotiate` authentication +Because of [a bug in current Git versions](https://lore.kernel.org/git/YKNVop80H8xSTCjz@coredump.intra.peff.net/T/#mab47fd7dcb61fee651f7cc8710b8edc6f62983d5), +the `git` CLI command uses only the `negotiate` authentication method if the HTTP server offers it, even if this method fails (such as when the client does not have a Kerberos token). It is thus not possible to fall back -to username/password (also known as `basic`) authentication if Kerberos +to an embedded username and password (also known as `basic`) authentication if Kerberos authentication fails. For GitLab users to be able to use either `basic` or `negotiate` authentication -with older Git versions, it is possible to offer Kerberos ticket-based +with current Git versions, it is possible to offer Kerberos ticket-based authentication on a different port (for example, `8443`) while the standard port offers only `basic` authentication. +NOTE: +[Git 2.4 and later](https://github.com/git/git/blob/master/Documentation/RelNotes/2.4.0.txt#L225-L228) supports falling back to `basic` authentication if the +username and password is passed interactively or through a credentials manager. It fails to fall back when the username and password is passed as part of the URL instead. For example, +this can happen in GitLab CI/CD jobs that [authenticate with the CI/CD job token](../ci/jobs/ci_job_token.md). + **For source installations with HTTPS** 1. Edit the NGINX configuration file for GitLab diff --git a/doc/integration/mattermost/index.md b/doc/integration/mattermost/index.md index 97da971dd75..02fe0f4ea71 100644 --- a/doc/integration/mattermost/index.md +++ b/doc/integration/mattermost/index.md @@ -340,7 +340,8 @@ Below is a list of Mattermost versions for GitLab 11.10 and later: | 14.3 | 5.38 | | 14.4 | 5.39 | | 14.5 | 5.39 | -| 14.6 | 6.1 | +| 14.6 | 6.1 | +| 14.7 | 6.2 | - GitLab 14.5 remained on Mattermost 5.39 - GitLab 14.6 updates to Mattermost 6.1 instead of 6.0 diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index af715e47ab9..ff144d9985b 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index dd51d823109..4c05f94148c 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -46,10 +46,6 @@ GitLab supports the following OmniAuth providers. ## Configure initial settings -NOTE: -In GitLab 11.4 and later, OmniAuth is enabled by default. If you're using an -earlier version, you must explicitly enable it. - Before you configure the OmniAuth provider, configure the settings that are common for all providers. @@ -153,7 +149,7 @@ To enable or disable an OmniAuth provider: ## Disable OmniAuth -In GitLab 11.4 and later, OmniAuth is enabled by default. However, OmniAuth only works +OmniAuth is enabled by default. However, OmniAuth only works if providers are configured and [enabled](#enable-or-disable-sign-in-with-an-omniauth-provider-without-disabling-import-sources). If OmniAuth providers are causing problems even when individually disabled, you @@ -385,3 +381,9 @@ then override the icon in one of two ways: ... } ``` + +## Limitations + +Most supported OmniAuth providers don't support Git over HTTP password authentication. +The only exception is [Atlassian Crowd](../administration/auth/crowd.md) (since GitLab [13.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46935)). +As a workaround, you can authenticate using a [personal access token](../user/profile/personal_access_tokens.md). diff --git a/doc/integration/openid_connect_provider.md b/doc/integration/openid_connect_provider.md index 54d4a5b6bb7..e85231d1c25 100644 --- a/doc/integration/openid_connect_provider.md +++ b/doc/integration/openid_connect_provider.md @@ -47,20 +47,19 @@ The following user information is shared with clients: | Claim | Type | Description | |:-----------------|:----------|:------------| -| `sub` | `string` | The ID of the user -| `sub_legacy` | `string` | An opaque token that uniquely identifies the user<br><br>**Deprecation notice:** this token isn't stable because it's tied to the Rails secret key base, and is provided only for migration to the new stable `sub` value available from GitLab 11.1 -| `auth_time` | `integer` | The timestamp for the user's last authentication -| `name` | `string` | The user's full name -| `nickname` | `string` | The user's GitLab username -| `email` | `string` | The user's email address<br>This is the user's *primary* email address if the application has access to the `email` claim and the user's *public* email address otherwise -| `email_verified` | `boolean` | Whether the user's email address was verified -| `website` | `string` | URL for the user's website -| `profile` | `string` | URL for the user's GitLab profile -| `picture` | `string` | URL for the user's GitLab avatar -| `groups` | `array` | Paths for the groups the user is a member of, either directly or through an ancestor group. -| `groups_direct` | `array` | Paths for the groups the user is a direct member of. -| `https://gitlab.org/claims/groups/owner` | `array` | Names of the groups the user is a direct member of with Owner role -| `https://gitlab.org/claims/groups/maintainer` | `array` | Names of the groups the user is a direct member of with Maintainer role -| `https://gitlab.org/claims/groups/developer` | `array` | Names of the groups the user is a direct member of with Developer role +| `sub` | `string` | The ID of the user | +| `auth_time` | `integer` | The timestamp for the user's last authentication | +| `name` | `string` | The user's full name | +| `nickname` | `string` | The user's GitLab username | +| `email` | `string` | The user's email address<br>This is the user's *primary* email address if the application has access to the `email` claim and the user's *public* email address otherwise | +| `email_verified` | `boolean` | Whether the user's email address was verified | +| `website` | `string` | URL for the user's website | +| `profile` | `string` | URL for the user's GitLab profile | +| `picture` | `string` | URL for the user's GitLab avatar | +| `groups` | `array` | Paths for the groups the user is a member of, either directly or through an ancestor group. | +| `groups_direct` | `array` | Paths for the groups the user is a direct member of. | +| `https://gitlab.org/claims/groups/owner` | `array` | Names of the groups the user is a direct member of with Owner role | +| `https://gitlab.org/claims/groups/maintainer` | `array` | Names of the groups the user is a direct member of with Maintainer role | +| `https://gitlab.org/claims/groups/developer` | `array` | Names of the groups the user is a direct member of with Developer role | The claims `sub`, `sub_legacy`, `email`, `email_verified` and `groups_direct` are included in the ID token. All other claims are available from the `/oauth/userinfo` endpoint used by OIDC clients. diff --git a/doc/integration/saml.md b/doc/integration/saml.md index 70d6932b9eb..61d09b4e173 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -917,8 +917,10 @@ You may also find the [SAML Tracer](https://addons.mozilla.org/en-US/firefox/add ### Invalid audience This error means that the IdP doesn't recognize GitLab as a valid sender and -receiver of SAML requests. Make sure to add the GitLab callback URL to the approved -audiences of the IdP server. +receiver of SAML requests. Make sure to: + +- Add the GitLab callback URL to the approved audiences of the IdP server. +- Avoid trailing whitespace in the `issuer` string. ### Missing claims, or `Email can't be blank` errors diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 6f0027aedc7..b2e5f7b4b7d 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -7,8 +7,13 @@ type: reference, how-to # Sourcegraph integration **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16556) in GitLab 12.5. -> - Note that this integration is in BETA and deployed [behind a feature flag](#enable-the-sourcegraph-feature-flag) disabled by default. Self-managed instances can opt to enable it. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16556) in GitLab 12.5 [with a flag](../administration/feature_flags.md) named `sourcegraph`. Disabled by default. +> - Enabled on GitLab.com in GitLab 12.5. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73116) in GitLab 14.8. + +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `sourcegraph`. +On GitLab.com, this feature is available for public projects only. [Sourcegraph](https://sourcegraph.com) provides code intelligence features, natively integrated into the GitLab UI. @@ -26,41 +31,9 @@ you can choose to enable Sourcegraph [through your user preferences](#enable-sou ## Set up for self-managed GitLab instances **(FREE SELF)** Before you can enable Sourcegraph code intelligence in GitLab you must: +configure a Sourcegraph instance with your GitLab instance as an external service. -- Enable the `sourcegraph` feature flag for your GitLab instance. -- Configure a Sourcegraph instance with your GitLab instance as an external service. - -### Enable the Sourcegraph feature flag - -NOTE: -If you are running a self-managed instance, the Sourcegraph integration is unavailable -unless the feature flag `sourcegraph` is enabled. This can be done from the Rails console -by instance administrators. - -Use these commands to start the Rails console: - -```shell -# Omnibus GitLab -gitlab-rails console - -# Installation from source -cd /home/git/gitlab -sudo -u git -H bin/rails console -e production -``` - -Then run the following command to enable the feature flag: - -```ruby -Feature.enable(:sourcegraph) -``` - -You can also enable the feature flag only for specific projects with: - -```ruby -Feature.enable(:sourcegraph, Project.find_by_full_path('my_group/my_project')) -``` - -### Set up a self-managed Sourcegraph instance +### Set up a self-managed Sourcegraph instance **(FREE SELF)** 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. diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index 68a0d492c5d..7533646aa34 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Error Tracking **(FREE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/169) in GitLab 11.8. - Error Tracking allows developers to easily discover and view the errors that their application may be generating. By surfacing error information where the code is being developed, efficiency and awareness can be increased. ## How error tracking works diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index 49898d2e904..b0a180b5635 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Feature Flags **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) from GitLab Premium to GitLab Free in 13.5. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) from GitLab Premium to GitLab Free in 13.5. With Feature Flags, you can deploy your application's new features to production in smaller batches. You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery. diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 64dea795d3c..ada1f426dd8 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -47,8 +47,6 @@ To create an incident from the Issues List: ### Create incidents automatically **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in GitLab 11.11. - With at least the Maintainer [role](../../user/permissions.md), you can enable GitLab to create incident automatically whenever an alert is triggered: diff --git a/doc/operations/index.md b/doc/operations/index.md index ec54b6c57b9..5a83e47b556 100644 --- a/doc/operations/index.md +++ b/doc/operations/index.md @@ -9,11 +9,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab provides a variety of tools to help operate and maintain your applications. -## Measure reliability and stability with metrics +## Measure reliability and stability with metrics (DEPRECATED) + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346485) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346485) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. Metrics help you understand the health and performance of your infrastructure, applications, and systems by providing insights into your application's reliability, -stability, and performance. GitLab provides a dashboard out-of-the-box, which you +stability, and performance. GitLab provides a default dashboard that you can extend with custom metrics, and augment with additional custom dashboards. You can track the metrics that matter most to your team, generate automated alerts when performance degrades, and manage those alerts - all within GitLab. @@ -30,13 +36,13 @@ performance degrades, and manage those alerts - all within GitLab. GitLab helps reduce alert fatigue for IT responders by providing tools to identify issues across multiple systems and aggregate alerts in a centralized place. Your team needs a single, central interface where they can easily investigate alerts -using metrics and logs, and promote the critical alerts to incidents. +and promote the critical alerts to incidents. Are your alerts too noisy? Alerts configured on GitLab metrics can configured and fine-tuned in GitLab immediately following a fire-fight. - [Manage alerts and incidents](incident_management/index.md) in GitLab. -- [Configure alerts for metrics](metrics/alerts.md) in GitLab. +- [Configure alerts for metrics](metrics/alerts.md) in GitLab. (DEPRECATED) - Create a [status page](incident_management/status_page.md) to communicate efficiently to your users during an incident. @@ -51,7 +57,13 @@ and the work required to fix them - all without leaving GitLab. - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). -## Trace application health and performance +## Trace application health and performance (DEPRECATED) + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346485) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346485) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. Application tracing in GitLab is a way to measure an application's performance and health while it's running. After configuring your application to enable tracing, you @@ -65,7 +77,13 @@ microservices-based distributed systems - and displays results within GitLab. - [Trace the performance and health](tracing.md) of a deployed application. -## Aggregate and store logs +## Aggregate and store logs (DEPRECATED) + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346485) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346485) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. Developers need to troubleshoot application changes in development, and incident responders need aggregated, real-time logs when troubleshooting problems with diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 44999ad7cd6..712ee04e916 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -19,8 +19,7 @@ Alerts are not currently supported for [Prometheus cluster integrations](../../u ## External Prometheus instances -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9258) in GitLab Ultimate 11.8. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to GitLab Free in 12.10. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to GitLab Free in 12.10. For manually configured Prometheus servers, GitLab provides a notify endpoint for use with Prometheus webhooks. If you have manual configuration enabled, an @@ -61,8 +60,6 @@ Prometheus server to use the ## Trigger actions from alerts **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in GitLab 11.11. - 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 2be26e843c4..295c146f0d5 100644 --- a/doc/operations/metrics/dashboards/default.md +++ b/doc/operations/metrics/dashboards/default.md @@ -4,7 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# GitLab-defined metrics dashboards (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab provides some dashboards out-of-the-box for any project with [Prometheus available](../../../user/project/integrations/prometheus.md). You can diff --git a/doc/operations/metrics/dashboards/develop.md b/doc/operations/metrics/dashboards/develop.md index 28a4488014a..38f375c40a6 100644 --- a/doc/operations/metrics/dashboards/develop.md +++ b/doc/operations/metrics/dashboards/develop.md @@ -4,7 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Developing templates for custom dashboards (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab provides a template to make it easier for you to create templates for [custom dashboards](index.md). Templates provide helpful guidance and diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index d59f72f2a91..9a75703a2f1 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -4,9 +4,14 @@ group: Monitor info: To 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 **(FREE)** +# Custom dashboards (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. By default, all projects include a [GitLab-defined Prometheus dashboard](default.md), which includes a few key metrics, but you can also define your own custom dashboards. diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md index 140e18b5b13..9b015760fe9 100644 --- a/doc/operations/metrics/dashboards/panel_types.md +++ b/doc/operations/metrics/dashboards/panel_types.md @@ -4,7 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Panel types for dashboards (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. The below panel types are supported in monitoring dashboards. diff --git a/doc/operations/metrics/dashboards/settings.md b/doc/operations/metrics/dashboards/settings.md index f14d326a0d3..f4c37718c52 100644 --- a/doc/operations/metrics/dashboards/settings.md +++ b/doc/operations/metrics/dashboards/settings.md @@ -4,7 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Dashboard settings (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. You can configure your [Monitoring dashboard](../index.md) to display the time zone of your choice, and the links of your choice. diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md index 20071300dec..8ccd334dac3 100644 --- a/doc/operations/metrics/dashboards/templating_variables.md +++ b/doc/operations/metrics/dashboards/templating_variables.md @@ -4,9 +4,14 @@ group: Monitor info: To 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 **(FREE)** +# Templating variables for metrics dashboards (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214539) in GitLab 13.0. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214539) in GitLab 13.0. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. Templating variables can be used to make your metrics dashboard more versatile. diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index fa79524883d..0008706df40 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -4,7 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Using variables (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. ## Query variables diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index 8068a66d5c4..9d1c270388e 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -4,7 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Dashboard YAML properties (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. Dashboards have several components: diff --git a/doc/operations/tracing.md b/doc/operations/tracing.md index 1593607cc98..09a31c12bf4 100644 --- a/doc/operations/tracing.md +++ b/doc/operations/tracing.md @@ -4,10 +4,14 @@ group: Monitor info: To 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 **(FREE)** +# Tracing (DEPRECATED) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7903) in GitLab 11.5. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42645) from GitLab Ultimate to GitLab Free in 13.5. +> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346540) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346540) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. Tracing provides insight into the performance and health of a deployed application, tracking each function or microservice that handles a given request. Tracing makes it easy to understand the diff --git a/doc/policy/alpha-beta-support.md b/doc/policy/alpha-beta-support.md index be634bbf7be..ba988b38af2 100644 --- a/doc/policy/alpha-beta-support.md +++ b/doc/policy/alpha-beta-support.md @@ -4,6 +4,8 @@ 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 --- +<!-- any changes made to this page should be reflected in https://about.gitlab.com/support/statement-of-support.html#alpha--beta-features and https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga --> + # Support for Alpha, Beta, and Generally Available Features **(PREMIUM)** Some GitLab features are released as [Alpha or Beta versions](https://about.gitlab.com/support/statement-of-support.html#alpha--beta-features) which are not fully supported. All other features are considered to be Generally Available (GA). @@ -30,7 +32,7 @@ Characteristics of beta features: - Features and functions are not likely to change. - Data loss is not likely. -Your Support Contract provides **best-efforts** support for Beta features, with the expectation that issues will require extra time and assistance from development to troubleshoot. +Your Support Contract provides **commercially-reasonable effort** support for Beta features, with the expectation that issues will require extra time and assistance from development to troubleshoot. ## Generally Available (GA) diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md index 425275a0370..c37853ffe81 100644 --- a/doc/push_rules/push_rules.md +++ b/doc/push_rules/push_rules.md @@ -14,10 +14,6 @@ GitLab already offers [protected branches](../user/project/protected_branches.md cases when you need some specific rules. Some common scenarios: preventing Git tag removal, or enforcing a special format for commit messages. -INFO: -Get access to push rules and more with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-push-rules-docs). - Push rules are [pre-receive Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) you can enable in a user-friendly interface. They are defined either: @@ -147,76 +143,80 @@ Feature.disable(:reject_unsigned_commits_by_gitlab) > Moved to GitLab Premium in 13.9. -Secrets such as credential files, SSH private keys, and other files containing secrets should never be committed to source control. -GitLab enables you to turn on a predefined denylist of files which can't be -pushed to a repository. The list stops those commits from reaching the remote repository. - -By selecting the checkbox *Prevent committing secrets to Git*, GitLab prevents -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: -Files already committed aren't restricted by this push rule. - -Below is an example list of what GitLab rejects with these regular expressions: - -```shell -##################### -# AWS CLI credential blobs -##################### -.aws/credentials -aws/credentials -homefolder/aws/credentials - -##################### -# Private RSA SSH keys -##################### -/ssh/id_rsa -/.ssh/personal_rsa -/config/server_rsa -id_rsa -.id_rsa - -##################### -# Private DSA SSH keys -##################### -/ssh/id_dsa -/.ssh/personal_dsa -/config/server_dsa -id_dsa -.id_dsa - -##################### -# Private ed25519 SSH keys -##################### -/ssh/id_ed25519 -/.ssh/personal_ed25519 -/config/server_ed25519 -id_ed25519 -.id_ed25519 - -##################### -# Private ECDSA SSH keys -##################### -/ssh/id_ecdsa -/.ssh/personal_ecdsa -/config/server_ecdsa -id_ecdsa -.id_ecdsa - -##################### -# Any file with .pem or .key extensions -##################### -*.pem -*.key - -##################### -# Any file ending with _history or .history extension -##################### -*.history -*_history -``` +Secrets, such as credential files and SSH private keys, should never be committed to a version control +system. In GitLab, you can use a predefined list of files to block those files from a +repository. Any merge request containing a file matching the list is blocked from being merged. +Files already committed to the repository are not restricted by this push rule. + +Files blocked by this rule are listed below. For a complete list of criteria, see +[`files_denylist.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml). + +- AWS CLI credential blobs: + + - `.aws/credentials` + - `aws/credentials` + - `homefolder/aws/credentials` + +- Private RSA SSH keys: + + - `/ssh/id_rsa` + - `/.ssh/personal_rsa` + - `/config/server_rsa` + - `id_rsa` + - `.id_rsa` + +- Private DSA SSH keys: + + - `/ssh/id_dsa` + - `/.ssh/personal_dsa` + - `/config/server_dsa` + - `id_dsa` + - `.id_dsa` + +- Private ed25519 SSH keys: + + - `/ssh/id_ed25519` + - `/.ssh/personal_ed25519` + - `/config/server_ed25519` + - `id_ed25519` + - `.id_ed25519` + +- Private ECDSA SSH keys: + + - `/ssh/id_ecdsa` + - `/.ssh/personal_ecdsa` + - `/config/server_ecdsa` + - `id_ecdsa` + - `.id_ecdsa` + +- Any files ending with these suffixes: + + - `*.pem` + - `*.key` + - `*.history` + - `*_history` + +### Prevent pushing secrets to all projects + +To set a global push rule to prevent pushing secrets to all projects: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Push Rules**. +1. Expand **Push rules**. +1. Select **Prevent pushing secret files**. +1. Select **Save push rules**. + +### Prevent pushing secrets to a project + +The push rule of a project overrides the global push rule. + +To prevent pushing secrets to a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Push rules**. +1. Select **Prevent pushing secret files**. +1. Select **Save push rules**. ## Prohibited file names diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 676cc529c98..539908cd7bc 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -12,11 +12,11 @@ An application data backup creates an archive file that contains the database, all repositories and all attachments. 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 a backup and restore. +of GitLab on which it was created. The best way to [migrate your projects +from one server to another](#migrate-to-a-new-server) is through a backup and restore. WARNING: -GitLab doesn't back up items that aren't stored in the file system. If you're +GitLab doesn't back up items that aren't stored on the file system. If you're using [object storage](../administration/object_storage.md), be sure to enable backups with your object storage provider, if desired. @@ -58,16 +58,17 @@ including: - CI/CD job output logs - CI/CD job artifacts - LFS objects +- Terraform states ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331806) in GitLab 14.7) - Container Registry images - GitLab Pages content +- Packages ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332006) in GitLab 14.7) - Snippets - [Group wikis](../user/project/wiki/group.md) Backups do not include: -- [Terraform state files](../administration/terraform_state.md) -- [Package registry files](../administration/packages/index.md) - [Mattermost data](https://docs.mattermost.com/administration/config-settings.html#file-storage) +- Redis (and thus Sidekiq jobs) WARNING: GitLab does not back up any configuration files (`/etc/gitlab`), TLS keys and certificates, or system @@ -115,12 +116,8 @@ the host, based on your installed version of GitLab: If you're using the [GitLab Helm chart](https://gitlab.com/gitlab-org/charts/gitlab) on a Kubernetes cluster, you can run the backup task by using `kubectl` to run the `backup-utility` -script on the GitLab task runner pod. For more details, see -[backing up a GitLab installation](https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/backup-restore/backup.md#backing-up-a-gitlab-installation). - -```shell -kubectl exec -it <gitlab task-runner pod> -- backup-utility -``` +script on the GitLab toolbox pod. For more details, see the +[charts backup documentation](https://docs.gitlab.com/charts/backup-restore/backup.html). 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 isn't @@ -276,9 +273,11 @@ You can exclude specific directories from the backup by adding the environment v - `builds` (CI job output logs) - `artifacts` (CI job artifacts) - `lfs` (LFS objects) +- `terraform_state` (Terraform states) - `registry` (Container Registry images) - `pages` (Pages content) - `repositories` (Git repositories data) +- `packages` (Packages) All wikis are backed up as part of the `repositories` group. Non-existent wikis are skipped during a backup. @@ -985,7 +984,7 @@ your installation is using PgBouncer, for either performance reasons or when usi Next, restore `/etc/gitlab/gitlab-secrets.json` if necessary, [as previously mentioned](#restore-prerequisites). -Reconfigure, restart and check GitLab: +Reconfigure, restart and [check](../administration/raketasks/maintenance.md#check-gitlab-configuration) GitLab: ```shell sudo gitlab-ctl reconfigure @@ -993,7 +992,7 @@ sudo gitlab-ctl restart sudo gitlab-rake gitlab:check SANITIZE=true ``` -In GitLab 13.1 and later, check [database values can be decrypted](../administration/raketasks/doctor.md) +In GitLab 13.1 and later, check [database values can be decrypted](../administration/raketasks/check.md#verify-database-values-can-be-decrypted-using-the-current-secrets) especially if `/etc/gitlab/gitlab-secrets.json` was restored, or if a different server is the target for the restore. @@ -1001,6 +1000,14 @@ the target for the restore. sudo gitlab-rake gitlab:doctor:secrets ``` +For added assurance, you can perform [an integrity check on the uploaded files](../administration/raketasks/check.md#uploaded-files-integrity): + +```shell +sudo gitlab-rake gitlab:artifacts:check +sudo gitlab-rake gitlab:lfs:check +sudo gitlab-rake gitlab:uploads:check +``` + ### Restore for Docker image and GitLab Helm chart installations For GitLab installations using the Docker image or the GitLab Helm chart on a @@ -1182,7 +1189,7 @@ has a longer discussion explaining the potential problems. To prevent writes to the Git repository data, there are two possible approaches: -- Use [maintenance mode](../administration/maintenance_mode/index.md) to place GitLab in a read-only state. +- Use [maintenance mode](../administration/maintenance_mode/index.md) **(PREMIUM SELF)** to place GitLab in a read-only state. - Create explicit downtime by stopping all Gitaly services before backing up the repositories: ```shell @@ -1284,6 +1291,198 @@ sudo GITLAB_BACKUP_PGHOST=192.168.1.10 GITLAB_BACKUP_PGPORT=5432 /opt/gitlab/bin See the [PostgreSQL documentation](https://www.postgresql.org/docs/12/libpq-envars.html) for more details on what these parameters do. +## Migrate to a new server + +<!-- some details borrowed from GitLab.com move from Azure to GCP detailed at https://gitlab.com/gitlab-com/migration/-/blob/master/.gitlab/issue_templates/failover.md --> + +You can use GitLab backup and restore to migrate your instance to a new server. This section outlines a typical procedure for a GitLab deployment running on a single server. +If you're running GitLab Geo, an alternative option is [Geo disaster recovery for planned failover](../administration/geo/disaster_recovery/planned_failover.md). + +WARNING: +Avoid uncoordinated data processing by both the new and old servers, where multiple +servers could connect concurrently and process the same data. For example, when using +[incoming email](../administration/incoming_email.md), if both GitLab instances are +processing email at the same time, then both instances will end up missing some data. +This type of problem can occur with other services as well, such as a +[non-packaged database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server), +a non-packaged Redis instance, or non-packaged Sidekiq. + +Prerequisites: + +- Some time before your migration, consider notifying your users of upcoming + scheduled maintenance with a [broadcast message banner](../user/admin_area/broadcast_messages.md). +- Ensure your backups are complete and current. Create a complete system-level backup, or + take a snapshot of all servers involved in the migration, in case destructive commands + (like `rm`) are run incorrectly. + +### Prepare the new server + +To prepare the new server: + +1. Copy the + [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079) + from the old server to avoid man-in-the-middle attack warnings. +1. [Install and configure GitLab](https://about.gitlab.com/install) except + [incoming email](../administration/incoming_email.md): + 1. Install GitLab. + 1. Configure by copying `/etc/gitlab` files from the old server to the new server, and update as necessary. + Read the + [Omnibus configuration backup and restore instructions](https://docs.gitlab.com/omnibus/settings/backups.html) for more detail. + 1. If applicable, disable [incoming email](../administration/incoming_email.md). + 1. Block new CI/CD jobs from starting upon initial startup after the backup and restore. + Edit `/etc/gitlab/gitlab.rb` and set the following: + + ```ruby + nginx['custom_gitlab_server_config'] = "location /api/v4/jobs/request {\n deny all;\n return 503;\n}\n" + ``` + + 1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Stop GitLab to avoid any potential unnecessary and unintentional data processing: + + ```shell + sudo gitlab-ctl stop + ``` + +1. Configure the new server to allow receiving the Redis database and GitLab backup files: + + ```shell + sudo rm -f /var/opt/gitlab/redis/dump.rdb + sudo chown <your-linux-username> /var/opt/gitlab/redis + sudo mkdir /var/opt/gitlab/backups + sudo chown <your-linux-username> /var/opt/gitlab/backups + ``` + +### Prepare and transfer content from the old server + +1. Ensure you have an up-to-date system-level backup or snapshot of the old server. +1. Enable [maintenance mode](../administration/maintenance_mode/index.md) **(PREMIUM SELF)**, + if supported by your GitLab edition. +1. Block new CI/CD jobs from starting: + 1. Edit `/etc/gitlab/gitlab.rb`, and set the following: + + ```ruby + nginx['custom_gitlab_server_config'] = "location /api/v4/jobs/request {\n deny all;\n return 503;\n}\n" + ``` + + 1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Disable periodic background jobs: + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. Under the Sidekiq dashboard, select **Cron** tab and then + **Disable All**. +1. Wait for the currently running CI/CD jobs to finish, or accept that jobs that have not completed may be lost. + To view jobs currently running, on the left sidebar, select **Overviews > Jobs**, + and then select **Running**. +1. Wait for Sidekiq jobs to finish: + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. Under the Sidekiq dashboard, select **Queues** and then **Live Poll**. + Wait for **Busy** and **Enqueued** to drop to 0. + These queues contain work that has been submitted by your users; + shutting down before these jobs complete may cause the work to be lost. + Make note of the numbers shown in the Sidekiq dashboard for post-migration verification. +1. Flush the Redis database to disk, and stop GitLab other than the services needed for migration: + + ```shell + sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket save && sudo gitlab-ctl stop && sudo gitlab-ctl start postgresql + ``` + +1. Create a GitLab backup: + + ```shell + sudo gitlab-backup create + ``` + +1. Disable the following GitLab services and prevent unintentional restarts by adding the following to the bottom of `/etc/gitlab/gitlab.rb`: + + ```ruby + alertmanager['enable'] = false + gitlab_exporter['enable'] = false + gitlab_pages['enable'] = false + gitlab_workhorse['enable'] = false + grafana['enable'] = false + logrotate['enable'] = false + gitlab_rails['incoming_email_enabled'] = false + nginx['enable'] = false + node_exporter['enable'] = false + postgres_exporter['enable'] = false + postgresql['enable'] = false + prometheus['enable'] = false + puma['enable'] = false + redis['enable'] = false + redis_exporter['enable'] = false + registry['enable'] = false + sidekiq['enable'] = false + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Verify everything is stopped, and confirm no services are running: + + ```shell + sudo gitlab-ctl status + ``` + +1. Transfer the Redis database and GitLab backups to the new server: + + ```shell + sudo scp /var/opt/gitlab/redis/dump.rdb <your-linux-username>@new-server:/var/opt/gitlab/redis + sudo scp /var/opt/gitlab/backups/your-backup.tar <your-linux-username>@new-server:/var/opt/gitlab/backups + ``` + +### Restore data on the new server + +1. Restore appropriate file system permissions: + + ```shell + sudo chown gitlab-redis /var/opt/gitlab/redis + sudo chown gitlab-redis:gitlab-redis /var/opt/gitlab/redis/dump.rdb + sudo chown git:root /var/opt/gitlab/backups + sudo chown git:git /var/opt/gitlab/backups/your-backup.tar + ``` + +1. [Restore the GitLab backup](#restore-gitlab). +1. Verify that the Redis database restored correctly: + 1. On the top bar, select **Menu > Admin**. + 1. On the left sidebar, select **Monitoring > Background Jobs**. + 1. Under the Sidekiq dashboard, verify that the numbers + match with what was shown on the old server. + 1. While still under the Sidekiq dashboard, select **Cron** and then **Enable All** + to re-enable periodic background jobs. +1. Test that read-only operations on the GitLab instance work as expected. For example, browse through project repository files, merge requests, and issues. +1. Disable [Maintenance Mode](../administration/maintenance_mode/index.md) **(PREMIUM SELF)**, if previously enabled. +1. Test that the GitLab instance is working as expected. +1. If applicable, re-enable [incoming email](../administration/incoming_email.md) and test it is working as expected. +1. Update your DNS or load balancer to point at the new server. +1. Unblock new CI/CD jobs from starting by removing the custom NGINX config + you added previously: + + ```ruby + # The following line must be removed + nginx['custom_gitlab_server_config'] = "location /api/v4/jobs/request {\n deny all;\n return 503;\n}\n" + ``` + +1. Reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Remove the scheduled maintenance [broadcast message banner](../user/admin_area/broadcast_messages.md). + ## Additional notes This documentation is for GitLab Community and Enterprise Edition. We back up @@ -1308,9 +1507,11 @@ If you're using backup restore procedures, you may encounter the following warning messages: ```plaintext -psql:/var/opt/gitlab/backups/db/database.sql:22: ERROR: must be owner of extension plpgsql -psql:/var/opt/gitlab/backups/db/database.sql:2931: WARNING: no privileges could be revoked for "public" (two occurrences) -psql:/var/opt/gitlab/backups/db/database.sql:2933: WARNING: no privileges were granted for "public" (two occurrences) +ERROR: must be owner of extension pg_trgm +ERROR: must be owner of extension btree_gist +ERROR: must be owner of extension plpgsql +WARNING: no privileges could be revoked for "public" (two occurrences) +WARNING: no privileges were granted for "public" (two occurrences) ``` Be advised that the backup is successfully restored in spite of these warning @@ -1362,8 +1563,8 @@ Use the information in the following sections at your own risk. #### Verify that all values can be decrypted -You can determine if your database contains values that can't be decrypted by using the -[Secrets Doctor Rake task](../administration/raketasks/doctor.md). +You can determine if your database contains values that can't be decrypted by using a +[Rake task](../administration/raketasks/check.md#verify-database-values-can-be-decrypted-using-the-current-secrets). #### Take a backup @@ -1619,10 +1820,12 @@ There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features). Refer to this feature's version history for more details. -`gitaly-backup` is used by the backup Rake task to create and restore repository backups from Gitaly. +The `gitaly-backup` binary is used by the backup Rake task to create and restore repository backups from Gitaly. `gitaly-backup` replaces the previous backup method that directly calls RPCs on Gitaly from GitLab. -The backup Rake task must be able to find this executable. It can be configured in Omnibus GitLab packages: +The backup Rake task must be able to find this executable. In most cases, you don't need to change +the path to the binary as it should work fine with the default path `/opt/gitlab/embedded/bin/gitaly-backup`. +If you have a specific reason to change the path, it can be configured in Omnibus GitLab packages: 1. Add the following to `/etc/gitlab/gitlab.rb`: diff --git a/doc/raketasks/index.md b/doc/raketasks/index.md index 6227731e807..96c31047d8d 100644 --- a/doc/raketasks/index.md +++ b/doc/raketasks/index.md @@ -26,7 +26,6 @@ The following Rake tasks are available for use with GitLab: | [Back up and restore](backup_restore.md) | Back up, restore, and migrate GitLab instances between servers. | | [Clean up](cleanup.md) | Clean up unneeded items from GitLab instances. | | [Development](../development/rake_tasks.md) | Tasks for GitLab contributors. | -| [Doctor tasks](../administration/raketasks/doctor.md) | Checks for data integrity issues. | | [Elasticsearch](../integration/elasticsearch.md#gitlab-advanced-search-rake-tasks) | Maintain Elasticsearch in a GitLab instance. | | [Enable namespaces](features.md) | Enable usernames and namespaces for user projects. | | [General maintenance](../administration/raketasks/maintenance.md) | General maintenance and self-check tasks. | @@ -34,7 +33,7 @@ The following Rake tasks are available for use with GitLab: | [GitHub import](../administration/raketasks/github_import.md) | Retrieve and import repositories from GitHub. | | [Import repositories](import.md) | Import bare repositories into your GitLab instance. | | [Import large project exports](../development/import_project.md#importing-via-a-rake-task) | Import large GitLab [project exports](../user/project/settings/import_export.md). | -| [Integrity checks](../administration/raketasks/check.md) | Check the integrity of repositories, files, and LDAP. | +| [Integrity checks](../administration/raketasks/check.md) | Check the integrity of repositories, files, LDAP, and more. | | [LDAP maintenance](../administration/raketasks/ldap.md) | [LDAP](../administration/auth/ldap/index.md)-related tasks. | | [List repositories](list_repos.md) | List all GitLab-managed Git repositories on disk. | | [Migrate snippets to Git](migrate_snippets.md) | Migrate GitLab Snippets to Git repositories, and show the migration status. | diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md index 6c3bce939df..45c1c71158a 100644 --- a/doc/security/asset_proxy.md +++ b/doc/security/asset_proxy.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index 801a294dd81..1abb0c9e918 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/security/img/unlock_user_v14_7.png b/doc/security/img/unlock_user_v14_7.png Binary files differnew file mode 100644 index 00000000000..51015d932cb --- /dev/null +++ b/doc/security/img/unlock_user_v14_7.png diff --git a/doc/security/index.md b/doc/security/index.md index 832af93b95e..ab554e9135f 100644 --- a/doc/security/index.md +++ b/doc/security/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 162346c8874..07b5a688671 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts --- diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index bedf2ac3ab1..1cfff358c9d 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- diff --git a/doc/security/password_storage.md b/doc/security/password_storage.md index 7d8ac3bad39..6b71933b1ae 100644 --- a/doc/security/password_storage.md +++ b/doc/security/password_storage.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/security/passwords_for_integrated_authentication_methods.md b/doc/security/passwords_for_integrated_authentication_methods.md index 9931fd56e83..7281b310a30 100644 --- a/doc/security/passwords_for_integrated_authentication_methods.md +++ b/doc/security/passwords_for_integrated_authentication_methods.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 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 3c5099b1f75..9727ba1c5f0 100644 --- a/doc/security/project_import_decompressed_archive_size_limits.md +++ b/doc/security/project_import_decompressed_archive_size_limits.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md deleted file mode 100644 index a8b55007d2e..00000000000 --- a/doc/security/rack_attack.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../user/admin_area/settings/protected_paths.md' -remove_date: '2022-01-14' ---- - -This document was moved to [another location](../user/admin_area/settings/protected_paths.md). - -<!-- This redirect file can be deleted after <2022-01-14>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/security/rate_limits.md b/doc/security/rate_limits.md index 9d49297c9de..14fc526ca7e 100644 --- a/doc/security/rate_limits.md +++ b/doc/security/rate_limits.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -87,6 +87,33 @@ There is a rate limit for [testing webhooks](../user/project/integrations/webhoo The **rate limit** is 5 requests per minute per user. +### Users sign up + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77835) in GitLab 14.7. + +There is a rate limit per IP address on the `/users/sign_up` endpoint. This is to mitigate attempts to misuse the endpoint. For example, to mass +discover usernames or email addresses in use. + +The **rate limit** is 20 calls per minute per IP address. + +### Update username + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77221) in GitLab 14.7. + +There is a rate limit on the update username action. This is enforced to mitigate misuse of the feature. For example, to mass discover +which usernames are in use. + +The **rate limit** is 10 calls per minute per signed-in user. + +### Username exists + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77119) in GitLab 14.7. + +There is a rate limit for the internal endpoint `/users/:username/exists`, used by registration to perform a client-side validation for +uniqueness of the chosen username. This is to mitigate the risk of misuses, such as mass discovery of usernames in use. + +The **rate limit** is 20 calls per minute per IP address. + ## Troubleshooting ### Rack Attack is denylisting the load balancer diff --git a/doc/security/reset_user_password.md b/doc/security/reset_user_password.md index a61660f6a2f..f67b1934dc5 100644 --- a/doc/security/reset_user_password.md +++ b/doc/security/reset_user_password.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -68,12 +68,12 @@ If you know the username, user ID, or email address, you can use the Rails conso user = User.find(123) ``` - - By email address: + - By email address: ```ruby user = User.find_by(email: 'user@example.com') ``` - + 1. Reset the password: ```ruby @@ -105,7 +105,7 @@ To reset the root password, follow the steps listed previously. - If the root account name hasn't changed, use the username `root`. - If the root account name has changed and you don't know the new username, - you might be able to use a Rails console with user ID `1`. In almost all + you might be able to use a Rails console with user ID `1`. In almost all cases, the first user is the default administrator account. ## Troubleshooting diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 1f1c7457441..a7d852e2754 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/security/token_overview.md b/doc/security/token_overview.md index 333548fa1c9..578bb03563f 100644 --- a/doc/security/token_overview.md +++ b/doc/security/token_overview.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -93,17 +93,19 @@ This table shows available scopes per token. Scopes can be limited further on to | | API access | Registry access | Repository access | |-----------------------------|------------|-----------------|-------------------| -| Personal access token | ✅ | ✅ | ✅ | -| OAuth2 token | ✅ | 🚫 | ✅ | -| Impersonation token | ✅ | ✅ | ✅ | -| Project access token | ✅(1) | ✅(1) | ✅(1) | -| Deploy token | 🚫 | ✅ | ✅ | -| Deploy key | 🚫 | 🚫 | ✅ | -| Runner registration token | 🚫 | 🚫 | ✴️(2) | -| Runner authentication token | 🚫 | 🚫 | ✴️(2) | -| Job token | ✴️(3) | 🚫 | ✅ | +| Personal access token | ✅ | ✅ | ✅ | +| OAuth2 token | ✅ | 🚫 | ✅ | +| Impersonation token | ✅ | ✅ | ✅ | +| Project access token | ✅(1) | ✅(1) | ✅(1) | +| Group access token | ✅(2) | ✅(2) | ✅(2) | +| Deploy token | 🚫 | ✅ | ✅ | +| Deploy key | 🚫 | 🚫 | ✅ | +| Runner registration token | 🚫 | 🚫 | ✴️(3) | +| Runner authentication token | 🚫 | 🚫 | ✴️(3) | +| Job token | ✴️(4) | 🚫 | ✅ | 1. Limited to the one project. +1. Limited to the one group. 1. Runner registration and authentication token don't provide direct access to repositories, but can be used to register and authenticate a new runner that may execute jobs which do have access to the repository 1. Limited to certain [endpoints](../ci/jobs/ci_job_token.md). @@ -113,7 +115,7 @@ Access tokens should be treated like passwords and kept secure. Adding them to URLs is a security risk. This is especially true when cloning or adding a remote, as Git then writes the URL to its `.git/config` file in plain text. URLs are also generally logged by proxies and application servers, which makes those credentials visible to system administrators. -Instead, API calls can be passed an access token using headers, like [the `Private-Token` header](../api/index.md#personalproject-access-tokens). +Instead, API calls can be passed an access token using headers, like [the `Private-Token` header](../api/index.md#personalprojectgroup-access-tokens). Tokens can also be stored using a [Git credential storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 61b26204599..b83d81722fa 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -1,7 +1,7 @@ --- type: howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -49,7 +49,7 @@ Gitlab::CurrentSettings.update!('require_two_factor_authentication': false) To enforce 2FA only for certain groups: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select the **Require all users in this group to set up two-factor authentication** option. You can also specify a grace period in the **Time before enforced** option. @@ -76,7 +76,7 @@ The following are important notes about 2FA: groups) the shortest grace period is used. - It is possible to disallow subgroups from setting up their own 2FA requirements: 1. Go to the top-level group's **Settings > General**. - 1. Expand the **Permissions, LFS, 2FA** section. + 1. Expand the **Permissions and group features** section. 1. Uncheck the **Allow subgroups to set up their own two-factor authentication rule** field. This action causes all subgroups with 2FA requirements to stop requiring that from their members. diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index ceb375a9ad1..057d4e87efa 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -1,13 +1,27 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- -# How to unlock a locked user from the command line **(FREE SELF)** +# Locked users **(FREE SELF)** -After ten failed login attempts a user gets in a locked state. +Users are locked after ten failed sign-in attempts. These users remain locked: + +- For 10 minutes, after which time they are automatically unlocked. +- Until an admin unlocks them from the [Admin Area](../user/admin_area/index.md) or the command line in under 10 minutes. + +## Unlock a user from the Admin Area + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Use the search bar to find the locked user. +1. From the **User administration** dropdown select **Unlock**. + + + +## Unlock a user from the command line To unlock a locked user: diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 48538e413b4..8baddaf1383 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -1,7 +1,7 @@ --- type: howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index 7a8a78cc5f8..734a4cde7e8 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index 47ef90cbe55..621e6d595bf 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: concepts, reference, howto --- @@ -74,7 +74,8 @@ allowlist: The allowed entries can be separated by semicolons, commas or whitespaces (including newlines) and be in different formats like hostnames, IP addresses and/or IP ranges. IPv6 is supported. Hostnames that contain Unicode characters should -use Internationalising Domain Names in Applications (IDNA) encoding. +use [Internationalized Domain Names in Applications](https://www.icann.org/resources/pages/glossary-2014-02-04-en#i) +(IDNA) encoding. The allowlist can hold a maximum of 1000 entries. Each entry can be a maximum of 255 characters. diff --git a/doc/ssh/index.md b/doc/ssh/index.md index 2fae3512b9d..6196ee5465b 100644 --- a/doc/ssh/index.md +++ b/doc/ssh/index.md @@ -1,14 +1,14 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: howto, reference --- -# GitLab and SSH keys **(FREE)** +# Use SSH keys to communicate with GitLab **(FREE)** Git is a distributed version control system, which means you can work locally, -then share or "push" your changes to a server. In this case, the server is GitLab. +then share or *push* your changes to a server. In this case, the server you push to is GitLab. GitLab uses the SSH protocol to securely communicate with Git. When you use SSH keys to authenticate to the GitLab remote server, @@ -376,7 +376,9 @@ Git user has default SSH configuration? ... no Remove the custom configuration as soon as you can. These customizations are **explicitly not supported** and may stop working at any time. -## Troubleshooting SSH connections +## Troubleshooting + +### Password prompt with `git clone` When you run `git clone`, you may be prompted for a password, like `git@gitlab.example.com's password:`. This indicates that something is wrong with your SSH setup. @@ -386,3 +388,13 @@ This indicates that something is wrong with your SSH setup. - Try to manually register your private SSH key by using `ssh-agent`. - Try to debug the connection by running `ssh -Tv git@example.com`. Replace `example.com` with your GitLab URL. + +### `Could not resolve hostname` error + +You may receive the following error when [verifying that you can connect](#verify-that-you-can-connect): + +```shell +ssh: Could not resolve hostname gitlab.example.com: nodename nor servname provided, or not known +``` + +If you receive this error, restart your terminal and try the command again. diff --git a/doc/subscriptions/bronze_starter.md b/doc/subscriptions/bronze_starter.md index 3a58dd84614..2c66d32f669 100644 --- a/doc/subscriptions/bronze_starter.md +++ b/doc/subscriptions/bronze_starter.md @@ -98,8 +98,8 @@ the tiers are no longer mentioned in GitLab documentation: - [Bidirectional mirroring](../user/project/repository/mirror/bidirectional.md) - [Mirror with Perforce Helix with Git Fusion](../user/project/repository/mirror/bidirectional.md#mirror-with-perforce-helix-with-git-fusion) - Runners: - - Run pipelines in the parent project [for merge requests from a forked project](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project) - - [Shared runners pipeline minutes quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) + - Run pipelines in the parent project [for merge requests from a forked project](../ci/pipelines/merge_request_pipelines.md#run-pipelines-in-the-parent-project) + - [Shared runners CI/CD minutes](../ci/pipelines/cicd_minutes.md) - [Push rules](../push_rules/push_rules.md) - SAML for self-managed GitLab instance: - [Administrator groups](../integration/saml.md#administrator-groups) diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md index e174a144cfc..b72fad02b3d 100644 --- a/doc/subscriptions/gitlab_com/index.md +++ b/doc/subscriptions/gitlab_com/index.md @@ -11,25 +11,32 @@ GitLab SaaS is the GitLab software-as-a-service offering, which is available at You don't need to install anything to use GitLab SaaS, you only need to [sign up](https://gitlab.com/users/sign_up). When you sign up, you choose: -- [A license tier](https://about.gitlab.com/pricing/). +- [A subscription](https://about.gitlab.com/pricing/). - [The number of seats you want](#how-seat-usage-is-determined). -All GitLab SaaS public projects, regardless of the subscription, get access to features in the **Ultimate** tier. -Qualifying open source projects also get 50,000 CI minutes and free access to the **Ultimate** tier +The subscription determines which features are available for your private projects. Public projects automatically get **Ultimate** tier features. + +Qualifying open source projects also get 50,000 CI/CD minutes and free access to the **Ultimate** tier through the [GitLab for Open Source program](https://about.gitlab.com/solutions/open-source/). ## Obtain a GitLab SaaS subscription +A GitLab SaaS subscription applies to a top-level group. +Members of every subgroup and project in the group: + +- Can use the features of the subscription. +- Consume seats in the subscription. + To subscribe to GitLab SaaS: 1. View the [GitLab SaaS feature comparison](https://about.gitlab.com/pricing/gitlab-com/feature-comparison/) and decide which tier you want. 1. Create a user account for yourself by using the [sign up page](https://gitlab.com/users/sign_up). -1. Create a [group](../../user/group/index.md#create-a-group). You use the group to grant users access to several projects - at once. A group is not required if you plan to have projects in a personal namespace instead. +1. Create a [group](../../user/group/index.md#create-a-group). Your license tier applies to the top-level group, its subgroups, and projects. 1. Create additional users and - [add them to the group](../../user/group/index.md#add-users-to-a-group). + [add them to the group](../../user/group/index.md#add-users-to-a-group). The users in this group, its subgroups, and projects can use + the features of your license tier, and they consume a seat in your subscription. 1. On the left sidebar, select **Billing** and choose a tier. 1. Fill out the form to complete your purchase. @@ -62,10 +69,12 @@ The following information is displayed: email address. A GitLab SaaS subscription uses a concurrent (_seat_) model. You pay for a -subscription according to the maximum number of users enabled at one time. You can +subscription according to the maximum number of users assigned to the top-level group or its children during the billing period. You can add and remove users during the subscription period, as long as the total users at any given time doesn't exceed the subscription count. +A top-level group can be [changed](../../user/group/index.md#change-a-groups-path) like any other group. + Every user is included in seat usage, with the following exceptions: - Users who are pending approval. @@ -77,6 +86,12 @@ Every user is included in seat usage, with the following exceptions: Seat usage is reviewed [quarterly or annually](../quarterly_reconciliation.md). +If a user navigates to a different top-level group (one they have created themselves, for example) +and that group does not have a paid subscription, they would not see any of the paid features. + +It is also possible for users to belong to two different top-level groups with different subscriptions. +In this case, they would see only the features available to that subscription. + ### View seat usage To view a list of seats being used: @@ -124,7 +139,7 @@ and is not affected by the current search. A GitLab subscription is valid for a specific number of users. If the number of billable users exceeds the number included in the subscription, known -as the number of **seats owed**, you must pay for the excess number of users before renewal. +as the number of **seats owed**, you must pay for the excess number of users. For example, if you purchase a subscription for 10 users: @@ -138,9 +153,9 @@ Seats owed = 12 - 10 (Maximum users - users in subscription) ### Add users to your subscription -You can add users to your subscription at 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. +Your subscription cost is based on the maximum number of seats you use during the billing period. +Even if you reach the number of seats in your subscription, you can continue to add users. +GitLab [bills you for the overage](../quarterly_reconciliation.md). To add users to a subscription: @@ -219,6 +234,8 @@ of the date of expiry with a banner in the GitLab user interface. To renew your subscription: 1. Log in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) and beneath your existing subscription, select **Renew**. +The **Renew** button remains disabled (grayed-out) until 15 days before a subscription expires. +You can hover your mouse on the **Renew** button to see the date when it will become active. 1. Review your renewal details and complete the payment process. 1. Select **Confirm purchase**. @@ -250,132 +267,30 @@ previous period), log in to the [Customers Portal](https://customers.gitlab.com/ If you have difficulty during the renewal process, contact the [Support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293) for assistance. -## Change the contact person for your subscription - -To change the contact person who manages your subscription, -contact the GitLab [Support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293). - -## CI pipeline minutes - -CI pipeline minutes are the execution time for your [pipelines](../../ci/pipelines/index.md) -on GitLab shared runners. Each [GitLab SaaS tier](https://about.gitlab.com/pricing/) -includes a monthly quota of CI pipeline minutes for private and public projects in -the namespace: - -| Plan | CI pipeline minutes | -|----------|---------------------| -| Free | 400 | -| Premium | 10,000 | -| Ultimate | 50,000 | - -The consumption rate for CI pipeline minutes is based on the visibility of the projects: - -- Private projects in the namespace consume pipeline minutes at a rate of 1 CI pipeline minute - per 1 minute of execution time on GitLab shared runners. -- Public projects in: - - Namespaces [created on or after 2021-07-17](https://gitlab.com/gitlab-org/gitlab/-/issues/332708) - consume pipeline minutes at a slower rate, 1 CI pipeline minute per 125 minutes - of execution time on GitLab shared runners. The per-minute rate for public projects - is 0.008 CI pipeline minutes per 1 minute of execution time on GitLab shared runners. - - Namespaces created before 2021-07-17 do not consume CI pipeline minutes. - -| Plan | CI pipeline minutes | Maximum **private** project execution time (all namespaces) | Maximum **public** project execution time (namespaces created 2021-07-17 and later) | -|----------|---------------------|-------------------------------------------------------------|-------------------------------------------------------------------------------------| -| Free | 400 | 400 minutes | 50,000 minutes | -| Premium | 10,000 | 10,000 minutes | 1,250,000 minutes | -| Ultimate | 50,000 | 50,000 minutes | 6,250,000 minutes | - -Quotas apply to: - -- Groups, where the minutes are shared across all members of the group, its - subgroups, and nested projects. To view the group's usage, navigate to the group, - then **Settings > Usage Quotas**. -- Your personal account, where the minutes are available for your personal projects. - To view and buy personal minutes: - - 1. In the top-right corner, select your avatar. - 1. Select **Edit profile**. - 1. On the left sidebar, select **[Usage Quotas](https://gitlab.com/-/profile/usage_quotas#pipelines-quota-tab)**. - -Only pipeline minutes for GitLab shared runners are restricted. If you have a -specific runner set up for your projects, there is no limit to your build time on GitLab SaaS. - -The available quota is reset on the first of each calendar month at midnight UTC. +## Add or change the contacts for your subscription -When the CI minutes are depleted, an email is sent automatically to notify the owner(s) -of the namespace. You can [purchase additional CI minutes](#purchase-additional-ci-minutes), -or upgrade your account to a higher [plan](https://about.gitlab.com/pricing/). -Your own runners can still be used even if you reach your limits. +Contacts can renew a subscription, cancel a subscription, or transfer the subscription to a different namespace. -### Purchase additional CI minutes +To change the contacts: -If you're using GitLab SaaS, you can purchase additional CI minutes so 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 on the -[GitLab Pricing page](https://about.gitlab.com/pricing/). Additional minutes: +1. Ensure an account exists in the + [Customers Portal](https://customers.gitlab.com/customers/sign_in) for the user you want to add. +1. Verify you have access to at least one of + [these requirements](https://about.gitlab.com/handbook/support/license-and-renewals/workflows/customersdot/associating_purchases.html). +1. [Create a ticket with the Support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293). Include any relevant material in your request. -- Are only used after the shared quota included in your subscription runs out. -- Roll over month to month. - -To purchase additional minutes for your personal namespace: - -1. In the top-right corner, select your avatar. -1. Select **Edit profile**. -1. On the left sidebar, select **Usage Quotas**. -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 SaaS, click **Buy more CI minutes**, and complete the details about the transaction. - -After we process your payment, the extra CI minutes are synced to your group -namespace. - -To confirm the available CI minutes for your personal projects, go to the **Usage Quotas** settings again. - -The **Additional minutes** displayed now includes the purchased additional CI -minutes, plus any minutes rolled over from last month. - -Be aware that: - -- Extra CI minutes assigned to one group cannot be transferred to a different - group. -- If you have used more minutes than your default quota, those minutes are - deducted from your Additional Minutes quota immediately after your purchase of - additional minutes. - -### Purchase additional CI minutes on GitLab SaaS - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6574) in GitLab 14.5. - -If you're using GitLab SaaS, you can purchase additional CI minutes so 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 on the -[GitLab Pricing page](https://about.gitlab.com/pricing/). Additional minutes: - -- 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 SaaS: - -1. On the top bar, select **Menu > Groups** and find your group. -1. On the left sidebar, select **Settings > Usage Quotas**. -1. Select **Buy additional minutes**. -1. Complete the details about the transaction. - -After we process your payment, the extra CI minutes are synced to your group -namespace. +## CI/CD minutes -To confirm the available CI minutes, go to your group, and then select -**Settings > Usage Quotas**. +CI/CD minutes are the execution time for your [pipelines](../../ci/pipelines/index.md) +on GitLab shared runners. -The **Additional minutes** displayed now includes the purchased additional CI -minutes, plus any minutes rolled over from last month. +Refer to [CI/CD minutes](../../ci/pipelines/cicd_minutes.md) +for more information. -Be aware that: +### Purchase additional CI/CD minutes -- Extra CI minutes assigned to one group cannot be transferred to a different - group. -- If you have used more minutes than your default quota, those minutes are - deducted from your Additional Minutes quota immediately after your purchase of - additional minutes. +You can [purchase additional minutes](../../ci/pipelines/cicd_minutes.md#purchase-additional-cicd-minutes) +for your personal or group namespace. ## Storage subscription diff --git a/doc/subscriptions/img/quarterly_reconciliation.png b/doc/subscriptions/img/quarterly_reconciliation.png Binary files differnew file mode 100644 index 00000000000..1990d64616e --- /dev/null +++ b/doc/subscriptions/img/quarterly_reconciliation.png diff --git a/doc/subscriptions/index.md b/doc/subscriptions/index.md index 2cf3b9f7074..4e4c0309c3d 100644 --- a/doc/subscriptions/index.md +++ b/doc/subscriptions/index.md @@ -7,11 +7,6 @@ type: index, reference # GitLab subscription **(PREMIUM)** -INFO: -Get advanced search and more with -[a trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-subscription-docs). -Free for 30 days. - GitLab offers tiers of features. Your subscription determines which tier you have access to. Subscriptions are valid for 12 months. @@ -177,7 +172,7 @@ To change the password for this customers portal account: ### GitLab for Education For qualifying non-profit educational institutions, the [GitLab for Education](https://about.gitlab.com/solutions/education/) program provides -the top GitLab tier, plus 50,000 CI minutes per month. +the top GitLab tier, plus 50,000 CI/CD minutes per month. The GitLab for Education license can only be used for instructional-use or non-commercial academic research. @@ -188,7 +183,7 @@ Find more information on how to apply and renew at ### GitLab for Open Source For qualifying open source projects, the [GitLab for Open Source](https://about.gitlab.com/solutions/open-source/) program provides -the top GitLab tier, plus 50,000 CI minutes per month. +the top GitLab tier, plus 50,000 CI/CD minutes per month. You can find more information about the [program requirements](https://about.gitlab.com/solutions/open-source/join/#requirements), [renewals](https://about.gitlab.com/solutions/open-source/join/#renewals), @@ -253,7 +248,7 @@ if a project holds sensitive data. Email `opensource@gitlab.com` with details of ### GitLab for Startups For qualifying startups, the [GitLab for Startups](https://about.gitlab.com/solutions/startups/) program provides -the top GitLab tier, plus 50,000 CI minutes per month for 12 months. +the top GitLab tier, plus 50,000 CI/CD minutes per month for 12 months. For more information, including program requirements, see the [Startup program's landing page](https://about.gitlab.com/solutions/startups/). diff --git a/doc/subscriptions/quarterly_reconciliation.md b/doc/subscriptions/quarterly_reconciliation.md index cdac50748d0..3398902da1b 100644 --- a/doc/subscriptions/quarterly_reconciliation.md +++ b/doc/subscriptions/quarterly_reconciliation.md @@ -9,14 +9,44 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab reviews your seat usage and sends you an invoice for any overages. This review can occur: -- **Annually**, also known as the annual true-up process. This process requires you to pay the full annual subscription fee +- **Annually**. This process is also known as **the annual true-up process**. This process requires you to pay the full annual subscription fee for users added anytime during the year. -- **Quarterly**. With this process, you only pay for the remaining period of your subscription term. +- **Quarterly**. With this process, you pay only for the remaining period of your subscription term. -## Quarterly reconciliation process +## Quarterly reconciliation vs. annual true-ups -With the quarterly reconciliation process, if you add users in the third quarter of your subscription term, for example, -you only pay 25% of what you would have paid previously. This calculation results in substantial savings. +Quarterly reconciliation can result in substantial savings. + +Let's say in January you purchased an annual license for 100 users. This chart shows your usage during the year. +The number of users went up and down, with 120 as the maximum. The dark purple indicates the most users you had each quarter. + + + +If you are being billed annually: + +- During the year, you went over the license by 20 users. +- If we pretend each extra seat is $100, then you pay $100 x 20 users. + +Annual total: **$2000** + +If you are being billed quarterly, you pay for the maximum number of seats you used during the quarter, +and for only the remaining quarters. + +Using the same example, if a seat is $100 per year, then it is $25 per quarter. + +- In Q1, you had a maximum of 110 users. 10 users over license x $25 per user x 3 quarters = **$750** + The license is now paid for 110 users. + +- In Q2, 105 users was the maximum. You did not go over 110 users, so no charge. + +- In Q3, you had 120 users. 10 users over license x $25 per user x 1 remaining quarter = **$250** + The license is now paid for 120 users. + +- In Q4, you had 120 users. You did not exceed the number of users. However, if you had, you would not be charged, because in Q4, there are no charges for exceeding the number. + +Annual total: **$1000** + +With quarterly reconciliation, you pay less annually. If it's not possible for you to participate in quarterly reconciliations, you can opt out of the process by using a contract amendment. In that case, you default to the annual review. diff --git a/doc/subscriptions/self_managed/index.md b/doc/subscriptions/self_managed/index.md index 94180da2bbd..5ac2c5a5037 100644 --- a/doc/subscriptions/self_managed/index.md +++ b/doc/subscriptions/self_managed/index.md @@ -254,7 +254,7 @@ To subscribe to GitLab through a GitLab self-managed installation: 1. Go to the [Customers Portal](https://customers.gitlab.com/) and purchase a GitLab self-managed plan. 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). + which must be [uploaded to your GitLab instance](../../user/admin_area/license.md#upload-your-license). NOTE: If you're purchasing a subscription for an existing **Free** GitLab self-managed @@ -373,7 +373,7 @@ To add seats to a subscription: 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. +- A new license. [Upload this license](../../user/admin_area/license.md#upload-your-license) to your instance to use it. ### Renew a subscription @@ -384,6 +384,8 @@ We recommend following these steps during renewal: 1. Prune any inactive or unwanted users by [blocking them](../../user/admin_area/moderate_users.md#block-a-user). 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. +The **Renew** button remains disabled (grayed-out) until 15 days before a subscription expires. +You can hover your mouse on the **Renew** button to see the date when it will become active. NOTE: If you need to change your [GitLab tier](https://about.gitlab.com/pricing/), contact our sales team via [the sales contact form](https://about.gitlab.com/sales/) for assistance as this can't be done in the Customers Portal. @@ -392,7 +394,7 @@ We recommend following these steps during 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. 1. Review your renewal details and complete the payment process. 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. +1. [Upload](../../user/admin_area/license.md#upload-your-license) your new license to your instance. 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. @@ -414,9 +416,21 @@ The following is emailed to you: [**View invoices**](https://customers.gitlab.com/receipts). - A new license. -[Upload the new license](../../user/admin_area/license.md#uploading-your-license) to your instance. +[Upload the new license](../../user/admin_area/license.md#upload-your-license) to your instance. The new tier takes effect when the new license is uploaded. +## Add or change the contacts for your subscription + +Contacts can renew a subscription, cancel a subscription, or transfer the subscription to a different namespace. + +To change the contacts: + +1. Ensure an account exists in the + [Customers Portal](https://customers.gitlab.com/customers/sign_in) for the user you want to add. +1. Verify you have access to at least one of + [these requirements](https://about.gitlab.com/handbook/support/license-and-renewals/workflows/customersdot/associating_purchases.html). +1. [Create a ticket with the Support team](https://support.gitlab.com/hc/en-us/requests/new?ticket_form_id=360000071293). Include any relevant material in your request. + ## Subscription expiry When your license expires, GitLab locks down features, like Git pushes diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 72106a00191..44429754747 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -45,7 +45,7 @@ System hooks can be used, for example, for logging or changing information in an LDAP server. In addition to these default events, you can enable triggers for other events, -such as push events, and disable the `repository_update` event +such as push events, and disable the `repository_update` event when you create a system hook. NOTE: diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index da96e88bb21..2a301e6ff5b 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -11,7 +11,7 @@ This page gathers all the resources for the topic **Authentication** within GitL ## GitLab users - [SSH](../../ssh/index.md) -- [Two-factor authentication (2FA)](../../user/profile/account/two_factor_authentication.md#two-factor-authentication) +- [Two-factor authentication](../../user/profile/account/two_factor_authentication.md) - [Why do I keep getting signed out?](../../user/profile/index.md#why-do-i-keep-getting-signed-out) - **Articles:** - [Support for Universal 2nd Factor Authentication - YubiKeys](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/) @@ -40,8 +40,9 @@ This page gathers all the resources for the topic **Authentication** within GitL ## API - [OAuth 2 Tokens](../../api/index.md#oauth2-tokens) -- [Personal access tokens](../../api/index.md#personalproject-access-tokens) -- [Project access tokens](../../api/index.md#personalproject-access-tokens) +- [Personal access tokens](../../api/index.md#personalprojectgroup-access-tokens) +- [Project access tokens](../../api/index.md#personalprojectgroup-access-tokens) +- [Group access tokens](../../api/index.md#personalprojectgroup-access-tokens) - [Impersonation tokens](../../api/index.md#impersonation-tokens) - [OAuth 2.0 identity provider API](../../api/oauth2.md) diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 925f657c099..177e10b99b9 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -131,7 +131,7 @@ You can extend and manage your Auto DevOps configuration with GitLab APIs: ## Forward CI/CD variables to the build environment -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25514) in GitLab 12.3, but available in versions 11.9 and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25514) in GitLab 12.3, but available in GitLab 12.0 and later. CI/CD variables can be forwarded into the build environment using the `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` CI/CD variable. @@ -408,14 +408,15 @@ applications. | `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` | A [comma-separated list of CI/CD variable names](#forward-cicd-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_CHART_REPOSITORY_NAME` | Used to set the name of the Helm repository. Defaults to `gitlab`. | +| `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | 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` | Used to set a password to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. | | `AUTO_DEVOPS_CHART_REPOSITORY_PASS_CREDENTIALS` | From GitLab 14.2, set to a non-empty value to enable forwarding of the Helm repository credentials to the chart server when the chart artifacts are on a different host than repository. | | `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). | | `BUILDPACK_URL` | Buildpack's full URL. [Must point to a URL supported by Pack or Herokuish](#custom-buildpacks). | -| `CANARY_ENABLED` | From GitLab 11.0, used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | +| `CANARY_ENABLED` | Used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | +| `BUILDPACK_VOLUMES` | Specify one or more [Buildpack volumes to mount](stages.md#mount-volumes-into-the-build-container). Use a pipe `|` as list separator. | | `CANARY_PRODUCTION_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. Takes precedence over `CANARY_REPLICAS`. Defaults to 1. | | `CANARY_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md). Defaults to 1. | | `CI_APPLICATION_REPOSITORY` | The repository of container image being built or deployed, `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`. For more details, read [Custom container image](#custom-container-image). | @@ -424,18 +425,18 @@ 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 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) is made available by Auto DevOps as environment variables to the deployed application. | +| `HELM_UPGRADE_EXTRA_ARGS` | Allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. | +| `INCREMENTAL_ROLLOUT_MODE` | 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_*` | Any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) is made available by Auto DevOps as environment variables to the deployed application. | | `KUBE_CONTEXT` | From GitLab 14.5, can be used to select which context to use from `KUBECONFIG`. When `KUBE_CONTEXT` is blank, the default context in `KUBECONFIG` (if any) will be used. A context must be selected when using the [CI/CD tunnel](../../user/clusters/agent/ci_cd_tunnel.md). | -| `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) for more information. | +| `KUBE_INGRESS_BASE_DOMAIN` | Can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) for more information. | | `KUBE_NAMESPACE` | The namespace used for deployments. When using certificate-based clusters, [this value should not be overwritten directly](../../user/project/clusters/deploy_to_cluster.md#custom-namespace). | | `KUBECONFIG` | The kubeconfig to use for deployments. User-provided values take priority over GitLab-provided values. | | `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. | -| `ROLLOUT_RESOURCE_TYPE` | From GitLab 11.9, allows specification of the resource type being deployed when using a custom Helm chart. Default value is `deployment`. | +| `ROLLOUT_RESOURCE_TYPE` | Allows specification of the resource type being deployed when using a custom Helm chart. Default value is `deployment`. | | `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). | +| `STAGING_ENABLED` | Used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | NOTE: After you set up your replica variables using a @@ -453,8 +454,8 @@ The following table lists CI/CD variables related to the database. | **CI/CD Variable** | **Description** | |-----------------------------------------|------------------------------------| -| `DB_INITIALIZE` | From GitLab 11.4, used to specify the command to run to initialize the application's PostgreSQL database. Runs inside the application pod. | -| `DB_MIGRATE` | From GitLab 11.4, used to specify the command to run to migrate the application's PostgreSQL database. Runs inside the application pod. | +| `DB_INITIALIZE` | Used to specify the command to run to initialize the application's PostgreSQL database. Runs inside the application pod. | +| `DB_MIGRATE` | Used to specify the command to run to migrate the application's PostgreSQL database. Runs inside the application pod. | | `POSTGRES_ENABLED` | Whether PostgreSQL is enabled. Defaults to `true`. Set to `false` to disable the automatic deployment of PostgreSQL. | | `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. | @@ -478,12 +479,11 @@ The following table lists variables used to disable jobs. | `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. | +| `code_quality` | `CODE_QUALITY_DISABLED` | | If the variable is present, the job isn't created. | +| `container_scanning` | `CONTAINER_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `dast` | `DAST_DISABLED` | | 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. | +| `dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | 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. | @@ -491,34 +491,32 @@ The following table lists variables used to disable jobs. | `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_management` | `LICENSE_MANAGEMENT_DISABLED` | GitLab 12.7 and earlier | 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` | GitLab 11.0 to GitLab 13.12 | Browser performance. If the variable is present, the job isn't created. Replaced by `browser_performance`. | +| `performance` | `PERFORMANCE_DISABLED` | GitLab 13.12 and earlier | Browser performance. If the variable is present, the job isn't created. Replaced by `browser_performance`. | | `browser_performance` | `BROWSER_PERFORMANCE_DISABLED` | From GitLab 14.0 | Browser performance. If the variable is present, the job isn't created. Replaces `performance`. | | `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. | +| `review` | `REVIEW_DISABLED` | | If the variable is present, the job isn't created. | +| `review:stop` | `REVIEW_DISABLED` | | Manual job. If the variable is present, the job isn't created. | +| `sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `sast:container` | `CONTAINER_SCANNING_DISABLED` | | 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. | +| `secrets-sast` | `SAST_DISABLED` | | 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. | +| `test` | `TEST_DISABLED` | | 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 -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/49056) in GitLab 11.7. - Some applications need to define secret variables that are accessible by the deployed application. Auto DevOps detects CI/CD variables starting with `K8S_SECRET_`, and makes these prefixed variables available to the deployed application as environment variables. @@ -623,8 +621,6 @@ service: ### Deploy policy for staging and production environments -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/-/merge_requests/160) in GitLab 10.8. - NOTE: You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy). @@ -640,8 +636,6 @@ you when you're ready to manually deploy to production. ### Deploy policy for canary environments **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/-/merge_requests/171) in GitLab 11.0. - You can use a [canary environment](../../user/project/canary_deployments.md) before deploying any changes to production. @@ -652,8 +646,6 @@ If you define `CANARY_ENABLED` with a non-empty value, then two manual jobs are ### Incremental rollout to production **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5415) in GitLab 10.8. - NOTE: You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy). @@ -703,14 +695,10 @@ With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`  WARNING: -Before GitLab 11.4, the presence of the `INCREMENTAL_ROLLOUT_ENABLED` CI/CD variable -enabled this feature. This configuration is deprecated, and is scheduled to be -removed in the future. +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. - NOTE: You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy). diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index ca004662395..8b3966526ec 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -65,6 +65,30 @@ 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). +#### Mount volumes into the build container + +> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-build-image/-/merge_requests/65) in GitLab 14.2. +> - Multiple volume support (or `auto-build-image` v1.6.0) [introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-build-image/-/merge_requests/80) in GitLab 14.6. + +The variable `BUILDPACK_VOLUMES` can be used to pass volume mount definitions to the +`pack` command. The mounts are passed to `pack build` using `--volume` arguments. +Each volume definition can include any of the capabilities provided by `build pack` +such as the host path, the target path, whether the volume is writable, and +one or more volume options. + +Use a pipe `|` character to pass multiple volumes. +Each item from the list is passed to `build back` using a separate `--volume` argument. + +In this example, three volumes are mounted in the container as `/etc/foo`, `/opt/foo`, and `/var/opt/foo`: + +```yaml +buildjob: + variables: + BUILDPACK_VOLUMES: /mnt/1:/etc/foo:ro|/mnt/2:/opt/foo:ro|/mnt/3:/var/opt/foo:rw +``` + +Read more about defining volumes in the [`pack build` documentation](https://buildpacks.io/docs/tools/pack/cli/pack_build/). + ### Auto Build using Herokuish > [Replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63351) with Cloud Native Buildpacks in GitLab 14.0. diff --git a/doc/topics/build_your_application.md b/doc/topics/build_your_application.md index 9750af5ba1c..d7097e55052 100644 --- a/doc/topics/build_your_application.md +++ b/doc/topics/build_your_application.md @@ -1,6 +1,6 @@ --- -stage: -group: +stage: none +group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index fc9c0e0ec63..422919ea46c 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -3,96 +3,83 @@ 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/#assignments description: 'This article describes how to install Git on macOS, Ubuntu Linux and Windows.' -type: howto --- # Installing Git **(FREE)** -To begin contributing to GitLab projects, -you must install the Git client on your computer. - -This article shows you how to install Git on macOS, Ubuntu Linux and Windows. - -Information on [installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +To begin contributing to GitLab projects, you must install the appropriate Git client +on your computer. Information about [installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) is also available at the official Git website. -## Install Git on macOS using the Homebrew package manager - -Although you can use the version of Git shipped with macOS or install the latest -version of Git on macOS by downloading it from the project website, we recommend -installing Git with Homebrew to get access to an extensive selection of -dependency-managed libraries and applications. - -If you don't need access to any additional development libraries or don't have -approximately 15 GB of available disk space for Xcode and Homebrew, use one of -the previously mentioned methods. - -### Installing Xcode - -To build dependencies, Homebrew needs the XCode Command Line Tools. Install -it by running in your terminal: +## Supported operating systems -```shell -xcode-select --install -``` +Git is available for the following operating systems: -Click **Install** to download and install it. Alternatively, you can install -the entire [XCode](https://developer.apple.com/xcode/) package through the -macOS App Store. +- [macOS](#macos) +- [Ubuntu Linux](#ubuntu-linux) +- [Microsoft Windows](#windows) -### Installing Homebrew +### macOS -With Xcode installed, browse to the [Homebrew website](https://brew.sh/index.html) -for the official Homebrew installation instructions. +A version of Git is supplied by macOS. You can use this version, or install the latest +version of Git on macOS by downloading it from the project website. We recommend +installing Git with [Homebrew](https://brew.sh/index.html). With Homebrew, you can +access an extensive selection of libraries and applications, with their dependencies +managed for you. -### Installing Git via Homebrew +Prerequisites: -With Homebrew installed, you are now ready to install Git. -Open a terminal and enter the following command: +- 15 GB of available disk space for Homebrew and Xcode. +- Extra disk space for any additional development libraries. -```shell -brew install git -``` +To install Git on macOS: -Congratulations! You should now have Git installed via Homebrew. +1. Open a terminal and install the XCode Command Line Tools: -To verify that Git works on your system, run: + ```shell + xcode-select --install + ``` -```shell -git --version -``` + Alternatively, you can install the entire [XCode](https://developer.apple.com/xcode/) + package through the macOS App Store. -Next, read our article on [adding an SSH key to GitLab](../../../ssh/index.md). +1. Select **Install** to download and install XCode Command Line Tools. +1. Install Homebrew according to the [official Homebrew installation instructions](https://brew.sh/index.html). +1. Install Git by running `brew install git` from your terminal. +1. In a terminal, verify that Git works on your computer: -## Install Git on Ubuntu Linux + ```shell + git --version + ``` -On Ubuntu and other Linux operating systems -it is recommended to use the built-in package manager to install Git. +### Ubuntu Linux -Open a terminal and enter the following commands -to install the latest Git from the official Git maintained package archives: +On Ubuntu and other Linux operating systems, use the built-in package manager +to install Git: -```shell -sudo apt-add-repository ppa:git-core/ppa -sudo apt-get update -sudo apt-get install git -``` +1. Open a terminal and run these commands to install the latest Git +from the officially + maintained package archives: -Congratulations! You should now have Git installed via the Ubuntu package manager. + ```shell + sudo apt-add-repository ppa:git-core/ppa + sudo apt-get update + sudo apt-get install git + ``` -To verify that Git works on your system, run: +1. To verify that Git works on your computer, run: -```shell -git --version -``` + ```shell + git --version + ``` -Next, read our article on [adding an SSH key to GitLab](../../../ssh/index.md). +### Windows -## Installing Git on Windows from the Git website +Go to the [Git website](https://git-scm.com/), and then download and install Git for Windows. -Open the [Git website](https://git-scm.com/) and download and install Git for Windows. +## After you install Git -Next, read our article on [adding an SSH key to GitLab](../../../ssh/index.md). +After you successfully install Git on your computer, read about [adding an SSH key to GitLab](../../../ssh/index.md). <!-- ## Troubleshooting diff --git a/doc/topics/git/lfs/index.md b/doc/topics/git/lfs/index.md index 0fe38e25df5..a94caf2bf33 100644 --- a/doc/topics/git/lfs/index.md +++ b/doc/topics/git/lfs/index.md @@ -99,7 +99,7 @@ and are not pushed to the remote repository. ### Migrate an existing repository to Git LFS -Read the documentation on how to [migrate an existing Git repository with Git LFS](migrate_to_git_lfs.md). +Read the documentation on how to [migrate an existing Git repository with Git LFS](https://github.com/git-lfs/git-lfs/blob/main/docs/man/git-lfs-migrate.1.ronn). ### Removing objects from LFS @@ -114,13 +114,9 @@ See the documentation on [File Locking](../../../user/project/file_lock.md). ## LFS objects in project archives -> - Support for including Git LFS blobs inside [project source downloads](../../../user/project/repository/index.md) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/268409) in GitLab 13.6. -> - Enabled on GitLab.com. -> - Recommended for production use. - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) support for including Git LFS blobs inside [project source downloads](../../../user/project/repository/index.md) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `include_lfs_blobs_in_archive`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46572) in GitLab 13.6. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62539) in GitLab 14.0. Feature flag `include_lfs_blobs_in_archive` removed. Prior to GitLab 13.5, [project source downloads](../../../user/project/repository/index.md) would include Git diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index ae1667376b0..f881826e74a 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -45,7 +45,7 @@ set to 50MB. The default is 1MB. **If pushing over SSH**, first check your SSH configuration as 'Broken pipe' errors can sometimes be caused by underlying issues with SSH (such as authentication). Make sure that SSH is correctly configured by following the -instructions in the [SSH troubleshooting](../../ssh/index.md#troubleshooting-ssh-connections) documentation. +instructions in the [SSH troubleshooting](../../ssh/index.md#password-prompt-with-git-clone) documentation. If you're a GitLab administrator with server access, you can also prevent session timeouts by configuring SSH `keep-alive` on the client or the server. @@ -110,6 +110,13 @@ ssh_exchange_identification: Connection closed by remote host fatal: The remote end hung up unexpectedly ``` +or + +```plaintext +kex_exchange_identification: Connection closed by remote host +Connection closed by x.x.x.x port 22 +``` + This error usually indicates that SSH daemon's `MaxStartups` value is throttling SSH connections. This setting specifies the maximum number of concurrent, unauthenticated connections to the SSH daemon. This affects users with proper authentication diff --git a/doc/topics/gitlab_flow.md b/doc/topics/gitlab_flow.md index e831c35a8ea..7675bba8d83 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/#assignments" +info: To 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' --- @@ -47,9 +47,11 @@ For a video introduction of how this works in GitLab, see [GitLab Flow](https:// <!-- vale gitlab.Spelling = YES --> -Git flow was one of the first proposals to use Git branches, and it has received a lot of attention. -It suggests a `main` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes. -The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `main` branch. +Git flow was one of the first proposals to use Git branches, and it has received +a lot of attention. It suggests a `main` branch and a separate `develop` branch, +with supporting branches for features, releases, and hotfixes. The development +happens on the `develop` branch, moves to a release branch, and is finally merged +into the `main` branch. Git flow is a well-defined standard, but its complexity introduces two problems. The first problem is that developers must use the `develop` branch and not `main`. `main` is reserved for code that is released to production. diff --git a/doc/topics/release_your_application.md b/doc/topics/release_your_application.md index cbd7cfab720..3a0080fe21c 100644 --- a/doc/topics/release_your_application.md +++ b/doc/topics/release_your_application.md @@ -1,6 +1,6 @@ --- -stage: -group: +stage: none +group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -9,6 +9,58 @@ info: To determine the technical writer assigned to the Stage/Group associated w Deploy your application internally or to the public. Use flags to release features incrementally. -- [Environments and deployments](../ci/environments/index.md) -- [Releases](../user/project/releases/index.md) -- [Feature flags](../operations/feature_flags.md) +## Deployments + +Deployment is the step of the software delivery process when your application gets deployed to its +final, target infrastructure. + +### Deploy with Auto DevOps + +[Auto DevOps](autodevops/index.md) is an automated CI/CD-based workflow that supports the entire software +supply chain: build, test, lint, package, deploy, secure, and monitor applications using GitLab CI/CD. +It provides a set of ready-to-use templates that serve the vast majority of use cases. + +[Auto Deploy](autodevops/stages.md#auto-deploy) is the DevOps stage dedicated to software +deployment using GitLab CI/CD. + +### Deploy applications to Kubernetes clusters + +With the extensive integration between GitLab and Kubernetes, you can safely deploy your applications +to Kubernetes clusters using the [GitLab Agent](../user/clusters/agent/install/index.md). + +#### GitOps deployments **(PREMIUM)** + +With the [GitLab Agent](../user/clusters/agent/install/index.md), you can perform pull-based +deployments using Kubernetes manifests. This provides a scalable, secure, and cloud-native +approach to manage Kubernetes deployments. + +#### Deploy to Kubernetes with the CI/CD Tunnel + +With the [GitLab Agent](../user/clusters/agent/install/index.md), you can perform push-based +deployments with the [CI/CD Tunnel](../user/clusters/agent/ci_cd_tunnel.md). It provides +a secure and reliable connection between GitLab and your Kubernetes cluster. + +### Deploy to AWS with GitLab CI/CD + +GitLab provides Docker images that you can use to run AWS commands from GitLab CI/CD, and a template to +facilitate [deployment to AWS](../ci/cloud_deployment). Moreover, Auto Deploy has built-in support +for EC2 and ECS deployments. + +### General software deployment with GitLab CI/CD + +You can use GitLab CI/CD to target any type of infrastructure accessible by the GitLab Runner. +[User and pre-defined environment variables](../ci/variables/index.md) and CI/CD templates +support setting up a vast number of deployment strategies. + +## Environments + +To keep track of your deployments and gain insights into your infrastructure, we recommend +connecting them to [a GitLab Environment](../ci/environments/index.md). + +## Releases + +Use GitLab [Releases](../user/project/releases/index.md) to plan, build, and deliver your applications. + +### Feature flags + +Use [feature flags](../operations/feature_flags.md) to control and strategically roullout application deployments. diff --git a/doc/topics/set_up_organization.md b/doc/topics/set_up_organization.md index 3758435d297..3f8a00f9981 100644 --- a/doc/topics/set_up_organization.md +++ b/doc/topics/set_up_organization.md @@ -1,6 +1,6 @@ --- -stage: -group: +stage: none +group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/topics/use_gitlab.md b/doc/topics/use_gitlab.md index f73e41c251b..a7189284fe6 100644 --- a/doc/topics/use_gitlab.md +++ b/doc/topics/use_gitlab.md @@ -1,6 +1,6 @@ --- -stage: -group: +stage: none +group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/tutorials/index.md b/doc/tutorials/index.md new file mode 100644 index 00000000000..1f866aeb889 --- /dev/null +++ b/doc/tutorials/index.md @@ -0,0 +1,123 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Get started with GitLab tutorials + +These tutorials can help you learn how to use GitLab. + +## Find your way around GitLab + +Get to know the features of GitLab and where to find them so you can get up +and running quickly. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [GitLab 101](https://gitlab.edcast.com/pathways/copy-of-gitlab-certification) | Learn the basics of GitLab in this certification course. | **{star}** | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Use GitLab for DevOps](https://www.youtube.com/watch?v=7q9Y1Cv-ib0) (12m 34s) | Use GitLab through the entire DevOps lifecycle, from planning to monitoring. | **{star}** | +| [Use Markdown at GitLab](../user/markdown.md) | GitLab Flavored Markdown (GFM) is used in many areas of GitLab, for example, in merge requests. | **{star}** | +| [GitLab 201](https://gitlab.edcast.com/pathways/ECL-44010cf6-7a9c-4b9b-b684-fa08508a3252) | Go beyond the basics to learn more about using GitLab for your work. | | +| Learn GitLab project | You might already have the **Learn GitLab** project, which has tutorial-style issues to help you learn GitLab. If not, download [this export file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/project_templates/learn_gitlab_ultimate.tar.gz) and [import it to a new project](../user/project/settings/import_export.md#import-a-project-and-its-data). | | +| [Productivity tips](https://about.gitlab.com/blog/2021/02/18/improve-your-gitlab-productivity-with-these-10-tips/) | Get tips to help make you a productive GitLab user. | | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Structure a multi-team organization](https://www.youtube.com/watch?v=KmASFwSap7c) (37m 37s) | Learn to use issues, milestones, epics, labels, and more to plan and manage your work. | | + +## Use Git + +GitLab is a Git-based platform, so understanding Git is important to get +the most out of GitLab. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Start using Git on the command line](../gitlab-basics/start-using-git.md) | Learn how to set up Git, clone repositories, and work with branches. | **{star}** | +| [Git cheat sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) | Download a PDF of common Git commands. | | + +## Plan your work in projects + +Your work takes place in a project, from creating code, to planning, +collaborating, and more. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Create a project from a template](https://gitlab.com/projects/new#create_from_template) | For hands-on learning, select **Sample GitLab Project** and create a project with example issues and merge requests. | **{star}** | +| [Migrate to GitLab](../user/project/import/index.md) | If you are coming to GitLab from another platform, you can import or convert your projects. | | + +## Use CI/CD pipelines + +CI/CD pipelines are used to automatically build, test, and deploy your code. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Get started: Create a pipeline](../ci/quick_start/index.md) | Create a `.gitlab-ci.yml` file and start a pipeline. | **{star}** | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Get started: Learn about CI/CD](https://www.youtube.com/watch?v=sIegJaLy2ug) (9m 02s) | Learn about the `.gitlab-ci.yml` file and how it's used. | **{star}** | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [CI deep dive](https://www.youtube.com/watch?v=ZVUbmVac-m8&list=PL05JrBw4t0KorkxIFgZGnzzxjZRCGROt_&index=27) (22m 51s) | Take a closer look at pipelines and continuous integration concepts. | | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [CD deep dive](https://www.youtube.com/watch?v=Cn0rzND-Yjw&list=PL05JrBw4t0KorkxIFgZGnzzxjZRCGROt_&index=10) (47m 54s) | Learn about deploying in GitLab. | | +| [Set up CI/CD in the cloud](../ci/examples/index.md#cicd-in-the-cloud) | Learn how to set up CI/CD in different cloud-based environments. | | +| [Find CI/CD examples and templates](../ci/examples/index.md#cicd-examples) | Use these examples and templates to set up CI/CD for your use case. | | +| <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [Understand CI/CD rules](https://www.youtube.com/watch?v=QjQc-zeL16Q) (8m 56s) | Learn more about how to use CI/CD rules. | | + +## Configure your applications and infrastructure + +Use GitLab configuration features to reduce the effort needed to +configure the infrastructure for your application. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Connect with a Kubernetes cluster](https://about.gitlab.com/blog/2021/11/18/gitops-with-gitlab-connecting-the-cluster/) | Connect a Kubernetes cluster with GitLab for pull and push based deployments and security integrations. | | +| [Use Auto DevOps to deploy an application](../topics/autodevops/quick_start_guide.md) | Deploy an application to Google Kubernetes Engine (GKE). | | + +## Publish a static website + +Use GitLab Pages to publish a static website directly from your project. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Create a Pages website from a CI/CD template](../user/project/pages/getting_started/pages_ci_cd_template.md) | Quickly generate a Pages website for your project using a CI/CD template for a popular Static Site Generator (SSG). | **{star}** | +| [Create a Pages website from scratch](../user/project/pages/getting_started/pages_from_scratch.md) | Create all the components of a Pages website from a blank project. | | + +## Secure your application + +GitLab can check your application for security vulnerabilities. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Set up dependency scanning](https://about.gitlab.com/blog/2021/01/14/try-dependency-scanning/) | Try out dependency scanning, which checks for known vulnerabilities in dependencies. | **{star}** | + +## Work with a self-managed instance + +If you're an administrator of a self-managed instance of GitLab, these tutorials +can help you manage and configure your instance. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Install GitLab](../install/index.md) | Install GitLab according to your requirements.| | +| [Get started administering GitLab](../administration/get_started.md) | Configure your organization and its authentication, then secure, monitor, and back up GitLab. | | +| [Secure your instance](https://about.gitlab.com/blog/2020/05/20/gitlab-instance-security-best-practices/) | Implement security features for your instance. | | + +## Integrate with GitLab + +GitLab [integrates](../integration/index.md) with a number of third-party services, +enabling you to work with those services directly from GitLab. + +| Topic | Description | Good for beginners | +|-------|-------------|--------------------| +| [Integrate with Jira](https://about.gitlab.com/blog/2021/04/12/gitlab-jira-integration-selfmanaged/) | Configure the Jira integration, so you can work with Jira issues from GitLab. | | +| [Integrate with Gitpod](https://about.gitlab.com/blog/2021/07/19/teams-gitpod-integration-gitlab-speed-up-development/) | Integrate with Gitpod, to help speed up your development. | | + +## Find more tutorial content + +If you're learning about GitLab, here are some ways you can find more tutorial +content: + +- Find learning tracks and certification options at [GitLab Learn](https://about.gitlab.com/learn/). + GitLab learning platform login required (email and password for non-GitLab team members). + For more information, see [First time login details](https://about.gitlab.com/handbook/people-group/learning-and-development/gitlab-learn/user/#first-time-login-to-gitlab-learn). + +- Find recent tutorials on the GitLab blog by [searching by the `tutorial` tag](https://about.gitlab.com/blog/tags.html#tutorial). + +- Browse the **Learn@GitLab** [playlist on YouTube](https://www.youtube.com/playlist?list=PLFGfElNsQthYDx0A_FaNNfUm9NHsK6zED) + to find video tutorials. + +If you find an article, video, or other resource that would be a +great addition to this page, add it in a [merge request](../development/documentation/index.md). diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md index 8bf14bc2dce..7388f4baf83 100644 --- a/doc/update/deprecations.md +++ b/doc/update/deprecations.md @@ -4,7 +4,7 @@ group: none info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" --- -# Deprecated feature removal schedule +# Deprecations by milestone DISCLAIMER: This page contains information related to upcoming products, features, and functionality. @@ -36,68 +36,118 @@ For deprecation reviewers (Technical Writers only): https://about.gitlab.com/handbook/marketing/blog/release-posts/#update-the-deprecations-doc --> -## 14.5 - -### Rename Task Runner pod to Toolbox - -The Task Runner pod is used to execute periodic housekeeping tasks within the GitLab application and is often confused with the GitLab Runner. Thus, [Task Runner will be renamed to Toolbox](https://gitlab.com/groups/gitlab-org/charts/-/epics/25). +## 14.0 -This will result in the rename of the sub-chart: `gitlab/task-runner` to `gitlab/toolbox`. Resulting pods will be named along the lines of `{{ .Release.Name }}-toolbox`, which will often be `gitlab-toolbox`. They will be locatable with the label `app=toolbox`. +### NFS for Git repository storage deprecated -Announced: 2021-08-22 -Planned removal: 2021-11-22 +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. -## 14.6 +With the general availability of Gitaly Cluster ([introduced in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/)), we have deprecated development (bugfixes, performance improvements, etc) for NFS for Git repository storage in GitLab 14.0. We will continue to provide technical support for NFS for Git repositories throughout 14.x, but we will remove all support for NFS in GitLab 15.0. Please see our official [Statement of Support](https://about.gitlab.com/support/statement-of-support.html#gitaly-and-nfs) for further information. -### Release CLI be distributed as a generic package +Gitaly Cluster offers tremendous benefits for our customers such as: -The [release-cli](https://gitlab.com/gitlab-org/release-cli) will be released as a [generic package](https://gitlab.com/gitlab-org/release-cli/-/packages) starting in GitLab 14.2. We will continue to deploy it as a binary to S3 until GitLab 14.5 and stop distributing it in S3 in GitLab 14.6. +- [Variable replication factors](https://docs.gitlab.com/ee/administration/gitaly/index.html#replication-factor). +- [Strong consistency](https://docs.gitlab.com/ee/administration/gitaly/index.html#strong-consistency). +- [Distributed read capabilities](https://docs.gitlab.com/ee/administration/gitaly/index.html#distributed-reads). -Announced: 2021-08-22 -Planned removal: 2021-12-22 +We encourage customers currently using NFS for Git repositories to plan their migration by reviewing our documentation on [migrating to Gitaly Cluster](https://docs.gitlab.com/ee/administration/gitaly/index.html#migrate-to-gitaly-cluster). -## 14.8 +**Planned removal milestone: 15.0 (2022-05-22)** -### openSUSE Leap 15.2 packages +## 14.2 -Distribution support and security updates for openSUSE Leap 15.2 are [ending December 2021](https://en.opensuse.org/Lifetime#openSUSE_Leap). +### Release CLI distributed as a generic package -Starting in 14.5 we are providing packages for openSUSE Leap 15.3, and will stop providing packages for openSUSE Leap 15.2 in the 14.8 milestone. +The [release-cli](https://gitlab.com/gitlab-org/release-cli) will be released as a [generic package](https://gitlab.com/gitlab-org/release-cli/-/packages) starting in GitLab 14.2. We will continue to deploy it as a binary to S3 until GitLab 14.5 and stop distributing it in S3 in GitLab 14.6. -Announced: 2021-11-22 -Planned removal: 2022-02-22 +**Planned removal milestone: 14.6 (2021-12-22)** -## 15.0 +### Rename Task Runner pod to Toolbox -### API: `stale` status returned instead of `offline` or `not_connected` +The Task Runner pod is used to execute periodic housekeeping tasks within the GitLab application and is often confused with the GitLab Runner. Thus, [Task Runner will be renamed to Toolbox](https://gitlab.com/groups/gitlab-org/charts/-/epics/25). -A breaking change will occur for the Runner [API](https://docs.gitlab.com/ee/api/runners.html#runners-api) endpoints in 15.0. +This will result in the rename of the sub-chart: `gitlab/task-runner` to `gitlab/toolbox`. Resulting pods will be named along the lines of `{{ .Release.Name }}-toolbox`, which will often be `gitlab-toolbox`. They will be locatable with the label `app=toolbox`. -Instead of the GitLab Runner API endpoints returning `offline` and `not_connected` for runners that have not contacted the GitLab instance in the past three months, the API endpoints will return the `stale` value, which was introduced in 14.6. +**Planned removal milestone: 14.5 (2021-11-22)** -Announced: 2021-12-22 -Planned removal: 2022-05-22 +## 14.3 ### Audit events for repository push events +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + Audit events for [repository events](https://docs.gitlab.com/ee/administration/audit_events.html#repository-push) are now deprecated and will be removed in GitLab 15.0. These events have always been disabled by default and had to be manually enabled with a feature flag. Enabling them can cause too many events to be generated which can dramatically slow down GitLab instances. For this reason, they are being removed. -Announced: 2021-09-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** -### CI/CD job name length limit +### GitLab Serverless -In GitLab 15.0 we are going to limit the number of characters in CI/CD job names to 255. Any pipeline with job names that exceed the 255 character limit will stop working after the 15.0 release. +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +[GitLab Serverless](https://docs.gitlab.com/ee/user/project/clusters/serverless/) is a feature set to support Knative-based serverless development with automatic deployments and monitoring. + +We decided to remove the GitLab Serverless features as they never really resonated with our users. Besides, given the continuous development of Kubernetes and Knative, our current implementations do not even work with recent versions. -Announced: 2021-12-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** + +### Legacy database configuration + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +The syntax of [GitLabs database](https://docs.gitlab.com/omnibus/settings/database.html) +configuration located in `database.yml` is changing and the legacy format is deprecated. The legacy format +supported using a single PostgreSQL adapter, whereas the new format is changing to support multiple databases. The `main:` database needs to be defined as a first configuration item. + +This deprecation mainly impacts users compiling GitLab from source because Omnibus will handle this configuration automatically. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### OmniAuth Kerberos gem + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +The `omniauth-kerberos` gem will be removed in our next major release, GitLab 15.0. + +This gem has not been maintained and has very little usage. We therefore plan to remove support for this authentication method and recommend using the Kerberos [SPNEGO](https://en.wikipedia.org/wiki/SPNEGO) integration instead. You can follow the [upgrade instructions](https://docs.gitlab.com/ee/integration/kerberos.html#upgrading-from-password-based-to-ticket-based-kerberos-sign-ins) to upgrade from the `omniauth-kerberos` integration to the supported one. + +Note that we are not deprecating the Kerberos SPNEGO integration, only the old password-based Kerberos integration. + +**Planned removal milestone: 15.0 (2022-05-22)** + +## 14.5 ### Certificate-based integration with Kubernetes +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + [We are deprecating the certificate-based integration with Kubernetes](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/). The timeline of removal of the integration from the product is not yet planned and we will communicate more details as they emerge. The certificate-based integration will continue to receive security and @@ -108,227 +158,561 @@ For updates and details, follow this [epic](https://gitlab.com/groups/gitlab-org For a more robust, secure, forthcoming, and reliable integration with Kubernetes, we recommend the use of the [Kubernetes Agent](https://docs.gitlab.com/ee/user/clusters/agent/) to connect Kubernetes clusters with GitLab. -Announced: 2021-11-15 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** ### Converting an instance (shared) runner to a project (specific) runner is deprecated +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + In GitLab 15.0, we will remove the feature that enables you to convert an instance (shared) runner to a project (specific) runner. Users who need to add a runner to only a particular project can register a runner to the project directly. -Announced: 2021-11-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** ### Deprecate `Versions` on base `PackageType` +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + As part of the work to create a [Package Registry GraphQL API](https://gitlab.com/groups/gitlab-org/-/epics/6318), the Package group deprecated the `Version` type for the basic `PackageType` type and moved it to [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/index.html#packagedetailstype). In milestone 15.0, we will completely remove `Version` from `PackageType`. -Announced: 2021-11-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** + +### Deprecate support for SLES 12 SP2 + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 12 SP2 [ended on March 31, 2021](https://www.suse.com/lifecycle/). The CA certificates on SP2 include the expired DST root certificate, and it's not getting new CA certificate package updates. We have implemented some [workarounds](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/merge_requests/191), but we will not be able to continue to keep the build running properly. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Known host required for GitLab Runner SSH executor + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3074), we added a configuration setting in the GitLab Runner `config.toml` file. This setting, [`[runners.ssh.disable_strict_host_key_checking]`](https://docs.gitlab.com/runner/executors/ssh.html#security), controls whether or not to use strict host key checking with the SSH executor. + +In GitLab 15.0 and later, the default value for this configuration option will change from `true` to `false`. This means that strict host key checking will be enforced when using the GitLab Runner SSH executor. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Must explicitly assign `AuthenticationType` for `[runners.cache.s3]` + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +In GitLab 15.0 and later, to access the AWS S3 cache, you must specify the `AuthenticationType` for [`[runners.cache.s3]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscaches3-section). The `AuthenticationType` must be `IAM` or `credentials`. + +Prior to 14.5, if you did not define the `AuthenticationType`, GitLab Runner chose a type for you. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Package pipelines in API payload is paginated + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +A request to the API for `/api/v4/projects/:id/packages` returns a paginated result of packages. Each package lists all of its pipelines in this response. This is a performance concern, as it's possible for a package to have hundreds or thousands of associated pipelines. + +In milestone 15.0, we will remove the `pipelines` attribute from the API response. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### REST API Runner will not contain `paused` + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +The GitLab Runner REST and GraphQL API endpoints will not return `paused` or `active` as a status in GitLab 15.0. + +A runner's status will only relate to runner contact status, such as: +`online`, `offline`, or `not_connected`. Status `paused` or `active` will no longer appear. + +When checking if a runner is `paused`, API users are advised to check the boolean attribute +`active` to be `false` instead. When checking if a runner is `active`, check if `active` is `true`. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Removal of `defaultMergeCommitMessageWithDescription` GraphQL API field + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +The GraphQL API field `defaultMergeCommitMessageWithDescription` has been deprecated and will be removed in GitLab 15.0. For projects with a commit message template set, it will ignore the template. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Removal of `promote-db` command from `gitlab-ctl` + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-db` which is used to promote database nodes in multi-node Geo secondary sites. `gitlab-ctl promote-db` will continue to function as-is and be available until GitLab 15.0. We recommend that Geo customers begin testing the new `gitlab-ctl promote` command in their staging environments and incorporating the new command in their failover procedures. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Removal of `promote-to-primary-node` command from `gitlab-ctl` + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-to-primary-node` which was only usable for single-node Geo sites. `gitlab-ctl promote-to-primary-node` will continue to function as-is and be available until GitLab 15.0. We recommend that Geo customers begin testing the new `gitlab-ctl promote` command in their staging environments and incorporating the new command in their failover procedures. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Remove the `:dependency_proxy_for_private_groups` feature flag + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +We added a feature flag because [GitLab-#11582](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) changed how public groups use the Dependency Proxy. Prior to this change, you could use the Dependency Proxy without authentication. The change requires authentication to use the Dependency Proxy. + +In milestone 15.0, we will remove the feature flag entirely. Moving forward, you must authenticate when using the Dependency Proxy. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Remove the `pipelines` field from the `version` field + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +In GraphQL, there are two `pipelines` fields that you can use in a [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/#packagedetailstype) to get the pipelines for package versions: + +- The `versions` field's `pipelines` field. This returns all the pipelines associated with all the package's versions, which can pull an unbounded number of objects in memory and create performance concerns. +- The `pipelines` field of a specific `version`. This returns only the pipelines associated with that single package version. + +To mitigate possible performance problems, we will remove the `versions` field's `pipelines` field in milestone 15.0. Although you will no longer be able to get all pipelines for all versions of a package, you can still get the pipelines of a single version through the remaining `pipelines` field for that version. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Update to the Container Registry group-level API + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +In milestone 15.0, support for the `tags` and `tags_count` parameters will be removed from the Container Registry API that [gets registry repositories from a group](../api/container_registry.md#within-a-group). + +The `GET /groups/:id/registry/repositories` endpoint will remain, but won't return any info about tags. To get the info about tags, you can use the existing `GET /registry/repositories/:id` endpoint, which will continue to support the `tags` and `tag_count` options as it does today. The latter must be called once per image repository. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Value Stream Analytics filtering calculation change + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +We are changing how the date filter works in Value Stream Analytics. Instead of filtering by the time that the issue or merge request was created, the date filter will filter by the end event time of the given stage. This will result in completely different figures after this change has rolled out. + +If you monitor Value Stream Analytics metrics and rely on the date filter, to avoid losing data, you must save the data prior to this change. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### openSUSE Leap 15.2 packages + +Distribution support and security updates for openSUSE Leap 15.2 are [ending December 2021](https://en.opensuse.org/Lifetime#openSUSE_Leap). + +Starting in 14.5 we are providing packages for openSUSE Leap 15.3, and will stop providing packages for openSUSE Leap 15.2 in the 14.8 milestone. + +**Planned removal milestone: 14.8 (2022-02-22)** + +## 14.6 + +### API: `stale` status returned instead of `offline` or `not_connected` + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +A breaking change will occur for the Runner [API](https://docs.gitlab.com/ee/api/runners.html#runners-api) endpoints in 15.0. + +Instead of the GitLab Runner API endpoints returning `offline` and `not_connected` for runners that have not contacted the GitLab instance in the past three months, the API endpoints will return the `stale` value, which was introduced in 14.6. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### CI/CD job name length limit + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +In GitLab 15.0 we are going to limit the number of characters in CI/CD job names to 255. Any pipeline with job names that exceed the 255 character limit will stop working after the 15.0 release. + +**Planned removal milestone: 15.0 (2022-05-22)** ### Deprecate `pipelines` fields in the Package GraphQL types +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + As part of the work to create a [Package Registry GraphQL API](https://gitlab.com/groups/gitlab-org/-/epics/6318), the Package group deprecated the `pipelines` fields in all Package-related GraphQL types. As of GitLab 14.6, the `pipelines` field is deprecated in [`Package`](https://docs.gitlab.com/ee/api/graphql/reference/index.html#package) and [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/index.html#packagedetailstype) due to scalability and performance concerns. In milestone 15.0, we will completely remove `pipelines` from `Package` and `PackageDetailsType`. You can follow and contribute to work on a replacement in the epic [GitLab-#7214](https://gitlab.com/groups/gitlab-org/-/epics/7214). -Announced: 2021-12-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** ### Deprecate legacy approval status names from License Compliance API -We deprecated legacy names for approval status of license policy (blacklisted, approved) in the `managed_licenses` API but they are still used in our API queries and responses. They will be removed in 15.0. - -If you are using our License Compliance API you should stop using the `approved` and `blacklisted` query parameters, they are now `allowed` and `denied`. In 15.0 the responses will also stop using `approved` and `blacklisted` so you need to adjust any of your custom tools to use the old and new values so they do not break with the 15.0 release. +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. -Announced: 2021-12-22 -Planned removal: 2022-05-22 +We deprecated legacy names for approval status of license policy (blacklisted, approved) in the `managed_licenses` API but they are still used in our API queries and responses. They will be removed in 15.0. -### Deprecate support for SLES 12 SP2 - -Long term service and support (LTSS) for SUSE Linux Enterprise Server (SLES) 12 SP2 [ended on March 31, 2021](https://www.suse.com/lifecycle/). The CA certificates on SP2 include the expired DST root certificate, and it's not getting new CA certificate package updates. We have implemented some [workarounds](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/merge_requests/191), but we will not be able to continue to keep the build running properly. +If you are using our License Compliance API you should stop using the `approved` and `blacklisted` query parameters, they are now `allowed` and `denied`. In 15.0 the responses will also stop using `approved` and `blacklisted` so you need to adjust any of your custom tools to use the old and new values so they do not break with the 15.0 release. -Announced: 2021-11-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** ### Deprecation of Runner status `not_connected` API value +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + The GitLab Runner REST and GraphQL [API](https://docs.gitlab.com/ee/api/runners.html#runners-api) endpoints will return `never_contacted` instead of `not_connected` as the status values in 15.0. Runners that have never contacted the GitLab instance will also return `stale` if created more than 3 months ago. -Announced: 2021-12-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** ### Deprecation of bundler-audit Dependency Scanning tool -As of 14.6 bundler-audit is being deprecated from Dependency Scanning. It will continue to be in our CI/CD template while deprecated. We are removing bundler-audit from Dependency Scanning on May 22, 2022 in 15.0. After this removal Ruby scanning functionality will not be affected as it is still being covered by Gemnasium. +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +As of 14.6 bundler-audit is being deprecated from Dependency Scanning. It will continue to be in our CI/CD template while deprecated. We are removing bundler-audit from Dependency Scanning on May 22, 2022 in 15.0. After this removal Ruby scanning functionality will not be affected as it is still being covered by Gemnasium. If you have explicitly excluded bundler-audit using DS_EXCLUDED_ANALYZERS you will need to clean up (remove the reference) in 15.0. If you have customized your pipeline's Dependency Scanning configuration, for example to edit the `bundler-audit-dependency_scanning` job, you will want to switch to gemnasium-dependency_scanning before removal in 15.0, to prevent your pipeline from failing. If you have not used the DS_EXCLUDED_ANALYZERS to reference bundler-audit, or customized your template specifically for bundler-audit, you will not need to take action. -Announced: 2021-12-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** -### GitLab Serverless +### Remove `type` and `types` keyword in CI/CD configuration -[GitLab Serverless](https://docs.gitlab.com/ee/user/project/clusters/serverless/) is a feature set to support Knative-based serverless development with automatic deployments and monitoring. +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. -We decided to remove the GitLab Serverless features as they never really resonated with our users. Besides, given the continuous development of Kubernetes and Knative, our current implementations do not even work with recent versions. +The `type` and `types` CI/CD keywords will be removed in GitLab 15.0. Pipelines that use these keywords will stop working, so you must switch to `stage` and `stages`, which have the same behavior. -Announced: 2021-09-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** -### Known host required for GitLab Runner SSH executor +### apiFuzzingCiConfigurationCreate GraphQL mutation -In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/3074), we added a configuration setting in the GitLab Runner `config.toml` file. This setting, [`[runners.ssh.disable_strict_host_key_checking]`](https://docs.gitlab.com/runner/executors/ssh.html#security), controls whether or not to use strict host key checking with the SSH executor. +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. -In GitLab 15.0 and later, the default value for this configuration option will change from `true` to `false`. This means that strict host key checking will be enforced when using the GitLab Runner SSH executor. +The API Fuzzing configuration snippet is now being generated client-side and does not require an +API request anymore. We are therefore deprecating the `apiFuzzingCiConfigurationCreate` mutation +which isn't being used in GitLab anymore. -Announced: 2021-11-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** -### Legacy database configuration +## 14.7 -The syntax of [GitLabs database](https://docs.gitlab.com/omnibus/settings/database.html) -configuration located in `database.yml` is changing and the legacy format is deprecated. The legacy format -supported using a single PostgreSQL adapter, whereas the new format is changing to support multiple databases. The `main:` database needs to be defined as a first configuration item. +### Container scanning schemas below 14.0.0 -This deprecation mainly impacts users compiling GitLab from source because Omnibus will handle this configuration automatically. +[Container scanning report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) +versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation +against the schema version declared in the report will also no longer be supported in GitLab 15.0. -Announced: 2021-09-22 -Planned removal: 2022-05-22 +Third-party tools that [integrate with GitLab by outputting a container scanning security report](https://docs.gitlab.com/ee/development/integrations/secure.html#report) +as a pipeline job artifact are affected. You must ensure that all output reports adhere to the correct schema with a minimum version of 14.0.0. Reports with a lower version or that fail to validate against the declared schema version will not be processed, and vulnerability findings will not display in MRs, pipelines, or Vulnerability Reports. -### Must explicitly assign `AuthenticationType` for `[runners.cache.s3]` +To help with the transition, from GitLab 14.10, non-compliant reports will display a +[warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) +in the Vulnerability Report. -In GitLab 15.0 and later, to access the AWS S3 cache, you must specify the `AuthenticationType` for [`[runners.cache.s3]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscaches3-section). The `AuthenticationType` must be `IAM` or `credentials`. +**Planned removal milestone: 15.0 (2022-05-22)** -Prior to 14.5, if you did not define the `AuthenticationType`, GitLab Runner chose a type for you. +### Coverage guided fuzzing schemas below 14.0.0 -Announced: 2021-11-22 -Planned removal: 2022-05-22 +[Coverage guided fuzzing report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) +below version 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation +against the schema version declared in the report will also no longer be supported in GitLab 15.0. -### NFS for Git repository storage deprecated +Third-party tools that [integrate with GitLab by outputting a coverage guided fuzzing security report](https://docs.gitlab.com/ee/development/integrations/secure.html#report) +as a pipeline job artifact are affected. You must ensure that all output reports adhere to the correct +schema with a minimum version of 14.0.0. Any reports with a lower version or that fail to validate +against the declared schema version will not be processed, and vulnerability +findings will not display in MRs, pipelines, or Vulnerability Reports. -With the general availability of Gitaly Cluster ([introduced in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/)), we have deprecated development (bugfixes, performance improvements, etc) for NFS for Git repository storage in GitLab 14.0. We will continue to provide technical support for NFS for Git repositories throughout 14.x, but we will remove all support for NFS in GitLab 15.0. Please see our official [Statement of Support](https://about.gitlab.com/support/statement-of-support.html#gitaly-and-nfs) for further information. +To help with the transition, from GitLab 14.10, non-compliant reports will display a +[warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) +in the Vulnerability Report. -Gitaly Cluster offers tremendous benefits for our customers such as: +**Planned removal milestone: 15.0 (2022-05-22)** -- [Variable replication factors](https://docs.gitlab.com/ee/administration/gitaly/index.html#replication-factor). -- [Strong consistency](https://docs.gitlab.com/ee/administration/gitaly/index.html#strong-consistency). -- [Distributed read capabilities](https://docs.gitlab.com/ee/administration/gitaly/index.html#distributed-reads). +### DAST schemas below 14.0.0 -We encourage customers currently using NFS for Git repositories to plan their migration by reviewing our documentation on [migrating to Gitaly Cluster](https://docs.gitlab.com/ee/administration/gitaly/index.html#migrate-to-gitaly-cluster). +[DAST report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) +versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation +against the schema version declared in the report will also no longer be supported as of GitLab 15.0. -Announced: 2021-06-22 -Planned removal: 2022-05-22 +Third-party tools that [integrate with GitLab by outputting a DAST security report](https://docs.gitlab.com/ee/development/integrations/secure.html#report) +as a pipeline job artifact are affected. You must ensure that all output reports adhere to the correct +schema with a minimum version of 14.0.0. Reports with a lower version or that fail to validate +against the declared schema version will not be processed, and vulnerability +findings will not display in MRs, pipelines, or Vulnerability Reports. -### OmniAuth Kerberos gem +To help with the transition, from GitLab 14.10, non-compliant reports will cause a +[warning to be displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) +in the Vulnerability Report. -The `omniauth-kerberos` gem will be removed in our next major release, GitLab 15.0. +**Planned removal milestone: 15.0 (2022-05-22)** -This gem has not been maintained and has very little usage. We therefore plan to remove support for this authentication method and recommend using the Kerberos [SPNEGO](https://en.wikipedia.org/wiki/SPNEGO) integration instead. You can follow the [upgrade instructions](https://docs.gitlab.com/ee/integration/kerberos.html#upgrading-from-password-based-to-ticket-based-kerberos-sign-ins) to upgrade from the `omniauth-kerberos` integration to the supported one. +### Dependency scanning schemas below 14.0.0 -Note that we are not deprecating the Kerberos SPNEGO integration, only the old password-based Kerberos integration. +[Dependency scanning report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) +versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation +against the schema version declared in the report will also no longer be supported as of GitLab 15.0. -Announced: 2021-09-22 -Planned removal: 2022-05-22 +Third-party tools that [integrate with GitLab by outputting a Dependency scanning security report](https://docs.gitlab.com/ee/development/integrations/secure.html#report) +as a pipeline job artifact are affected. You must ensure that all output reports adhere to the correct +schema with a minimum version of 14.0.0. Reports with a lower version or that fail to validate +against the declared schema version will not be processed, and vulnerability +findings will not display in MRs, pipelines, or Vulnerability Reports. -### Package pipelines in API payload is paginated +To help with the transition, from GitLab 14.10, non-compliant reports will cause a +[warning to be displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) +in the Vulnerability Report. -A request to the API for `/api/v4/projects/:id/packages` returns a paginated result of packages. Each package lists all of its pipelines in this response. This is a performance concern, as it's possible for a package to have hundreds or thousands of associated pipelines. +**Planned removal milestone: 15.0 (2022-05-22)** -In milestone 15.0, we will remove the `pipelines` attribute from the API response. +### Enforced validation of security report schemas -Announced: 2021-11-22 -Planned removal: 2022-05-22 +[Security report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) +versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation +against the schema version declared in the report will also no longer be supported in GitLab 15.0. -### REST API Runner will not contain `paused` +Security tools that [integrate with GitLab by outputting security reports](https://docs.gitlab.com/ee/development/integrations/secure.html#report) +as pipeline job artifacts are affected. You must ensure that all output reports adhere to the correct +schema with a minimum version of 14.0.0. Reports with a lower version or that fail to validate +against the declared schema version will not be processed, and vulnerability +findings will not display in MRs, pipelines, or Vulnerability Reports. -The GitLab Runner REST and GraphQL API endpoints will not return `paused` or `active` as a status in GitLab 15.0. +To help with the transition, from GitLab 14.10, non-compliant reports will display a +[warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) +in the Vulnerability Report. -A runner's status will only relate to runner contact status, such as: -`online`, `offline`, or `not_connected`. Status `paused` or `active` will no longer appear. +**Planned removal milestone: 15.0 (2022-05-22)** -When checking if a runner is `paused`, API users are advised to check the boolean attribute -`active` to be `false` instead. When checking if a runner is `active`, check if `active` is `true`. +### Godep support in License Compliance -Announced: 2021-11-22 -Planned removal: 2022-05-22 +The Godep dependency manager for Golang was deprecated in 2020 by Go and +has been replaced with Go modules. +To reduce our maintenance cost we are deprecating License Compliance for Godep projects as of 14.7 +and will remove it in GitLab 15.0 -### Removal of `defaultMergeCommitMessageWithDescription` GraphQL API field +**Planned removal milestone: 15.0 (2022-05-22)** -The GraphQL API field `defaultMergeCommitMessageWithDescription` has been deprecated and will be removed in GitLab 15.0. For projects with a commit message template set, it will ignore the template. +### Logging in GitLab -Announced: 2021-11-22 -Planned removal: 2022-05-22 +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. -### Removal of `promote-db` command from `gitlab-ctl` +The logging features in GitLab allow users to install the ELK stack (Elasticsearch, Logstash, and Kibana) to aggregate and manage application logs. Users can search for relevant logs in GitLab. However, since deprecating certificate-based integration with Kubernetes clusters and GitLab Managed Apps, we don't have a recommended solution for logging within GitLab. For more information, you can follow the issue for [integrating Opstrace with GitLab](https://gitlab.com/groups/gitlab-org/-/epics/6976). -In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-db` which is used to promote database nodes in multi-node Geo secondary sites. `gitlab-ctl promote-db` will continue to function as-is and be available until GitLab 15.0. We recommend that Geo customers begin testing the new `gitlab-ctl promote` command in their staging environments and incorporating the new command in their failover procedures. +**Planned removal milestone: 15.0 (2022-05-22)** -Announced: 2021-11-22 -Planned removal: 2022-05-22 +### Monitor performance metrics through Prometheus -### Removal of `promote-to-primary-node` command from `gitlab-ctl` +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. -In GitLab 14.5, we introduced the command `gitlab-ctl promote` to promote any Geo secondary node to a primary during a failover. This command replaces `gitlab-ctl promote-to-primary-node` which was only usable for single-node Geo sites. `gitlab-ctl promote-to-primary-node` will continue to function as-is and be available until GitLab 15.0. We recommend that Geo customers begin testing the new `gitlab-ctl promote` command in their staging environments and incorporating the new command in their failover procedures. +By displaying data stored in a Prometheus instance, GitLab allows users to view performance metrics. GitLab also displays visualizations of these metrics in dashboards. The user can connect to a previously-configured external Prometheus instance, or set up Prometheus as a GitLab Managed App. +However, since certificate-based integration with Kubernetes clusters is deprecated in GitLab, the metrics functionality in GitLab that relies on Prometheus is also deprecated. This includes the metrics visualizations in dashboards. GitLab is working to develop a single user experience based on [Opstrace](https://about.gitlab.com/press/releases/2021-12-14-gitlab-acquires-opstrace-to-expand-its-devops-platform-with-open-source-observability-solution.html). An [issue exists](https://gitlab.com/groups/gitlab-org/-/epics/6976) for you to follow work on the Opstrace integration. -Announced: 2021-11-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** -### Remove `type` and `types` keyword in CI/CD configuration +### Pseudonymizer -The `type` and `types` CI/CD keywords will be removed in GitLab 15.0. Pipelines that use these keywords will stop working, so you must switch to `stage` and `stages`, which have the same behavior. +The Pseudonymizer feature is generally unused, +can cause production issues with large databases, +and can interfere with object storage development. +It is now considered deprecated, and will be removed in GitLab 15.0. -Announced: 2021-12-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-05-22)** -### Remove the `:dependency_proxy_for_private_groups` feature flag +### Removal of Static Site Editor -We added a feature flag because [GitLab-#11582](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) changed how public groups use the Dependency Proxy. Prior to this change, you could use the Dependency Proxy without authentication. The change requires authentication to use the Dependency Proxy. +The Static Site Editor will no longer be available starting in GitLab 15.0. Improvements to the Markdown editing experience across GitLab will deliver smiliar benefit but with a wider reach. Incoming requests to the Static Site Editor will be redirected to the Web IDE. Current users of the Static Site Editor can view the [documentation](https://docs.gitlab.com/ee/user/project/static_site_editor/) for more information, including how to remove the configuration files from existing projects. -In milestone 15.0, we will remove the feature flag entirely. Moving forward, you must authenticate when using the Dependency Proxy. +**Planned removal milestone: 15.0 (2022-05-22)** -Announced: 2021-11-22 -Planned removal: 2022-05-22 +### Removal of `artifacts:report:cobertura` keyword -### Remove the `pipelines` field from the `version` field +Currently, test coverage visualizations in GitLab only support Cobertura reports. Starting 15.0, the +`artifacts:report:cobertura` keyword will be replaced by +[`artifacts:reports:coverage_report`](https://gitlab.com/gitlab-org/gitlab/-/issues/344533). Cobertura will be the +only supported report file in 15.0, but this is the first step towards GitLab supporting other report types. -In GraphQL, there are two `pipelines` fields that you can use in a [`PackageDetailsType`](https://docs.gitlab.com/ee/api/graphql/reference/#packagedetailstype) to get the pipelines for package versions: +**Planned removal milestone: 15.0 (2022-05-22)** -- The `versions` field's `pipelines` field. This returns all the pipelines associated with all the package's versions, which can pull an unbounded number of objects in memory and create performance concerns. -- The `pipelines` field of a specific `version`. This returns only the pipelines associated with that single package version. +### SAST schemas below 14.0.0 -To mitigate possible performance problems, we will remove the `versions` field's `pipelines` field in milestone 15.0. Although you will no longer be able to get all pipelines for all versions of a package, you can still get the pipelines of a single version through the remaining `pipelines` field for that version. +[SAST report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) +versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation +against the schema version declared in the report will also no longer be supported as of GitLab 15.0. -Announced: 2021-11-22 -Planned removal: 2022-05-22 +Third-party tools that [integrate with GitLab by outputting a SAST security report](https://docs.gitlab.com/ee/development/integrations/secure.html#report) +as a pipeline job artifact are affected. You must ensure that all output reports adhere to the correct +schema with a minimum version of 14.0.0. Reports with a lower version or that fail to validate +against the declared schema version will not be processed, and vulnerability +findings will not display in MRs, pipelines, or Vulnerability Reports. -### Update to the Container Registry group-level API +To help with the transition, from GitLab 14.10, non-compliant reports will display a +[warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) +in the Vulnerability Report. -In milestone 15.0, support for the `tags` and `tags_count` parameters will be removed from the Container Registry API that [gets registry repositories from a group](../api/container_registry.md#within-a-group). +**Planned removal milestone: 15.0 (2022-05-22)** -The `GET /groups/:id/registry/repositories` endpoint will remain, but won't return any info about tags. To get the info about tags, you can use the existing `GET /registry/repositories/:id` endpoint, which will continue to support the `tags` and `tag_count` options as it does today. The latter must be called once per image repository. +### Secret detection schemas below 14.0.0 -Announced: 2021-11-22 -Planned removal: 2022-05-22 +[Secret detection report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) +versions earlier than 14.0.0 will no longer be supported in GitLab 15.0. Reports that do not pass validation +against the schema version declared in the report will also no longer be supported as of GitLab 15.0. -### Value Stream Analytics filtering calculation change +Third-party tools that [integrate with GitLab by outputting a Secret detection security report](https://docs.gitlab.com/ee/development/integrations/secure.html#report) +as a pipeline job artifact are affected. You must ensure that all output reports adhere to the correct +schema with a minimum version of 14.0.0. Reports with a lower version or that fail to validate +against the declared schema version will not be processed, and vulnerability +findings will not display in MRs, pipelines, or Vulnerability Reports. -We are changing how the date filter works in Value Stream Analytics. Instead of filtering by the time that the issue or merge request was created, the date filter will filter by the end event time of the given stage. This will result in completely different figures after this change has rolled out. +To help with the transition, from GitLab 14.10, non-compliant reports will display a +[warning](https://gitlab.com/gitlab-org/gitlab/-/issues/335789#note_672853791) +in the Vulnerability Report. -If you monitor Value Stream Analytics metrics and rely on the date filter, to avoid losing data, you must save the data prior to this change. +**Planned removal milestone: 15.0 (2022-05-22)** -Announced: 2021-11-22 -Planned removal: 2022-05-22 +### Sidekiq metrics and health checks configuration -### apiFuzzingCiConfigurationCreate GraphQL mutation +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. -The API Fuzzing configuration snippet is now being generated client-side and does not require an -API request anymore. We are therefore deprecating the `apiFuzzingCiConfigurationCreate` mutation -which isn't being used in GitLab anymore. +Exporting Sidekiq metrics and health checks using a single process and port is deprecated. +Support will be removed in 15.0. + +We have updated Sidekiq to export [metrics and health checks from two separate processes](https://gitlab.com/groups/gitlab-org/-/epics/6409) +to improve stability and availability and prevent data loss in edge cases. +As those are two separate servers, a configuration change will be required in 15.0 +to explicitly set separate ports for metrics and health-checks. +The newly introduced settings for `sidekiq['health_checks_*']` +should always be set in `gitlab.rb`. +For more information, check the documentation for [configuring Sidekiq](https://docs.gitlab.com/ee/administration/sidekiq.html). + +These changes also require updates in either Prometheus to scrape the new endpoint or k8s health-checks to target the new +health-check port to work properly, otherwise either metrics or health-checks will disappear. + +For the deprecation period those settings are optional +and GitLab will default the Sidekiq health-checks port to the same port as `sidekiq_exporter` +and only run one server (not changing the current behaviour). +Only if they are both set and a different port is provided, a separate metrics server will spin up +to serve the Sidekiq metrics, similar to the way Sidekiq will behave in 15.0. + +**Planned removal milestone: 15.0 (2022-05-22)** + +### Tracing in GitLab + +WARNING: +This feature will be changed or removed in 15.0 +as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes). +Before updating GitLab, review the details carefully to determine if you need to make any +changes to your code, settings, or workflow. + +Tracing in GitLab is an integration with Jaeger, an open-source end-to-end distributed tracing system. GitLab users can navigate to their Jaeger instance to gain insight into the performance of a deployed application, tracking each function or microservice that handles a given request. Tracing in GitLab is deprecated in GitLab 14.7, and scheduled for removal in 15.0. To track work on a possible replacement, see the issue for [Opstrace integration with GitLab](https://gitlab.com/groups/gitlab-org/-/epics/6976). + +**Planned removal milestone: 15.0 (2022-05-22)** + +### merged_by API field + +The `merged_by` field in the [merge request API](https://docs.gitlab.com/ee/api/merge_requests.html#list-merge-requests) is being deprecated and will be removed in GitLab 15.0. This field is being replaced with the `merge_user` field (already present in GraphQL) which more correctly identifies who merged a merge request when performing actions (merge when pipeline succeeds, add to merge train) other than a simple merge. + +**Planned removal milestone: 15.0 (2022-05-22)** + +## 14.8 + +### `fixup!` commit messages setting draft status of associated Merge Request + +The use of `fixup!` as a commit message to trigger draft status +of the associated Merge Request is generally unused, and can cause +confusion with other uses of the term. "Draft" is the preferred +and supported trigger for triggering draft status from commit +messages, as part of our streamlining of the feature. +Support for `fixup!` is now considered deprecated, and will be +removed in GitLab 15.0. -Announced: 2021-12-22 -Planned removal: 2022-05-22 +**Planned removal milestone: 15.0 (2022-06-22)** diff --git a/doc/update/index.md b/doc/update/index.md index 98dfee04a41..3a17d3c01d7 100644 --- a/doc/update/index.md +++ b/doc/update/index.md @@ -85,7 +85,7 @@ Certain releases may require different migrations to be finished before you update to the newer version. [Batched migrations](#batched-background-migrations) are a migration type available in GitLab 14.0 and later. -Background migrations and batched migrations not the same, so you should check that both are +Background migrations and batched migrations are not the same, so you should check that both are complete before updating. Decrease the time required to complete these migrations by increasing the number of @@ -98,7 +98,7 @@ that can process jobs in the `background_migration` queue. ```shell sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.remaining' -sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.pending' +sudo gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigrationJob.pending' ``` **For installations from source:** @@ -106,7 +106,7 @@ sudo gitlab-rails runner -e production 'puts Gitlab::BackgroundMigration.pending ```shell cd /home/git/gitlab sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.remaining' -sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::BackgroundMigration.pending' +sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::BackgroundMigrationJob.pending' ``` ### Batched background migrations @@ -193,9 +193,9 @@ To address the above two scenario's, it is advised to do the following prior to 1. Wait until all jobs are finished. 1. Upgrade GitLab. -## Checking for pending Advanced Search migrations +## Checking for pending Advanced Search migrations **(PREMIUM SELF)** -This section is only applicable if you have enabled the [Elasticsearch integration](../integration/elasticsearch.md). +This section is only applicable if you have enabled the [Elasticsearch integration](../integration/elasticsearch.md) **(PREMIUM SELF)**. Major releases require all [Advanced Search migrations](../integration/elasticsearch.md#advanced-search-migrations) to be finished from the most recent minor release in your current version @@ -239,14 +239,12 @@ It is required to follow the following upgrade steps to ensure a successful *maj Identify a [supported upgrade path](#upgrade-paths). -It's also important to ensure that any background migrations have been fully completed -before upgrading to a new major version. To see the current size of the `background_migration` queue, -[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). +It's also important to ensure that any [background migrations have been fully completed](#checking-for-background-migrations-before-upgrading) +before upgrading to a new major version. -If you have enabled the [Elasticsearch integration](../integration/elasticsearch.md), then ensure -all Advanced Search migrations are completed in the last minor version within -your current version. Be sure to -[check for pending Advanced Search migrations](#checking-for-pending-advanced-search-migrations) +If you have enabled the [Elasticsearch integration](../integration/elasticsearch.md) **(PREMIUM SELF)**, then +[ensure all Advanced Search migrations are completed](#checking-for-pending-advanced-search-migrations) in the last minor version within +your current version before proceeding with the major version upgrade. If your GitLab instance has any runners associated with it, it is very @@ -539,6 +537,31 @@ See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-g - See [Maintenance mode issue in GitLab 13.9 to 14.4](#maintenance-mode-issue-in-gitlab-139-to-144). +- For GitLab Enterprise Edition customers, we noticed an issue when [subscription expiration is upcoming, and you create new subgroups and projects](https://gitlab.com/gitlab-org/gitlab/-/issues/322546). If you fall under that category and get 500 errors, you can work around this issue: + + 1. SSH into you GitLab server, and open a Rails console: + + ```shell + sudo gitlab-rails console + ``` + + 1. Disable the following features: + + ```ruby + Feature.disable(:subscribable_subscription_banner) + Feature.disable(:subscribable_license_banner) + ``` + + 1. Restart Puma or Unicorn: + + ```shell + #For installations using Puma + sudo gitlab-ctl restart puma + + #For installations using Unicorn + sudo gitlab-ctl restart unicorn + ``` + ### 13.8.8 GitLab 13.8 includes a background migration to address [an issue with duplicate service records](https://gitlab.com/gitlab-org/gitlab/-/issues/290008). If duplicate services are present, this background migration must complete before a unique index is applied to the services table, which was [introduced in GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52563). Upgrades from GitLab 13.8 and earlier to later versions must include an intermediate upgrade to GitLab 13.8.8 and [must wait until the background migrations complete](#checking-for-background-migrations-before-upgrading) before proceeding. diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md index 98549cc136a..665d2f6783e 100644 --- a/doc/update/plan_your_upgrade.md +++ b/doc/update/plan_your_upgrade.md @@ -35,7 +35,7 @@ to ensure the major components of GitLab are working: sudo gitlab-rake gitlab:check ``` -1. Confirm that encrypted database values [can be decrypted](../administration/raketasks/doctor.md#verify-database-values-can-be-decrypted-using-the-current-secrets): +1. Confirm that encrypted database values [can be decrypted](../administration/raketasks/check.md#verify-database-values-can-be-decrypted-using-the-current-secrets): ```shell sudo gitlab-rake gitlab:doctor:secrets @@ -60,6 +60,16 @@ to ensure the major components of GitLab are working: 1. If using Elasticsearch, verify that searches are successful. +1. If you are using [Reply by Email](../administration/reply_by_email.md) or [Service Desk](../user/project/service_desk.md), + manually install the latest version of `gitlab-mail_room`: + + ```shell + gem install gitlab-mail_room + ``` + + NOTE: This step is necessary to avoid thread deadlocks and to support the latest MailRoom features. See + [this explanation](../development/emails.md#mailroom-gem-updates) for more details. + If in any case something goes wrong, see [how to troubleshoot](#troubleshooting). ## Rollback plan diff --git a/doc/update/removals.md b/doc/update/removals.md new file mode 100644 index 00000000000..94ce815a110 --- /dev/null +++ b/doc/update/removals.md @@ -0,0 +1,390 @@ +--- +stage: none +group: none +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + +# Removals by milestone + +<!-- vale off --> + +<!-- +DO NOT EDIT THIS PAGE DIRECTLY + +This page is automatically generated from the YAML files in `/data/removals` by the rake task +located at `lib/tasks/gitlab/docs/compile_removals.rake`. + +For removal authors (usually Product Managers and Engineering Managers): + +- To add a removal, use the example.yml file in `/data/removals/templates` as a template. +- For more information about authoring removals, check the the removal item guidance: + https://about.gitlab.com/handbook/marketing/blog/release-posts/#creating-a-removal-entry + +For removal reviewers (Technical Writers only): + +- To update the removal doc, run: `bin/rake gitlab:docs:compile_removals` +- To verify the removals doc is up to date, run: `bin/rake gitlab:docs:check_removals` +- For more information about updating the removal doc, see the removal doc update guidance: + https://about.gitlab.com/handbook/marketing/blog/release-posts/#update-the-removals-doc +--> + +## 14.0 + +### Breaking changes to Terraform CI template + +GitLab 14.0 renews the Terraform CI template to the latest version. The new template is set up for the GitLab Managed Terraform state, with a dependency on the GitLab `terraform-images` image, to provide a good user experience around GitLab's Infrastructure-as-Code features. + +The current stable and latest templates are not compatible, and the current latest template becomes the stable template beginning with GitLab 14.0, your Terraform pipeline might encounter an unexpected failure if you run a custom `init` job. + +### Code Quality RuboCop support changed + +By default, the Code Quality feature has not provided support for Ruby 2.6+ if you're using the Code Quality template. To better support the latest versions of Ruby, the default RuboCop version is updated to add support for Ruby 2.4 through 3.0. As a result, support for Ruby 2.1, 2.2, and 2.3 is removed. You can re-enable support for older versions by [customizing your configuration](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html#rubocop-errors). + +Relevant Issue: [Default `codeclimate-rubocop` engine does not support Ruby 2.6+](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/28) + +### Container Scanning Engine Clair + +Clair, the default container scanning engine, was deprecated in GitLab 13.9 and is removed from GitLab 14.0 and replaced by Trivy. We advise customers who are customizing variables for their container scanning job to [follow these instructions](https://docs.gitlab.com/ee/user/application_security/container_scanning/#change-scanners) to ensure that their container scanning jobs continue to work. + +### DAST environment variable renaming and removal + +GitLab 13.8 renamed multiple environment variables to support their broader usage in different workflows. In GitLab 14.0, the old variables have been permanently removed and will no longer work. Any configurations using these variables must be updated to the new variable names. Any scans using these variables in GitLab 14.0 and later will fail to be configured correctly. These variables are: + +- `DAST_AUTH_EXCLUDE_URLS` becomes `DAST_EXCLUDE_URLS`. +- `AUTH_EXCLUDE_URLS` becomes `DAST_EXCLUDE_URLS`. +- `AUTH_USERNAME` becomes `DAST_USERNAME`. +- `AUTH_PASSWORD` becomes `DAST_PASSWORD`. +- `AUTH_USERNAME_FIELD` becomes `DAST_USERNAME_FIELD`. +- `AUTH_PASSWORD_FIELD` becomes `DAST_PASSWORD_FIELD`. +- `DAST_ZAP_USE_AJAX_SPIDER` will now be `DAST_USE_AJAX_SPIDER`. +- `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` will be removed, since the feature is being removed. + +### Default Browser Performance testing job renamed in GitLab 14.0 + +Browser Performance Testing has run in a job named `performance` by default. With the introduction of [Load Performance Testing](https://docs.gitlab.com/ee/user/project/merge_requests/load_performance_testing.html) in GitLab 13.2, this naming could be confusing. To make it clear which job is running [Browser Performance Testing](https://docs.gitlab.com/ee/user/project/merge_requests/browser_performance_testing.html), the default job name is changed from `performance` to `browser_performance` in the template in GitLab 14.0. + +Relevant Issue: [Rename default Browser Performance Testing job](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) + +### Default DAST spider begins crawling at target URL + +In GitLab 14.0, DAST has removed the current method of resetting the scan to the hostname when starting to spider. Prior to GitLab 14.0, the spider would not begin at the specified target path for the URL but would instead reset the URL to begin crawling at the host root. GitLab 14.0 changes the default for the new variable `DAST_SPIDER_START_AT_HOST` to `false` to better support users' intention of beginning spidering and scanning at the specified target URL, rather than the host root URL. This change has an added benefit: scans can take less time, if the specified path does not contain links to the entire site. This enables easier scanning of smaller sections of an application, rather than crawling the entire app during every scan. + +### Default branch name for new repositories now `main` + +Every Git repository has an initial branch, which is named `master` by default. It's the first branch to be created automatically when you create a new repository. Future [Git versions](https://lore.kernel.org/git/pull.656.v4.git.1593009996.gitgitgadget@gmail.com/) will change the default branch name in Git from `master` to `main`. In coordination with the Git project and the broader community, [GitLab has changed the default branch name](https://gitlab.com/gitlab-org/gitlab/-/issues/223789) for new projects on both our SaaS (GitLab.com) and self-managed offerings starting with GitLab 14.0. This will not affect existing projects. + +GitLab has already introduced changes that allow you to change the default branch name both at the [instance level](https://docs.gitlab.com/ee/user/project/repository/branches/default.html#instance-level-custom-initial-branch-name) (for self-managed users) and at the [group level](https://docs.gitlab.com/ee/user/group/#use-a-custom-name-for-the-initial-branch) (for both SaaS and self-managed users). We encourage you to make use of these features to set default branch names on new projects. + +For more information, check out our [blog post](https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/). + +### Deprecated GraphQL fields have been removed + +In accordance with our [GraphQL deprecation and removal process](https://docs.gitlab.com/ee/api/graphql/#deprecation-process), the following fields that were deprecated prior to 13.7 are [fully removed in 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/267966): + +- `Mutations::Todos::MarkAllDone`, `Mutations::Todos::RestoreMany` - `:updated_ids` +- `Mutations::DastScannerProfiles::Create`, `Types::DastScannerProfileType` - `:global_id` +- `Types::SnippetType` - `:blob` +- `EE::Types::GroupType`, `EE::Types::QueryType` - `:vulnerabilities_count_by_day_and_severity` +- `DeprecatedMutations (concern**)` - `AddAwardEmoji`, `RemoveAwardEmoji`, `ToggleAwardEmoji` +- `EE::Types::DeprecatedMutations (concern***)` - `Mutations::Pipelines::RunDastScan`, `Mutations::Vulnerabilities::Dismiss`, `Mutations::Vulnerabilities::RevertToDetected` + +### Deprecations for Dependency Scanning + +As mentioned in [13.9](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#deprecations-for-dependency-scanning) and [this blog post](https://about.gitlab.com/blog/2021/02/08/composition-analysis-14-deprecations-and-removals/) several removals for Dependency Scanning take effect. + +Previously, to exclude a DS analyzer, you needed to remove it from the default list of analyzers, and use that to set the `DS_DEFAULT_ANALYZERS` variable in your project’s CI template. We determined it should be easier to avoid running a particular analyzer without losing the benefit of newly added analyzers. As a result, we ask you to migrate from `DS_DEFAULT_ANALYZERS` to `DS_EXCLUDED_ANALYZERS` when it is available. Read about it in [issue #287691](https://gitlab.com/gitlab-org/gitlab/-/issues/287691). + +Previously, to prevent the Gemnasium analyzers to fetch the advisory database at runtime, you needed to set the `GEMNASIUM_DB_UPDATE` variable. However, this is not documented properly, and its naming is inconsistent with the equivalent `BUNDLER_AUDIT_UPDATE_DISABLED` variable. As a result, we ask you to migrate from `GEMNASIUM_DB_UPDATE` to `GEMNASIUM_UPDATE_DISABLED` when it is available. Read about it in [issue #215483](https://gitlab.com/gitlab-org/gitlab/-/issues/215483). + +### External Pipeline Validation Service Code Changes + +For self-managed instances using the experimental [external pipeline validation service](https://docs.gitlab.com/ee/administration/external_pipeline_validation.html), the range of error codes GitLab accepts will be reduced. Currently, pipelines are invalidated when the validation service returns a response code from `400` to `499`. In GitLab 14.0 and later, pipelines will be invalidated for the `406: Not Accepted` response code only. + +### Geo Foreign Data Wrapper settings removed + +As [announced in GitLab 13.3](https://about.gitlab.com/releases/2020/08/22/gitlab-13-3-released/#geo-foreign-data-wrapper-settings-deprecated), the following configuration settings in `/etc/gitlab/gitlab.rb` have been removed in 14.0: + +- `geo_secondary['db_fdw']` +- `geo_postgresql['fdw_external_user']` +- `geo_postgresql['fdw_external_password']` +- `gitlab-_rails['geo_migrated_local_files_clean_up_worker_cron']` + +### GitLab OAuth implicit grant deprecation + +GitLab is deprecating the [OAuth 2 implicit grant flow](https://docs.gitlab.com/ee/api/oauth2.html#implicit-grant-flow) as it has been removed for [OAuth 2.1](https://oauth.net/2.1/). + +Beginning in 14.0, new applications can't be created with the OAuth 2 implicit grant flow. Existing OAuth implicit grant flows are no longer supported in 14.4. Migrate your existing applications to other supported [OAuth2 flows](https://docs.gitlab.com/ee/api/oauth2.html#supported-oauth2-flows) before release 14.4. + +### GitLab Runner helper image in GitLab.com Container Registry + +In 14.0, we are now pulling the GitLab Runner [helper image](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#helper-image) from the GitLab Container Registry instead of Docker Hub. Refer to [issue #27218](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27218) for details. + +### GitLab Runner installation to ignore the `skel` directory + +In GitLab Runner 14.0, the installation process will ignore the `skel` directory by default when creating the user home directory. Refer to [issue #4845](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4845) for details. + +### Gitaly Cluster SQL primary elector has been removed + +Now that Praefect supports a [primary election strategy](https://docs.gitlab.com/ee/administration/gitaly/praefect.html#repository-specific-primary-nodes) for each repository, we have removed the `sql` election strategy. +The `per_repository` election strategy is the new default, which is automatically used if no election strategy was specified. + +If you had configured the `sql` election strategy, you must follow the [migration instructions](https://docs.gitlab.com/ee/administration/gitaly/praefect.html#migrate-to-repository-specific-primary-gitaly-nodes) before upgrading to 14.0. + +### Helm v2 support + +Helm v2 was [officially deprecated](https://helm.sh/blog/helm-v2-deprecation-timeline/) in November of 2020, with the `stable` repository being [de-listed from the Helm Hub](https://about.gitlab.com/blog/2020/11/09/ensure-auto-devops-work-after-helm-stable-repo/) shortly thereafter. With the release of GitLab 14.0, which will include the 5.0 release of the [GitLab Helm chart](https://docs.gitlab.com/charts/), Helm v2 will no longer be supported. + +Users of the chart should [upgrade to Helm v3](https://helm.sh/docs/topics/v2_v3_migration/) to deploy GitLab 14.0 and later. + +### Legacy feature flags removed + +Legacy feature flags became read-only in GitLab 13.4. GitLab 14.0 removes support for legacy feature flags, so you must migrate them to the [new version](https://docs.gitlab.com/ee/operations/feature_flags.html). You can do this by first taking a note (screenshot) of the legacy flag, then deleting the flag through the API or UI (you don't need to alter the code), and finally create a new Feature Flag with the same name as the legacy flag you deleted. Also, make sure the strategies and environments match the deleted flag. We created a [video tutorial](https://www.youtube.com/watch?v=CAJY2IGep7Y) to help with this migration. + +### Legacy storage removed + +As [announced in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/#planned-removal-of-legacy-storage-in-14.0), [legacy storage](https://docs.gitlab.com/ee/administration/repository_storage_types.html#legacy-storage) has been removed in GitLab 14.0. + +### Limit projects returned in `GET /groups/:id/` + +To improve performance, we are limiting the number of projects returned from the `GET /groups/:id/` API call to 100. A complete list of projects can still be retrieved with the `GET /groups/:id/projects` API call. + +### Make `pwsh` the default shell for newly-registered Windows Runners + +In GitLab Runner 13.2, PowerShell Core support was added to the Shell executor. In 14.0, PowerShell Core, `pwsh` is now the default shell for newly-registered Windows runners. Windows `CMD` will still be available as a shell option for Windows runners. Refer to [issue #26419](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26419) for details. + +### Migrate from `SAST_DEFAULT_ANALYZERS` to `SAST_EXCLUDED_ANALYZERS` + +Until GitLab 13.9, if you wanted to avoid running one particular GitLab SAST analyzer, you needed to remove it from the [long string of analyzers in the `SAST.gitlab-ci.yml` file](https://gitlab.com/gitlab-org/gitlab/-/blob/390afc431e7ce1ac253b35beb39f19e49c746bff/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml#L12) and use that to set the [`SAST_DEFAULT_ANALYZERS`](https://docs.gitlab.com/ee/user/application_security/sast/#docker-images) variable in your project's CI file. If you did this, it would exclude you from future new analyzers because this string hard codes the list of analyzers to execute. We avoid this problem by inverting this variable's logic to exclude, rather than choose default analyzers. +Beginning with 13.9, [we migrated](https://gitlab.com/gitlab-org/gitlab/-/blob/14fed7a33bfdbd4663d8928e46002a5ef3e3282c/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml#L13) to `SAST_EXCLUDED_ANALYZERS` in our `SAST.gitlab-ci.yml` file. We encourage anyone who uses a [customized SAST configuration](https://docs.gitlab.com/ee/user/application_security/sast/#customizing-the-sast-settings) in their project CI file to migrate to this new variable. If you have not overridden `SAST_DEFAULT_ANALYZERS`, no action is needed. The CI/CD variable `SAST_DEFAULT_ANALYZERS` has been removed in GitLab 14.0, which released on June 22, 2021. + +### New Terraform template version + +As we continuously [develop GitLab's Terraform integrations](https://gitlab.com/gitlab-org/gitlab/-/issues/325312), to minimize customer disruption, we maintain two GitLab CI/CD templates for Terraform: + +- The ["latest version" template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml), which is updated frequently between minor releases of GitLab (such as 13.10, 13.11, etc). +- The ["major version" template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml), which is updated only at major releases (such as 13.0, 14.0, etc). + +At every major release of GitLab, the "latest version" template becomes the "major version" template, inheriting the "latest template" setup. +As we have added many new features to the Terraform integration, the new setup for the "major version" template can be considered a breaking change. + +The latest template supports the [Terraform Merge Request widget](https://docs.gitlab.com/ee/user/infrastructure/mr_integration.html) and +doesn't need additional setup to work with the [GitLab managed Terraform state](https://docs.gitlab.com/ee/user/infrastructure/terraform_state.html). + +To check the new changes, see the [new "major version" template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml). + +### OpenSUSE Leap 15.1 + +Support for [OpenSUSE Leap 15.1 is being deprecated](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5135). Support for 15.1 will be dropped in 14.0. We are now providing support for openSUSE Leap 15.2 packages. + +### PostgreSQL 11 support + +PostgreSQL 12 will be the minimum required version in GitLab 14.0. It offers [significant improvements](https://www.postgresql.org/about/news/postgresql-12-released-1976/) to indexing, partitioning, and general performance benefits. + +Starting in GitLab 13.7, all new installations default to version 12. From GitLab 13.8, single-node instances are automatically upgraded as well. If you aren't ready to upgrade, you can [opt out of automatic upgrades](https://docs.gitlab.com/omnibus/settings/database.html#opt-out-of-automatic-postgresql-upgrades). + +### Removal of deprecated `trace` parameter from `jobs` API endpoint + +GitLab Runner was updated in GitLab 13.4 to internally stop passing the `trace` parameter to the `/api/jobs/:id` endpoint. GitLab 14.0 deprecates the `trace` parameter entirely for all other requests of this endpoint. Make sure your [GitLab Runner version matches your GitLab version](https://docs.gitlab.com/runner/#gitlab-runner-versions) to ensure consistent behavior. + +### Removal of legacy fields from DAST report + +As a part of the migration to a common report format for all of the Secure scanners in GitLab, DAST is making changes to the DAST JSON report. Certain legacy fields were deprecated in 13.8 and have been completely removed in 14.0. These fields are `@generated`, `@version`, `site`, and `spider`. This should not affect any normal DAST operation, but does affect users who consume the JSON report in an automated way and use these fields. Anyone affected by these changes, and needs these fields for business reasons, is encouraged to open a new GitLab issue and explain the need. + +For more information, see [the removal issue](https://gitlab.com/gitlab-org/gitlab/-/issues/33915). + +### Removal of release description in the Tags API + +GitLab 14.0 removes support for the release description in the Tags API. You can no longer add a release description when [creating a new tag](https://docs.gitlab.com/ee/api/tags.html#create-a-new-tag). You also can no longer [create](https://docs.gitlab.com/ee/api/tags.html#create-a-new-release) or [update](https://docs.gitlab.com/ee/api/tags.html#update-a-release) a release through the Tags API. Please migrate to use the [Releases API](https://docs.gitlab.com/ee/api/releases/#create-a-release) instead. + +### Removals for License Compliance + +In 13.0, we deprecated the License-Management CI template and renamed it License-Scanning. We have been providing backward compatibility by warning users of the old template to switch. Now in 14.0, we are completely removing the License-Management CI template. Read about it in [issue #216261](https://gitlab.com/gitlab-org/gitlab/-/issues/216261) or [this blog post](https://about.gitlab.com/blog/2021/02/08/composition-analysis-14-deprecations-and-removals/). + +### Remove DAST default template stages + +In GitLab 14.0, we've removed the stages defined in the current `DAST.gitlab-ci.yml` template to avoid the situation where the template overrides manual changes made by DAST users. We're making this change in response to customer issues where the stages in the template cause problems when used with customized DAST configurations. Because of this removal, `gitlab-ci.yml` configurations that do not specify a `dast` stage must be updated to include this stage. + +### Remove SAST analyzer `SAST_GOSEC_CONFIG` variable in favor of custom rulesets + +With the release of [SAST Custom Rulesets](https://docs.gitlab.com/ee/user/application_security/sast/#customize-rulesets) in GitLab 13.5 we allow greater flexibility in configuration options for our Go analyzer (GoSec). As a result we no longer plan to support our less flexible [`SAST_GOSEC_CONFIG`](https://docs.gitlab.com/ee/user/application_security/sast/#analyzer-settings) analyzer setting. This variable was deprecated in GitLab 13.10. +GitLab 14.0 removes the old `SAST_GOSEC_CONFIG variable`. If you use or override `SAST_GOSEC_CONFIG` in your CI file, update your SAST CI configuration or pin to an older version of the GoSec analyzer. We strongly encourage [inheriting and overriding our managed CI templates](https://docs.gitlab.com/ee/user/application_security/sast/#overriding-sast-jobs) to future-proof your CI templates. + +### Remove Ubuntu 19.10 (Eoan Ermine) package + +Ubuntu 19.10 (Eoan Ermine) reached end of life on Friday, July 17, 2020. In GitLab Runner 14.0, Ubuntu 19.10 (Eoan Ermine) is no longer available from our package distribution. Refer to [issue #26036](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26036) for details. + +### Remove `/usr/lib/gitlab-runner` symlink from package + +In GitLab Runner 13.3, a symlink was added from `/user/lib/gitlab-runner/gitlab-runner` to `/usr/bin/gitlab-runner`. In 14.0, the symlink has been removed and the runner is now installed in `/usr/bin/gitlab-runner`. Refer to [issue #26651](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26651) for details. + +### Remove `?w=1` URL parameter to ignore whitespace changes + +To create a consistent experience for users based on their preferences, support for toggling whitespace changes via URL parameter has been removed in GitLab 14.0. + +### Remove `FF_RESET_HELPER_IMAGE_ENTRYPOINT` feature flag + +In 14.0, we have deactivated the `FF_RESET_HELPER_IMAGE_ENTRYPOINT` feature flag. Refer to issue [#26679](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26679) for details. + +### Remove `FF_SHELL_EXECUTOR_USE_LEGACY_PROCESS_KILL` feature flag + +In [GitLab Runner 13.1](https://docs.gitlab.com/runner/executors/shell.html#gitlab-131-and-later), [issue #3376](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3376), we introduced `sigterm` and then `sigkill` to a process in the Shell executor. We also introduced a new feature flag, `FF_SHELL_EXECUTOR_USE_LEGACY_PROCESS_KILL`, so you can use the previous process termination sequence. In GitLab Runner 14.0, [issue #6413](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/6413), the feature flag has been removed. + +### Remove `FF_USE_GO_CLOUD_WITH_CACHE_ARCHIVER` feature flag + +GitLab Runner 14.0 removes the `FF_USE_GO_CLOUD_WITH_CACHE_ARCHIVER` feature flag. Refer to [issue #27175](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27175) for details. + +### Remove `secret_detection_default_branch` job + +To ensure Secret Detection was scanning both default branches and feature branches, we introduced two separate secret detection CI jobs (`secret_detection_default_branch` and `secret_detection`) in our managed [`Secret-Detection.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) template. These two CI jobs created confusion and complexity in the CI rules logic. This deprecation moves the `rule` logic into the `script` section, which then determines how the `secret_detection` job is run (historic, on a branch, commits, etc). +If you override or maintain custom versions of `SAST.gitlab-ci.yml` or `Secret-Detection.gitlab-ci.yml`, you must update your CI templates. We strongly encourage [inheriting and overriding our managed CI templates](https://docs.gitlab.com/ee/user/application_security/secret_detection/#custom-settings-example) to future-proof your CI templates. GitLab 14.0 no longer supports the old `secret_detection_default_branch` job. + +### Remove disk source configuration for GitLab Pages + +GitLab Pages [API-based configuration](https://docs.gitlab.com/ee/administration/pages/#gitlab-api-based-configuration) has been available since GitLab 13.0. It replaces the unsupported `disk` source configuration removed in GitLab 14.0, which can no longer be chosen. You should stop using `disk` source configuration, and move to `gitlab` for an API-based configuration. To migrate away from the 'disk' source configuration, set `gitlab_pages['domain_config_source'] = "gitlab"` in your `/etc/gitlab/gitlab.rb` file. We recommend you migrate before updating to GitLab 14.0, to identify and troubleshoot any potential problems before upgrading. + +### Remove legacy DAST domain validation + +The legacy method of DAST Domain Validation for CI/CD scans was deprecated in GitLab 13.8, and is removed in GitLab 14.0. This method of domain validation only disallows scans if the `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` environment variable is set to `true` in the `gitlab-ci.yml` file, and a `Gitlab-DAST-Permission` header on the site is not set to `allow`. This two-step method required users to opt in to using the variable before they could opt out from using the header. + +For more information, see the [removal issue](https://gitlab.com/gitlab-org/gitlab/-/issues/293595). + +### Remove off peak time mode configuration for Docker Machine autoscaling + +In GitLab Runner 13.0, [issue #5069](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/5069), we introduced new timing options for the GitLab Docker Machine executor. In GitLab Runner 14.0, we have removed the old configuration option, [off peak time mode](https://docs.gitlab.com/runner/configuration/autoscale.html#off-peak-time-mode-configuration-deprecated). + +### Remove redundant timestamp field from DORA metrics API payload + +The [deployment frequency project-level API](https://docs.gitlab.com/ee/api/dora4_project_analytics.html#list-project-deployment-frequencies) endpoint has been deprecated in favor of the [DORA 4 API](https://docs.gitlab.com/ee/api/dora/metrics.html), which consolidates all the metrics under one API with the specific metric as a required field. As a result, the timestamp field, which doesn't allow adding future extensions and causes performance issues, will be removed. With the old API, an example response would be `{ "2021-03-01": 3, "date": "2021-03-01", "value": 3 }`. The first key/value (`"2021-03-01": 3`) will be removed and replaced by the last two (`"date": "2021-03-01", "value": 3`). + +### Remove success and failure for finished build metric conversion + +In GitLab Runner 13.5, we introduced `failed` and `success` states for a job. To support Prometheus rules, we chose to convert `success/failure` to `finished` for the metric. In 14.0, the conversion has now been removed. Refer to [issue #26900](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/26900) for details. + +### Remove support for Windows Server 1903 image + +In 14.0, we have removed Windows Server 1903. Microsoft ended support for this version on 2020-08-12. Refer to [issue #27551](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27551) for details. + +### Remove support for Windows Server 1909 image + +In 14.0, we have removed Windows Server 1909. Microsoft ended support for this version on 2021-05-11. Refer to [issue #27899](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27899) for details. + +### Removed Global `SAST_ANALYZER_IMAGE_TAG` in SAST CI template + +With the maturity of GitLab Secure scanning tools, we've needed to add more granularity to our release process. Previously, GitLab shared a major version number for [all analyzers and tools](https://docs.gitlab.com/ee/user/application_security/sast/#supported-languages-and-frameworks). This requires all tools to share a major version, and prevents the use of [semantic version numbering](https://semver.org/). In GitLab 14.0, SAST removes the `SAST_ANALYZER_IMAGE_TAG` global variable in our [managed `SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml) CI template, in favor of the analyzer job variable setting the `major.minor` tag in the SAST vendored template. + +Each analyzer job now has a scoped `SAST_ANALYZER_IMAGE_TAG` variable, which will be actively managed by GitLab and set to the `major` tag for the respective analyzer. To pin to a specific version, [change the variable value to the specific version tag](https://docs.gitlab.com/ee/user/application_security/sast/#pinning-to-minor-image-version). +If you override or maintain custom versions of `SAST.gitlab-ci.yml`, update your CI templates to stop referencing the global `SAST_ANALYZER_IMAGE_TAG`, and move it to a scoped analyzer job tag. We strongly encourage [inheriting and overriding our managed CI templates](https://docs.gitlab.com/ee/user/application_security/sast/#overriding-sast-jobs) to future-proof your CI templates. This change allows you to more granularly control future analyzer updates with a pinned `major.minor` version. +This deprecation and removal changes our [previously announced plan](https://about.gitlab.com/releases/2021/02/22/gitlab-13-9-released/#pin-static-analysis-analyzers-and-tools-to-minor-versions) to pin the Static Analysis tools. + +### Ruby version changed in `Ruby.gitlab-ci.yml` + +By default, the `Ruby.gitlab-ci.yml` file has included Ruby 2.5. + +To better support the latest versions of Ruby, the template is changed to use `ruby:latest`, which is currently 3.0. To better understand the changes in Ruby 3.0, please reference the [Ruby-lang.org release announcement](https://www.ruby-lang.org/en/news/2020/12/25/ruby-3-0-0-released/). + +Relevant Issue: [Updates Ruby version 2.5 to 3.0](https://gitlab.com/gitlab-org/gitlab/-/issues/329160) + +### Segments removed from DevOps Adoption API + +The first release of the DevOps Adoption report had a concept of **Segments**. Segments were [quickly removed from the report](https://gitlab.com/groups/gitlab-org/-/epics/5251) because they introduced an additional layer of complexity on top of **Groups** and **Projects**. Subsequent iterations of the DevOps Adoption report focus on comparing adoption across groups rather than segments. GitLab 14.0 removes all references to **Segments** [from the GraphQL API](https://gitlab.com/gitlab-org/gitlab/-/issues/324414) and replaces them with **Enabled groups**. + +### Service Templates removed + +Service Templates are [removed in GitLab 14.0](https://gitlab.com/groups/gitlab-org/-/epics/5672). They were used to apply identical settings to a large number of projects, but they only did so at the time of project creation. + +While they solved part of the problem, _updating_ those values later proved to be a major pain point. [Project Integration Management](https://docs.gitlab.com/ee/user/admin_area/settings/project_integration_management.html) solves this problem by enabling you to create settings at the Group or Instance level, and projects within that namespace inheriting those settings. + +### Sidekiq queue selector options no longer accept the 'experimental' prefix + +GitLab supports a [queue selector](https://docs.gitlab.com/ee/administration/operations/extra_sidekiq_processes.html#queue-selector) to run only a subset of background jobs for a given process. When it was introduced, this option had an 'experimental' prefix (`experimental_queue_selector` in Omnibus, `experimentalQueueSelector` in Helm charts). + +As announced in the [13.6 release post](https://about.gitlab.com/releases/2020/11/22/gitlab-13-6-released/#sidekiq-cluster-queue-selector-configuration-option-has-been-renamed), the 'experimental' prefix is no longer supported. Instead, `queue_selector` for Omnibus and `queueSelector` in Helm charts should be used. + +### Ubuntu 16.04 support + +Ubuntu 16.04 [reached end-of-life in April 2021](https://ubuntu.com/about/release-cycle), and no longer receives maintenance updates. We strongly recommend users to upgrade to a newer release, such as 20.04. + +GitLab 13.12 will be the last release with Ubuntu 16.04 support. + +### Unicorn removed in favor of Puma for GitLab self-managed + +[Support for Unicorn](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6078) has been removed in GitLab 14.0 in favor of Puma. [Puma has a multi-threaded architecture](https://docs.gitlab.com/ee/administration/operations/puma.html) which uses less memory than a multi-process application server like Unicorn. On GitLab.com, we saw a 40% reduction in memory consumption by using Puma. + +### Update Auto Deploy template version + +In GitLab 14.0, we will update the [Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/stages.html#auto-deploy) CI template to the latest version. This includes new features, bug fixes, and performance improvements with a dependency on the v2 [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image). Auto Deploy CI tempalte v1 will is deprecated going forward. + +Since the v1 and v2 versions are not backward-compatible, your project might encounter an unexpected failure if you already have a deployed application. Follow the [upgrade guide](https://docs.gitlab.com/ee/topics/autodevops/upgrading_auto_deploy_dependencies.html#upgrade-guide) to upgrade your environments. You can also start using the latest template today by following the [early adoption guide](https://docs.gitlab.com/ee/topics/autodevops/upgrading_auto_deploy_dependencies.html#early-adopters). + +### Update CI/CD templates to stop using hardcoded `master` + +Our CI/CD templates have been updated to no longer use hard-coded references to a `master` branch. In 14.0, they all use a variable that points to your project's configured default branch instead. If your CI/CD pipeline relies on our built-in templates, verify that this change works with your current configuration. For example, if you have a `master` branch and a different default branch, the updates to the templates may cause changes to your pipeline behavior. For more information, [read the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/324131). + +### WIP merge requests renamed 'draft merge requests' + +The WIP (work in progress) status for merge requests signaled to reviewers that the merge request in question wasn't ready to merge. We've renamed the WIP feature to **Draft**, a more inclusive and self-explanatory term. **Draft** clearly communicates the merge request in question isn't ready for review, and makes no assumptions about the progress being made toward it. **Draft** also reduces the cognitive load for new users, non-English speakers, and anyone unfamiliar with the WIP acronym. + +### Web Application Firewall (WAF) + +The Web Application Firewall (WAF) was deprecated in GitLab 13.6 and is removed from GitLab 14.0. The WAF had limitations inherent in the architectural design that made it difficult to meet the requirements traditionally expected of a WAF. By removing the WAF, GitLab is able to focus on improving other areas in the product where more value can be provided to users. Users who currently rely on the WAF can continue to use the free and open source [ModSecurity](https://github.com/SpiderLabs/ModSecurity) project, which is independent from GitLab. Additional details are available in the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/271276). + +### `CI_PROJECT_CONFIG_PATH` removed in GitLab 14.0 + +GitLab 14.0 removes the `CI_PROJECT_CONFIG_PATH` pre-defined project variable in favor of `CI_CONFIG_PATH`, which is functionally the same. If you are using `CI_PROJECT_CONFIG_PATH` in your pipeline configurations, update them to use `CI_CONFIG_PATH` instead. + +### `CI_PROJECT_CONFIG_PATH` variable has been removed + +The `CI_PROJECT_CONFIG_PATH` [predefined project variable](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html) +has been removed in favor of `CI_CONFIG_PATH`, which is functionally the same. + +If you are using `CI_PROJECT_CONFIG_PATH` in your pipeline configurations, +please update them to use `CI_CONFIG_PATH` instead. + +## 14.1 + +### Remove support for `prometheus.listen_address` and `prometheus.enable` + +The support for `prometheus.listen_address` and `prometheus.enable` has been removed from `gitlab.yml`. Use `prometheus.enabled` and `prometheus.server_address` to set up Prometheus server that GitLab instance connects to. Refer to [our documentation](https://docs.gitlab.com/ee/install/installation.html#prometheus-server-setup) for details. + +This only affects new installations from source where users might use the old configurations. + +### Remove support for older browsers + +In GitLab 14.1, we are cleaning up and [removing old code](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63994) that was specific for browsers that we no longer support. This has no impact on users when one of our [supported web browsers](https://docs.gitlab.com/ee/install/requirements.html#supported-web-browsers) is used. + +Most notably, support for the following browsers has been removed: + +- Apple Safari 13 and older. +- Mozilla Firefox 68. +- Pre-Chromium Microsoft Edge. + +The minimum supported browser versions are: + +- Apple Safari 13.1. +- Mozilla Firefox 78. +- Google Chrome 84. +- Chromium 84. +- Microsoft Edge 84. + +## 14.2 + +### Max job log file size of 100 MB + +GitLab values efficiency for all users in our wider community of contributors, so we're always working hard to make sure the application performs at a high level with a lovable UX. + In GitLab 14.2, we have introduced a [job log file size limit](https://docs.gitlab.com/ee/administration/instance_limits.html#maximum-file-size-for-job-logs), set to 100 megabytes by default. Administrators of self-managed GitLab instances can customize this to any value. All jobs that exceed this limit are dropped and marked as failed, helping prevent performance impacts or over-use of resources. This ensures that everyone using GitLab has the best possible experience. + +## 14.3 + +### Introduced limit of 50 tags for jobs + +GitLab values efficiency and is prioritizing reliability for [GitLab.com in FY22](https://about.gitlab.com/direction/#gitlab-hosted-first). In 14.3, GitLab CI/CD jobs must have less than 50 [tags](https://docs.gitlab.com/ee/ci/yaml/index.html#tags). If a pipeline contains a job with 50 or more tags, you will receive an error and the pipeline will not be created. + +### List project pipelines API endpoint removes `name` support in 14.3 + +In GitLab 14.3, we will remove the ability to filter by `name` in the [list project pipelines API endpoint](https://docs.gitlab.com/ee/api/pipelines.html#list-project-pipelines) to improve performance. If you currently use this parameter with this endpoint, you must switch to `username`. + +### Use of legacy storage setting + +The support for [`gitlab_pages['use_legacy_storage']` setting](https://docs.gitlab.com/ee/administration/pages/index.html#domain-source-configuration-before-140) in Omnibus installations has been removed. + +In 14.0 we removed [`domain_config_source`](https://docs.gitlab.com/ee/administration/pages/index.html#domain-source-configuration-before-140) which had been previously deprecated, and allowed users to specify disk storage. In 14.0 we added `use_legacy_storage` as a **temporary** flag to unblock upgrades, and allow us to debug issues with our users and it was deprecated and communicated for removal in 14.3. diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index ede9e342a2e..df34cd03d71 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -59,7 +59,7 @@ You can use Group DevOps Adoption to: - Identify specific subgroups that are lagging in their adoption of GitLab features, so you can guide them on their DevOps journey. -- Find subgroups that have adopted certain features, and provide guidance to other subgroups on +- Find subgroups that have adopted certain features, and provide guidance to other subgroups on how to use those features. - Verify if you are getting the return on investment that you expected from GitLab. diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 0b264ef22b9..2083cb06f93 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -2,7 +2,6 @@ stage: none group: unassigned info: To determine 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' --- @@ -28,8 +27,6 @@ GitLab pipeline emails also display the custom logo. ## Favicon -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14497) in GitLab 11.0. - By default, the favicon (used by the browser as the tab icon, as well as the CI status icon) uses the GitLab logo, but this can be customized with any icon desired. It must be a 32x32 `.png` or `.ico` image. @@ -39,8 +36,6 @@ of the page to activate it in the GitLab instance. ## System header and footer messages -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55057) from GitLab Premium to GitLab Free 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 appear on all projects and pages of the instance, including the sign in / sign up page. The default color is white text on diff --git a/doc/user/admin_area/credentials_inventory.md b/doc/user/admin_area/credentials_inventory.md index d79508e5b68..f9b5168fb08 100644 --- a/doc/user/admin_area/credentials_inventory.md +++ b/doc/user/admin_area/credentials_inventory.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index f2b899f0be9..b3b2c14adbd 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -2,7 +2,6 @@ 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 sites Admin Area **(PREMIUM SELF)** @@ -50,20 +49,27 @@ download them all at once; so, GitLab places an upper limit on the concurrency o these operations. How long the backfill takes is dependent on the maximum concurrency, but higher -values place more strain on the **primary** site. From [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3107), -the limits are configurable. If your **primary** site has lots of surplus capacity, +values place more strain on the **primary** site. The limits are configurable. +If your **primary** site has lots of surplus capacity, you can increase the values to complete backfill in a shorter time. If it's under heavy load and backfill reduces its availability for normal requests, you can decrease them. -## Using a different URL for synchronization +## Set up the internal URLs + +> Setting up internal URLs in secondary sites was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77179) in GitLab 14.7. + +You can set up a different URL for synchronization between the primary and secondary site. The **primary** site's Internal URL is used by **secondary** sites to contact it (to sync repositories, for example). The name Internal URL distinguishes it from [External URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab), which is used by users. Internal URL does not need to be a private address. -Internal URL defaults to external URL, but you can also customize it: +When [Geo secondary proxying](../../administration/geo/secondary_proxy/index.md) is enabled, +the primary uses the secondary's internal URL to contact it directly. + +The internal URL defaults to external URL. To change it: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. @@ -71,6 +77,9 @@ Internal URL defaults to external URL, but you can also customize it: 1. Edit the internal URL. 1. Select **Save changes**. +When enabled, the Admin Area for Geo shows replication details for each site directly +from the primary site's UI, and through the Geo secondary proxy, if enabled. + WARNING: We recommend using an HTTPS connection while configuring the Geo sites. To avoid breaking communication between **primary** and **secondary** sites when using @@ -85,7 +94,7 @@ to the internal URL instead of the external one. ## Multiple secondary sites behind a load balancer -In GitLab 11.11, **secondary** sites can use identical external URLs if +**Secondary** sites can use identical external URLs if a unique `name` is set for each Geo site. The `gitlab.rb` setting `gitlab_rails['geo_node_name']` must: diff --git a/doc/user/admin_area/img/admin_labels.png b/doc/user/admin_area/img/admin_labels.png Binary files differdeleted file mode 100644 index a9ea059ccf9..00000000000 --- a/doc/user/admin_area/img/admin_labels.png +++ /dev/null diff --git a/doc/user/admin_area/img/admin_labels_v14_7.png b/doc/user/admin_area/img/admin_labels_v14_7.png Binary files differnew file mode 100644 index 00000000000..01a4ea0c2cc --- /dev/null +++ b/doc/user/admin_area/img/admin_labels_v14_7.png diff --git a/doc/user/admin_area/img/license_upload_v13_12.png b/doc/user/admin_area/img/license_upload_v13_12.png Binary files differdeleted file mode 100644 index 81dc162c1f0..00000000000 --- a/doc/user/admin_area/img/license_upload_v13_12.png +++ /dev/null diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index b0f38e8cfb9..ba0802b3b7a 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -110,13 +110,13 @@ You can combine the filter options. For example, to list only public projects wi #### Projects pending deletion **(PREMIUM SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37014) in GitLab 13.3. -> - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.7. +> - [Tab renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/347468) from **Deleted projects** in GitLab 14.6. When delayed project deletion is [enabled for a group](../group/index.md#enable-delayed-project-deletion), projects within that group are not deleted immediately, but only after a delay. To access a list of all projects that are pending deletion: 1. On the top bar, select **Menu > Projects > Explore projects**. -1. Select the **Pending deletion** tab (in GitLab 14.7 and later) or the **Deleted projects** tab (GitLab 14.6 and earlier). +1. Select the **Pending deletion** tab (in GitLab 14.6 and later) or the **Deleted projects** tab (GitLab 14.5 and earlier). Listed for each project is: @@ -202,6 +202,8 @@ The following data is included in the export: - Access level ([Project](../permissions.md#project-members-permissions) and [Group](../permissions.md#group-members-permissions)) - Date of last activity ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345388) in GitLab 14.6). For a list of activities that populate this column, see the [Users API documentation](../../api/users.md#get-user-activities-admin-only). +Only the first 100,000 user accounts are exported. +  #### Users statistics diff --git a/doc/user/admin_area/labels.md b/doc/user/admin_area/labels.md index b5dbf835d70..93114186e75 100644 --- a/doc/user/admin_area/labels.md +++ b/doc/user/admin_area/labels.md @@ -7,13 +7,12 @@ type: reference # Labels administration **(FREE SELF)** -In the Admin Area, you can manage labels for the GitLab instance. For more details, see [Labels](../project/labels.md). +To manage labels for the GitLab instance, select **Labels** (**{labels}**) from the Admin Area sidebar. For more details on how to manage labels, see [Labels](../project/labels.md). -## Default Labels +Labels created in the Admin Area are automatically added to new projects. +Updating or adding labels in the Admin Area does not modify labels in existing projects. -Labels created in the Admin Area become available to each _new_ project. - - + <!-- ## Troubleshooting diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index d984f6f4092..c3f0c94db21 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -2,173 +2,179 @@ 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/#assignments -type: howto --- -# Activating GitLab EE **(PREMIUM SELF)** +# Activate GitLab Enterprise Edition (EE) **(PREMIUM SELF)** -To enable features of GitLab Enterprise Edition (EE), you need to activate your instance. Ensure you are running an enterprise edition. To verify, sign in to GitLab and browse to `/help`. The GitLab edition and version are listed at the top of the **Help** page. +When you install a new GitLab instance without a license, it only has the Free features +enabled. To enable all features of GitLab Enterprise Edition (EE), activate +your instance with an activation code or a license file. When [the license expires](#what-happens-when-your-license-expires), +some functionality is locked. -If you are running GitLab Community Edition (CE), upgrade your installation to GitLab Enterprise Edition (EE). For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). If you have questions or need assistance upgrading from GitLab CE to EE please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). +## Verify your GitLab edition -As of GitLab Enterprise Edition 9.4.0, a newly-installed instance without an -uploaded license only has the Free features active. A trial license activates all Ultimate features, but after [the trial expires](#what-happens-when-your-license-expires), some functionality -is locked. +To activate your instance, make sure you are running GitLab Enterprise Edition (EE). -## Activate GitLab EE with an Activation Code +To verify the edition, sign in to GitLab and select +**Help** (**{question-o}**) > **Help**. The GitLab edition and version are listed +at the top of the page. -As of GitLab Enterprise Edition 14.1, you need an activation code to activate your instance. You can obtain an activation code by [purchasing a license](https://about.gitlab.com/pricing/) or by signing up for a [free trial](https://about.gitlab.com/free-trial/). This activation code is a 24-character alphanumeric string you receive in a confirmation email. You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) to copy the activation code to your clipboard. +If you are running GitLab Community Edition (CE), upgrade your installation to GitLab +EE. For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). +If you have questions or need assistance upgrading from GitLab CE to EE, +[contact GitLab Support](https://about.gitlab.com/support/#contact-support). -To begin the activation process with your activation code: +## Activate GitLab EE with an activation code + +In GitLab Enterprise Edition 14.1 and later, you need an activation code to activate +your instance. To get an activation code, [purchase a license](https://about.gitlab.com/pricing/) +or sign up for a [free trial](https://about.gitlab.com/free-trial/). The activation +code is a 24-character alphanumeric string you receive in a confirmation email. +You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) +to copy the activation code to your clipboard. + +To activate your instance with an activation code: 1. Sign in to your GitLab self-managed instance. -1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription**. -1. Paste the activation code onto the input field. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. +1. Enter the activation code in **Activation code**. 1. Read and accept the terms of service. 1. Select **Activate**. -## Activate GitLab EE with a License File - -If you receive a license file from GitLab (for example a new trial), you can upload it by signing into your GitLab instance as an administrator or adding it during installation. The license is a base64-encoded ASCII text file with a `.gitlab-license` extension. +## Activate GitLab EE with a license file -## Uploading your license +If you receive a license file from GitLab (for example, for a trial), you can +upload it to your instance or add it during installation. The license file is +a base64-encoded ASCII text file with a `.gitlab-license` extension. -The 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 the **Subscription** area. +## Upload your license -Otherwise, to manually go to the **Subscription** area: - -1. Sign in to your GitLab self-managed instance. -1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription**, and select **Upload a license file**. +The first time you sign in to your GitLab instance, a note with a +link to the **Upload license** page should be displayed. - - *If you've received a `.gitlab-license` file:* - 1. Download the license file to your local machine. - 1. Select **Upload `.gitlab-license` file**. - 1. Select **Choose file** and select the license file. - In this example the license file is named `GitLab.gitlab-license`. - 1. Select the **Terms of Service** checkbox. - 1. Select **Upload License**. +Otherwise, to upload your license: -  +1. Sign in to GitLab as an administrator. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings**. +1. In the **License file** area, select **Upload a license**. +1. Upload a license: + - For a file, select **Upload `.gitlab-license` file**, **Choose file**, and + select the license file from your local machine. + - For plain text, select **Enter license key** and paste the contents in + **License key**. +1. Select the **Terms of Service** checkbox. +1. Select **Upload License**. - - *If you've received your license as plain text:* - 1. Select **Enter license key**. - 1. Copy the license and paste it into the **License key** field. - 1. Select the **Terms of Service** checkbox. - 1. Select **Upload License**. +## Add your license during installation -## Add your license at install time +You can import a license file when you install GitLab. -A license can be automatically imported at install time by placing a file named -`Gitlab.gitlab-license` in `/etc/gitlab/` for Omnibus GitLab, or `config/` for source installations. +- **For installations from source** + - Place the `Gitlab.gitlab-license` file in the `config/` directory. + - To specify a custom location and filename for the license, set the + `GITLAB_LICENSE_FILE` environment variable with the path to the file: -You can also specify a custom location and filename for the license: + ```shell + export GITLAB_LICENSE_FILE="/path/to/license/file" + ``` -- Source installations should set the `GITLAB_LICENSE_FILE` environment - variable with the path to a valid GitLab Enterprise Edition license. +- **For Omnibus package** + - Place the `Gitlab.gitlab-license` file in the `/etc/gitlab/` directory. + - To specify a custom location and filename for the license, add this entry to `gitlab.rb`: - ```shell - export GITLAB_LICENSE_FILE="/path/to/license/file" - ``` - -- Omnibus GitLab installations should add this entry to `gitlab.rb`: - - ```ruby - gitlab_rails['initial_license_file'] = "/path/to/license/file" - ``` + ```ruby + gitlab_rails['initial_license_file'] = "/path/to/license/file" + ``` 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. - ---- - -After the license is uploaded, all GitLab Enterprise Edition functionality -is active until the end of the license period. When that period ends, the -instance will [fall back](#what-happens-when-your-license-expires) to Free-only -functionality. - -You can review the license details at any time by going to **Admin Area > Subscription**. - -## Notification before the license expires - -One month before the license expires, a message informing about the expiration -date is displayed to GitLab administrators. Make sure that you update your -license, otherwise you miss all the paid features if your license expires. +These methods only add a license at the time of installation. To renew or upgrade +a license, upload the license in the **Admin Area** in the web user interface. ## What happens when your license expires -When your license expires, GitLab locks down features, like Git pushes -and issue creation. Then, your instance becomes read-only and -an expiration message is displayed to all administrators. +Fifteen days before the license expires, a notification banner with the upcoming expiration +date displays to GitLab administrators. -For GitLab self-managed instances, you have a 14-day grace period +When your license expires, GitLab locks features, like Git pushes +and issue creation. Your instance becomes read-only and +an expiration message displays to all administrators. You have a 14-day grace period before this occurs. -- To resume functionality, upload a new license. -- To fall back to Free features, delete all expired licenses. +To resume functionality, [upload a new license](#upload-your-license). -### Remove a license file +To go back to Free features, [delete all expired licenses](#remove-a-license-file). + +## Remove a license file To remove a license file from a self-managed instance: -1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. 1. Select **Remove license**. -These steps may need to be repeated to completely remove all licenses, including those applied in the past. +Repeat these steps to remove all licenses, including those applied in the past. + +## View license details and history -## License history +To view your license details: -You can upload and view more than one license, but only the latest license in the current date -range is used as the active license. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. + +You can upload and view more than one license, but only the latest license in +the current date range is the active license. When you upload a future-dated license, it doesn't take effect until its applicable date. -You can view all of your active subscriptions in the **Subscription history** table. +You can view all active subscriptions in the **Subscription history** table. NOTE: -In GitLab 13.6 and earlier, a notification banner about an expiring license may continue to be displayed even after a new license has been uploaded. -This happens when the newly uploaded license's start date is in the future and the expiring one is still active. +In GitLab 13.6 and earlier, a banner about an expiring license may continue to display +when you upload a new license. This happens when the start date of the new license +is in the future and the expiring one is still active. The banner disappears after the new license becomes active. ## Troubleshooting -### There is no Subscription tab in the Admin Area +### No Subscription area in the Admin Area -If you originally installed Community Edition rather than Enterprise Edition you must -[upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition) -before uploading your license. +You cannot upload your license because there is no **Subscription** area. +This issue might occur if: -GitLab.com users can't upload and use a self-managed license. If you -want to use paid features on GitLab.com, you can -[purchase a separate subscription](../../subscriptions/gitlab_com/index.md). +- You're running GitLab Community Edition. Before you upload your license, you + must [upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition). +- You're using GitLab.com. You cannot upload a self-managed license to GitLab.com. + To use paid features on GitLab.com, [purchase a separate subscription](../../subscriptions/gitlab_com/index.md). ### Users exceed license limit upon renewal -If you've added new users to your GitLab instance prior to renewal, you may need to -purchase additional seats to cover those users. If this is the case, and a license -without enough users is uploaded, GitLab displays a message prompting you to purchase -additional users. More information on how to determine the required number of users -and how to add additional seats can be found in the -[licensing FAQ](https://about.gitlab.com/pricing/licensing-faq/). +GitLab displays a message prompting you to purchase +additional users. This issue occurs if you upload a license that does not have enough +users to cover the number of users in your instance. + +To fix this issue, purchase additional seats to cover those users. +For more information, read the [licensing FAQ](https://about.gitlab.com/pricing/licensing-faq/). -In GitLab 14.2 and later, for instances that use a license file, you can exceed the number of purchased users and still activate your license. +In GitLab 14.2 and later, for instances that use a license file, the following +rules apply: -- If the users over license are less than or equal to 10% of the users in the subscription, - the license is applied and the overage is paid in the next true-up. -- If the users over license are more than 10% of the users in the subscription, +- If the users over license are less than or equal to 10% of the users in the license + file, the license is applied and you pay the overage in the next renewal. +- If the users over license are more than 10% of the users in the license file, you cannot apply the license without purchasing more users. -For example, if you purchased a license for 100 users, you can have 110 users when you activate -your license. However, if you have 111, you must purchase more users before you can activate. +For example, if you purchase a license for 100 users, you can have 110 users when you activate +your license. However, if you have 111 users, you must purchase more users before you can activate +the license. -### There is a connectivity issue +### Cannot activate instance due to connectivity error -In GitLab 14.1 and later, to activate your subscription, your GitLab instance must be connected to the internet. +In GitLab 14.1 and later, to activate your subscription with an activation code, +your GitLab instance must be connected to the internet. -If you have an offline or airgapped environment, you can [upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. +If you have an offline or airgapped environment, +[upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. -If you have questions or need assistance activating your instance, please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). +If you have questions or need assistance activating your instance, +[contact GitLab Support](https://about.gitlab.com/support/#contact-support). diff --git a/doc/user/admin_area/moderate_users.md b/doc/user/admin_area/moderate_users.md index 3f15bd5b4e6..ee38664fa66 100644 --- a/doc/user/admin_area/moderate_users.md +++ b/doc/user/admin_area/moderate_users.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: howto --- @@ -100,7 +100,7 @@ A blocked user can be unblocked from the Admin Area. To do this: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. -1. Select on the **Blocked** tab. +1. Select the **Blocked** tab. 1. Optional. Select a user. 1. Select the **{settings}** **User administration** dropdown. 1. Select **Unblock**. @@ -111,6 +111,16 @@ The user's state is set to active and they consume a NOTE: Users can also be unblocked using the [GitLab API](../../api/users.md#unblock-user). +The unblock option may be unavailable for LDAP users. To enable the unblock option, +the LDAP identity first needs to be deleted: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Overview > Users**. +1. Select the **Blocked** tab. +1. Select a user. +1. Select the **Identities** tab. +1. Find the LDAP provider and select **Delete**. + ## Activate and deactivate users GitLab administrators can deactivate and activate users. diff --git a/doc/user/admin_area/monitoring/background_migrations.md b/doc/user/admin_area/monitoring/background_migrations.md index 66001a987a4..260a8515a1a 100644 --- a/doc/user/admin_area/monitoring/background_migrations.md +++ b/doc/user/admin_area/monitoring/background_migrations.md @@ -145,6 +145,8 @@ or [manually finish it](#manually-finishing-a-batched-background-migration). ### Manually finishing a batched background migration +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62634) in GitLab 14.1 + If you need to manually finish a batched background migration due to an error, you can run: diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 1d2d7be146c..75905d60c4e 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -6,12 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Health Check **(FREE SELF)** -> - Liveness and readiness probes were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10416) in GitLab 9.1. -> - The `health_check` endpoint was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3888) in GitLab 8.8 and was -> deprecated in GitLab 9.1. -> - [Access token](#access-token-deprecated) has been deprecated in GitLab 9.4 -> in favor of [IP whitelist](#ip-whitelist). - GitLab provides liveness and readiness probes to indicate service health and reachability to required services. These probes report on the status of the database connection, Redis connection, and access to the file system. These @@ -137,28 +131,9 @@ On failure, the endpoint returns a `503` HTTP status code. This check is being exempt from Rack Attack. -## Access token (Deprecated) - -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. You can -find the current accepted token in the user interface: - -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Monitoring > Health Check**. (`admin/health_check`) - - - -The access token can be passed as a URL parameter: - -```plaintext -https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN -``` +## Sidekiq -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. +Learn how to configure the [Sidekiq health checks](../../../administration/sidekiq_health_check.md). <!-- ## Troubleshooting diff --git a/doc/user/admin_area/monitoring/img/health_check_token.png b/doc/user/admin_area/monitoring/img/health_check_token.png Binary files differdeleted file mode 100644 index 8d4cf710176..00000000000 --- a/doc/user/admin_area/monitoring/img/health_check_token.png +++ /dev/null diff --git a/doc/user/admin_area/review_abuse_reports.md b/doc/user/admin_area/review_abuse_reports.md index 6a8b48e7ba7..4c5a241ab18 100644 --- a/doc/user/admin_area/review_abuse_reports.md +++ b/doc/user/admin_area/review_abuse_reports.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 5868f20d0d8..f748f575419 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -36,17 +36,19 @@ can create in their personal namespace: ## Max attachment size -You can change the maximum file size for attachments in comments and replies in GitLab: +The maximum file size for attachments in GitLab comments and replies is 10 MB. +To change the maximum attachment size: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum attachment size (MB)**. -NOTE: If you choose a size larger than the configured value for the web server, -you may receive errors. See the [troubleshooting section](#troubleshooting) for more +you may receive errors. Read the [troubleshooting section](#troubleshooting) for more details. +For GitLab.com repository size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). + ## Max push size You can change the maximum push size for your repository: @@ -64,17 +66,20 @@ Use [Git LFS](../../../topics/git/lfs/index.md) to add large files to a reposito ## Max import size -You can change the maximum file size for imports in GitLab: +> [Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. + +To modify the maximum file size for imports in GitLab: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**, then expand **Account and limit**. 1. Increase or decrease by changing the value in **Maximum import size (MB)**. -NOTE: If you choose a size larger than the configured value for the web server, you may receive errors. See the [troubleshooting section](#troubleshooting) for more details. +For GitLab.com repository size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). + ## Personal access token prefix > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20968) in GitLab 13.7. @@ -118,6 +123,9 @@ For instance, consider the following workflow: 1. Before you exceed available storage, you set up a limit of 10 GB per repository. +NOTE: +For GitLab.com repository size limits, read [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). + ### How it works Only a GitLab administrator can set those limits. Setting the limit to `0` means @@ -150,9 +158,6 @@ wiki, packages, or snippets. The repository size limit applies to both private a For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). -NOTE: -For GitLab.com repository size limits, see [accounts and limit settings](../../gitlab_com/index.md#account-and-limit-settings). - ## Troubleshooting ### 413 Request Entity Too Large @@ -196,11 +201,7 @@ To set a limit on how long these sessions are valid: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.6 [with a flag](../../../administration/feature_flags.md) named `ff_limit_ssh_key_lifetime`. Disabled by default. > - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/346753) in GitLab 14.6. - -FLAG: -On self-managed GitLab, by default this feature is available. To hide the feature, -ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `ff_limit_ssh_key_lifetime`. -On GitLab.com, this feature is not available. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/1007) in GitLab 14.7. [Feature flag ff_limit_ssh_key_lifetime](https://gitlab.com/gitlab-org/gitlab/-/issues/347408) removed. Users can optionally specify a lifetime for [SSH keys](../../../ssh/index.md). diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index c6ebce03b06..e18808ffb41 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -134,44 +134,9 @@ A new pipeline must run before the latest artifacts can expire and be deleted. NOTE: All application settings have a [customizable cache expiry interval](../../../administration/application_settings_cache.md) which can delay the settings affect. -## Shared runners pipeline minutes quota **(PREMIUM SELF)** +## Shared runners CI/CD minutes -> [Moved](https://about.gitlab.com/blog/2021/01/26/new-gitlab-product-subscription-model/) to GitLab Premium in 13.9. - -If you have enabled shared runners for your GitLab instance, you can limit their -usage by setting a maximum number of pipeline minutes that a group can use on -shared runners per month. Setting this to `0` (default value) grants -unlimited pipeline minutes. While build limits are stored as minutes, the -counting is done in seconds. Usage resets on the first day of each month. -On GitLab.com, the quota is calculated based on your -[subscription plan](../../../subscriptions/gitlab_com/index.md#ci-pipeline-minutes). - -To change the pipelines minutes quota: - -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **Continuous Integration and Deployment**. -1. In the **Pipeline minutes quota** box, enter the maximum number of minutes. -1. Click **Save changes** for the changes to take effect. - -While the setting in the Admin Area has a global effect, as an administrator you can -also change each group's pipeline minutes quota to override the global value. - -1. Navigate to the **Admin Area > Overview > Groups** and hit the **Edit** - button for the group you wish to change the pipeline minutes quota. -1. In the **Pipeline Minutes Quota** box, enter the maximum number of minutes. -1. Click **Save changes** for the changes to take effect. - -Once saved, you can see the build quota in the group settings. -The quota can also be viewed in the project settings if shared runners -are enabled. - - - -You can see an overview of the pipeline minutes quota of all projects of -a group in the **Usage Quotas** page available to the group page settings list. - - +As an administrator you can set either a global or namespace-specific limit on the number of [CI/CD minutes](../../../ci/pipelines/cicd_minutes.md) you can use. ## Archive jobs @@ -303,13 +268,12 @@ To set the maximum file size: 1. Enter the maximum file size, in bytes. 1. Click **Save size limits**. -## Runner registration +## Prevent users from registering runners + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22225) in GitLab 14.1. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22225) in GitLab 14.1. -> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to enable it. +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../feature_flags.md) named `runner_registration_control`. On GitLab.com, this feature is not available. GitLab administrators can adjust who is allowed to register runners, by showing and hiding areas of the UI. @@ -318,29 +282,14 @@ By default, all members of a project and group are able to register runners. To change this: 1. On the top bar, select **Menu > Admin**. -1. Go to **Settings > CI/CD**. -1. Expand the **Runner registration** section. -1. Select the desired options. -1. Click **Save changes**. - -When the registration sections are hidden in the UI, members of the project or group that need to register runners must contact the administrators. - -This feature is currently behind a feature flag. -To enable it: - -**In Omnibus installations:** - -1. Enter the Rails console: - - ```shell - sudo gitlab-rails console - ``` - -1. Flip the switch and enable the feature flag: +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Runner registration**. +1. Clear the checkbox if you don't want to display runner registration + information in the UI for group or project members. +1. Select **Save changes**. - ```ruby - Feature.enable(:runner_registration_control) - ``` +WARNING: +When the registration sections are hidden in the UI, members of the project or group that need to register runners must contact the administrators. If you plan to prevent registration, ensure users have access to the runners they need to run jobs. ## Troubleshooting diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 5f007c83e4b..4fd7c59ef24 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -29,39 +29,13 @@ functionality that render cross-project data. That includes: Labels, Milestones, Merge requests). - Global and Group search are disabled. -This is to prevent performing to many requests at once to the external +This is to prevent performing too 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 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 administrator: - -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > General**: -  - -The available required properties are: - -- **Service URL**: The URL to make authorization requests to. When leaving the - 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 - to the user. -- **Client authentication certificate**: The certificate to use to authenticate - with the external authorization service. -- **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. -- **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 @@ -69,6 +43,16 @@ using Omnibus, learn to install a custom CA in the Alternatively, learn where to install custom certificates by using `openssl version -d`. +## Configuration + +The external authorization service can be enabled by an administrator: + +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand **External authorization**. +1. Complete the fields. +1. Select **Save changes**. + ## How it works When GitLab requests access, it sends a JSON POST request to the external diff --git a/doc/user/admin_area/settings/img/admin_project_quota_view.png b/doc/user/admin_area/settings/img/admin_project_quota_view.png Binary files differdeleted file mode 100644 index 8320be860da..00000000000 --- a/doc/user/admin_area/settings/img/admin_project_quota_view.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/external_authorization_service_settings.png b/doc/user/admin_area/settings/img/external_authorization_service_settings.png Binary files differdeleted file mode 100644 index 9b8658fd1a1..00000000000 --- a/doc/user/admin_area/settings/img/external_authorization_service_settings.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/file_template_admin_area_v14_0.png b/doc/user/admin_area/settings/img/file_template_admin_area_v14_0.png Binary files differdeleted file mode 100644 index 33fce8a2b77..00000000000 --- a/doc/user/admin_area/settings/img/file_template_admin_area_v14_0.png +++ /dev/null diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 7945e5d790f..2820f3ae9df 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -64,7 +64,7 @@ The **CI/CD** settings contain: 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. Some - [risks are involved](../../packages/container_registry/index.md#use-with-external-container-registries) + [risks are involved](../../packages/container_registry/reduce_container_registry_storage.md#use-with-external-container-registries) in enabling some of these settings. ### Geo **(PREMIUM SELF)** @@ -91,7 +91,8 @@ The **Integrations** settings contain: 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. +- [Customer experience improvement and third-party offers](third_party_offers.md) - + Control the display of customer experience improvement content and third-party offers. - [Snowplow](../../../development/snowplow/index.md) - Configure the Snowplow integration. - [Google GKE](../../project/clusters/add_gke_clusters.md) - Google GKE integration enables you to provision GKE clusters from GitLab. diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index 71eb7bbbdc9..51695ef7fd2 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -7,7 +7,8 @@ type: reference # Instance template repository **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5986) in GitLab 11.3. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) to behave like group-level templates in GitLab 13.9. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. In hosted systems, enterprises often have a need to share their own templates across teams. This feature allows an administrator to pick a project to be the @@ -21,10 +22,9 @@ To select a project to serve as the custom template repository: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Templates**. -1. Select the project: - -  - +1. Expand **Templates** +1. From the dropdown list, select the project to use as the template repository. +1. Select **Save changes**. 1. Add custom templates to the selected repository. After you add templates, you can use them for the entire instance. diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 8cee63b0ac2..52b20d5b437 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -2,7 +2,6 @@ stage: none group: unassigned info: To determine 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 --- # Sign-in restrictions **(FREE SELF)** @@ -21,8 +20,11 @@ To access sign-in restriction settings: You can restrict the password authentication for web interface and Git over HTTP(S): -- **Web interface**: When this feature is disabled, the **Standard** sign-in tab is removed and an [external authentication provider](../../../administration/auth/index.md) must be used. -- **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) must be used to authenticate. +- **Web interface**: When this feature is disabled, the **Standard** sign-in tab + is removed and an [external authentication provider](../../../administration/auth/index.md) + must be used. +- **Git over HTTP(S)**: When this feature is disabled, a [Personal Access Token](../../profile/personal_access_tokens.md) + or LDAP password must be used to authenticate. In the event of an external authentication provider outage, use the [GitLab Rails console](../../../administration/operations/rails_console.md) to [re-enable the standard web sign-in form](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#re-enable-standard-web-sign-in-form). This configuration can also be changed over the [Application settings REST API](../../../api/settings.md#change-application-settings) while authenticating with an administrator account's personal access token. diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index c9d48b14a6c..04ec9ed652f 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -1,11 +1,11 @@ --- -stage: none -group: unassigned +stage: Manage +group: Workspace info: To determine 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 --- -# Third-party offers **(FREE SELF)** +# Customer experience improvement and third-party offers **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20379) in GitLab 11.1. @@ -13,11 +13,14 @@ Within GitLab, we inform users of available third-party offers they might find v to enhance the development of their projects. An example is the Google Cloud Platform free credit for using [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/). -To toggle the display of third-party offers: +Furthermore, we use content to improve customer experience. An example are the personalization +questions when creating a group. + +To toggle the display of customer experience improvement content and third-party offers: 1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings**, and expand **Third-party offers**. -1. Select **Do not display offers from third parties**. +1. On the left sidebar, select **Settings**, and expand **Customer experience improvement & third-party offers**. +1. Select **Do not display content for customer experience improvement and offers from third parties**. 1. Select **Save changes**. <!-- ## Troubleshooting 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 1087f50b215..82e0d3d27d4 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -188,6 +188,9 @@ To restrict visibility levels for projects, snippets, and selected pages: 1. On the left sidebar, select **Settings > General**. 1. Expand the **Visibility and access controls** section. 1. In the **Restricted visibility levels** section, select the desired visibility levels to restrict. + If you restrict the **Public** level: + - User profiles are only visible to logged in users via the Web interface. + - User attributes are only visible to authenticated users via the GraphQL API. 1. Select **Save changes**. For more details on project visibility, see diff --git a/doc/user/analytics/ci_cd_analytics.md b/doc/user/analytics/ci_cd_analytics.md index f083f886924..1bc0c2b8fb0 100644 --- a/doc/user/analytics/ci_cd_analytics.md +++ b/doc/user/analytics/ci_cd_analytics.md @@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/38318) to CI/CD Analytics in GitLab 12.8. -GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline -ran. To view this information for a project, go to **Analytics > CI/CD Analytics**. +CI/CD Analytics shows the history of your pipeline successes and failures, as well as how long each pipeline +ran. View successful pipelines: @@ -27,6 +27,13 @@ on when the pipeline was created. The total pipeline calculation includes child pipelines and pipelines that failed with invalid YAML. If you are interested in filtering pipelines based on other attributes, consider using the [Pipelines API](../../api/pipelines.md#list-project-pipelines). +## View CI/CD analytics + +To view CI/CD analytics: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > CI/CD Analytics**. + ## DevOps Research and Assessment (DORA) key metrics **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/275991) in GitLab 13.7. diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md index 496e768456f..066b45aeb39 100644 --- a/doc/user/analytics/code_review_analytics.md +++ b/doc/user/analytics/code_review_analytics.md @@ -17,16 +17,10 @@ requests, and: - Take action on individual merge requests. - Reduce overall cycle time. -NOTE: -Initially, no data appears. Data is populated as users comment on open merge requests. - -## Overview - Code Review Analytics is available to users with at least the Reporter [role](../permissions.md), and displays a table of open merge requests that have at least one non-author comment. The review time is measured from the time the first non-author comment was submitted. -To access Code Review Analytics, from your project's menu, go to **Analytics > Code Review**. - -You can filter the list of merge requests by milestone and label. +NOTE: +Initially, no data appears. Data is populated as users comment on open merge requests.  @@ -36,6 +30,14 @@ The table is sorted by: or to be broken down into smaller parts. - Other columns: Display the author, approvers, comment count, and line change (-/+) counts. +## View Code Review Analytics + +To view Code Review Analytics: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Code Review**. +1. Filter merge requests by milestone and label. + ## Use cases This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) diff --git a/doc/user/analytics/img/repository_analytics_v13_0.png b/doc/user/analytics/img/repository_analytics_v13_0.png Binary files differdeleted file mode 100644 index dd943b4f44d..00000000000 --- a/doc/user/analytics/img/repository_analytics_v13_0.png +++ /dev/null diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 6a157dbb5ae..01ee9857060 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -23,7 +23,7 @@ in one place. GitLab provides several analytics features at the group level. Some of these features require you to use a higher tier than GitLab Free. -- [Application Security](../application_security/security_dashboard/#group-security-dashboard) +- [Application Security](../application_security/security_dashboard/index.md) - [Contribution](../group/contribution_analytics/index.md) - [DevOps Adoption](../group/devops_adoption/index.md) - [Insights](../group/insights/index.md) @@ -36,7 +36,7 @@ GitLab provides several analytics features at the group level. Some of these fea You can use GitLab to review analytics at the project level. Some of these features require you to use a higher tier than GitLab Free. -- [Application Security](../application_security/security_dashboard/#project-security-dashboard) +- [Application Security](../application_security/security_dashboard/index.md) - [CI/CD](ci_cd_analytics.md) - [Code Review](code_review_analytics.md) - [Insights](../project/insights/index.md) diff --git a/doc/user/analytics/issue_analytics.md b/doc/user/analytics/issue_analytics.md index af7307eab39..6aa2f594532 100644 --- a/doc/user/analytics/issue_analytics.md +++ b/doc/user/analytics/issue_analytics.md @@ -5,11 +5,11 @@ 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)** +# Issue analytics for projects **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196561) in GitLab 12.9. -Issue Analytics is a bar graph which illustrates the number of issues created each month. +Issue analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months prior. diff --git a/doc/user/analytics/repository_analytics.md b/doc/user/analytics/repository_analytics.md index 936504187b4..5fd4a567b58 100644 --- a/doc/user/analytics/repository_analytics.md +++ b/doc/user/analytics/repository_analytics.md @@ -4,38 +4,36 @@ 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 **(FREE)** +# Repository analytics for projects **(FREE)** -Get high-level overview of the project's Git repository. +Use repository analytics to view information about a project's Git repository: - +- Programming languages used in the repository. +- Code coverage history from last 3 months ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1). +- Commit statistics (last month). +- Commits per day of month. +- Commits per weekday. +- Commits per day hour (UTC). -## Availability +Repository analytics is part of [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss). It's available to anyone who has permission to clone the repository. -Repository Analytics is part of [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss). It's available to anyone who has permission to clone the repository. - -The feature requires: +Repository analytics requires: - An initialized Git repository. - At least one commit in the default branch (`master` by default). -## Overview - -You can find Repository Analytics in the project's sidebar. To access the page, go to **{chart}** **Analytics > Repository**. - NOTE: -Without a Git commit in the default branch, the menu item won't be visible. +Without a Git commit in the default branch, the menu item isn't visible. Commits in a project's [wiki](../project/wiki/index.md#track-wiki-events) are not included in the analysis. -### Charts +## View repository analytics + +To review repository analytics for a project: -The data in the charts are queued. Background workers update the charts 10 minutes after each commit in the default branch. Depending on the size of the GitLab installation, it may take longer for data to refresh due to variations in the size of background job queues. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Repository**. -Available charts: +## How repository analytics chart data is updated -- Programming languages used in the repository -- Code coverage history (last 3 months) ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1) -- Commit statistics (last month) -- Commits per day of month -- Commits per weekday -- Commits per day hour (UTC) +Data in the charts are queued. Background workers update the charts 10 minutes after each commit in the default branch. +Depending on the size of the GitLab installation, it may take longer for data to refresh due to variations in the size of background job queues. diff --git a/doc/user/analytics/value_stream_analytics.md b/doc/user/analytics/value_stream_analytics.md index cb6b2e49f60..6bad374c371 100644 --- a/doc/user/analytics/value_stream_analytics.md +++ b/doc/user/analytics/value_stream_analytics.md @@ -4,31 +4,34 @@ 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 **(FREE)** +# Value stream analytics for projects **(FREE)** -> - Introduced as Cycle Analytics prior to GitLab 12.3 at the project level. +> - 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 12.3 at the group level. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23427) from Cycle Analytics to Value Stream Analytics in GitLab 12.8. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23427) from cycle analytics to value stream analytics in GitLab 12.8. -Value Stream Analytics measures the time spent to go from an +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 +(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. -You can use Value Stream Analytics to determine the velocity of a given +You can use value stream analytics to determine the velocity of a given project. 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 about how to contribute to the development of Value Stream Analytics, see our [contributor documentation](../../development/value_stream_analytics.md). +For information about how to contribute to the development of value stream analytics, see our [contributor documentation](../../development/value_stream_analytics.md). -Project-level Value Stream Analytics is available by using **Project > Analytics > Value Stream**. +To access value stream analytics for a project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Value stream**. NOTE: -[Group-level Value Stream Analytics](../group/value_stream_analytics) is also available. +[Value stream analytics for groups](../group/value_stream_analytics) is also available. ## Default stages -The stages tracked by Value Stream Analytics by default represent the [GitLab flow](../../topics/gitlab_flow.md). You can customize these stages in group-level Value Stream Analytics. +The stages tracked by value stream analytics by default represent the [GitLab flow](../../topics/gitlab_flow.md). You can customize these stages in value stream analytics for groups. - **Issue** (Tracker) - Time to schedule an issue (by milestone or by adding it to an issue board) @@ -43,7 +46,7 @@ The stages tracked by Value Stream Analytics by default represent the [GitLab fl - **Staging** (Continuous Deployment) - Time between merging and deploying to production -## Filter Value Stream Analytics data +## Filter value stream analytics data > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326701) in GitLab 14.3 @@ -60,7 +63,7 @@ To filter results: 1. Select a parameter. 1. Select a value. To find a value in the list, enter the value name. - + ### Date ranges @@ -72,7 +75,7 @@ from the date picker (default: last 30 days). > Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335974) in GitLab 14.4. - + The stage table shows a list of related workflow items for the selected stage. This can include: @@ -108,18 +111,18 @@ The **Time** metrics near the top of the page are measured as follows: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) in GitLab 11.3. -Value Stream Analytics exposes two deployment related metrics near the top of the page: +Value stream analytics exposes two deployment related metrics near the top of the page: - **Deploys:** The number of successful deployments in the date range. - **Deployment Frequency:** The average number of successful deployments. The deployment metrics calculation uses the same method as the -[group-level Value Stream Analytics](../group/value_stream_analytics/index.md#how-metrics-are-measured). +[value stream analytics for groups](../group/value_stream_analytics/index.md#how-metrics-are-measured). Both of them are based on the [DORA API](../../api/dora/metrics.md#devops-research-and-assessment-dora-key-metrics-api). ## How the stages are measured -Value Stream Analytics uses start events and end events to measure the time that an issue or merge request spends in each stage. +Value stream analytics uses start events and end events to measure the time that an issue or merge request spends in each stage. For example, a stage might start when one label is added to an issue and end when another label is added. Items aren't included in the stage time calculation if they have not reached the end event. @@ -143,7 +146,7 @@ How this works: 1. For the remaining pairs, review information needed for stages, including issue creation date and merge request merge time. -In short, the Value Stream Analytics dashboard tracks data related to [GitLab flow](../../topics/gitlab_flow.md). It does not include 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 that do not include labels present in the issue board. @@ -152,7 +155,7 @@ In short, the Value Stream Analytics dashboard tracks data related to [GitLab fl ## How the production environment is identified -Value Stream Analytics identifies production environments based on the +Value stream analytics identifies production environments based on the [deployment tier of environments](../../ci/environments/index.md#deployment-tier-of-environments). ## Example workflow @@ -197,12 +200,12 @@ More information: the cycle. The time is included in the **Review** process, as every merge request should be tested. - The previous example illustrates only one cycle of the multiple stages. Value - Stream Analytics, on its dashboard, shows the calculated median elapsed time + stream analytics, on its dashboard, shows the calculated median elapsed time for these issues. ## Permissions -The permissions for the project-level Value Stream Analytics dashboard include: +The permissions for the value stream analytics for projects dashboard include: | Project type | Permissions | |--------------|---------------------------------------| @@ -214,8 +217,8 @@ You can [read more about permissions](../../user/permissions.md) in general. ## More resources -Learn more about Value Stream Analytics with the following resources: +Learn more about value stream analytics with 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/). +- [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/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index a0f14ea59a1..be6b06a0797 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -12,10 +12,6 @@ parameters to unexpected values in an effort to cause unexpected behavior and er backend. This helps you discover bugs and potential security issues that other QA processes may miss. -INFO: -Try fuzz testing in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-api-fuzzing-docs). - We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), you can run fuzz tests as part your CI/CD workflow. @@ -572,6 +568,7 @@ profile increases as the number of tests increases. |[`FUZZAPI_PROFILE`](#api-fuzzing-profiles) | Configuration profile to use during testing. Defaults to `Quick-10`. | |[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI Specification file or URL. | +|[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. | @@ -1293,6 +1290,41 @@ The API Fuzzing template supports launching a docker container containing an API TODO --> +### Use OpenAPI with an invalid schema + +There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. + +#### Edit a non-compliant OpenAPI file + +To detect and correct elements that don't comply with the OpenAPI specifications, we recommend using an editor. An editor commonly provides document validation, and suggestions to create a schema-compliant OpenAPI document. Suggested editors include: + +| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x | +| -- | -- | -- | -- | +| [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON | +| [Stoplight Studio](https://stoplight.io/studio/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | + +If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using. + +#### Enable OpenAPI relaxed validation + +Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema. + +API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION` to any value, for example: + +```yaml + stages: + - fuzz + + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_OPENAPI_RELAXED_VALIDATION: On +``` + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index c3a2c179590..5f2dd626526 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -41,6 +41,8 @@ in your existing `.gitlab-ci.yml` file. To enable cluster image scanning in your pipeline, you need the following: +- Cluster Image Scanning runs in the `test` stage, which is available by default. If you redefine the stages + in the `.gitlab-ci.yml` file, the `test` stage is required. - [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) @@ -172,10 +174,10 @@ You can [configure](#customize-the-cluster-image-scanning-settings) analyzers by | CI/CD Variable | Default | Description | | ------------------------------ | ------------- | ----------- | | `CIS_KUBECONFIG` | `""` | File used to configure access to the Kubernetes cluster. See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) for more details. | -| `CIS_CONTAINER_NAME` | `""` | Name of the container used in the Kubernetes resource you want to filter vulnerabilities for. For example, `alpine`. | -| `CIS_RESOURCE_NAME` | `""` | Name of the Kubernetes resource you want to filter vulnerabilities for. For example, `nginx`. | -| `CIS_RESOURCE_NAMESPACE` | `""` | Namespace of the Kubernetes resource you want to filter vulnerabilities for. For example, `production`. | -| `CIS_RESOURCE_KIND` | `""` | Kind of the Kubernetes resource you want to filter vulnerabilities for. For example, `deployment`. | +| `CIS_CONTAINER_NAMES` | `""` | A comma-separated list of container names used in the Kubernetes resources you want to filter vulnerabilities for. For example, `alpine,postgres`. | +| `CIS_RESOURCE_NAMES` | `""` | A comma-separated list of Kubernetes resources you want to filter vulnerabilities for. For example, `nginx,redis`. | +| `CIS_RESOURCE_NAMESPACES` | `""` | A comma-separated list of namespaces of the Kubernetes resources you want to filter vulnerabilities for. For example, `production,staging`. | +| `CIS_RESOURCE_KINDS` | `""` | A comma-separated list of the kinds of Kubernetes resources to filter vulnerabilities for. For example, `deployment,pod`. | | `CIS_CLUSTER_IDENTIFIER` | `""` | ID of the Kubernetes cluster integrated with GitLab. This is used to map vulnerabilities to the cluster so they can be filtered in the Vulnerability Report page. | | `CIS_CLUSTER_AGENT_IDENTIFIER` | `""` | ID of the Kubernetes cluster agent integrated with GitLab. This maps vulnerabilities to the agent so they can be filtered in the Vulnerability Report page. | diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index bea9284873c..5a2dd5eb54f 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,10 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in GitLab 10.4. -INFO: -Try out Container Scanning in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-container-scanning-docs). - Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra Container Scanning job in your pipeline that scans for those vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based @@ -52,6 +48,7 @@ information directly in the merge request. To enable container scanning in your pipeline, you need the following: +- Container Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. - [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) 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 @@ -62,6 +59,7 @@ To enable container scanning in your pipeline, you need the following: - If you're using a third-party container registry, you might need to provide authentication credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). For more details on how to use these variables, see [authenticate to a remote registry](#authenticate-to-a-remote-registry). +- GitLab CI/CD pipeline must include the `test` stage, which is available unless overridden with the [`stages`](../../../ci/yaml/index.md#stages) keyword. ## Configuration diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index b35c2ed79cf..89b4cdcc34d 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -7,14 +7,14 @@ type: reference, howto # Coverage-guided fuzz testing **(ULTIMATE)** -Coverage-guided fuzzing sends random inputs to an instrumented version of your application in an -effort to cause unexpected behavior. Such behavior indicates a bug that you should address. +Coverage-guided fuzz testing sends random inputs to an instrumented version of your application in +an effort to cause unexpected behavior. Such behavior indicates a bug that you should address. GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. We recommend that you use fuzz testing in addition to the other security scanners in [GitLab Secure](../index.md) and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), -you can run your coverage-guided fuzz tests as part your CI/CD workflow. +you can run your coverage-guided fuzz testing as part your CI/CD workflow. ## Coverage-guided fuzz testing process @@ -30,30 +30,40 @@ The results of the coverage-guided fuzz testing are available in the CI/CD pipel ## Supported fuzzing engines and languages -GitLab supports these languages through the fuzzing engine listed for each. We currently provide a -Docker image for apps written in Go, but you can test the other languages below by providing a -Docker image with the fuzz engine to run your app. - -| Language | Fuzzing Engine | Example | -|----------|----------------|---------| -| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/c-cpp-fuzzing-example) | -| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | -| Swift | [libFuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | -| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | -| Java | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | -| Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | -| JavaScript | [`jsfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz)| [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | -| Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz)| [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | -| AFL (any language that works on top of AFL) | [AFL](https://lcamtuf.coredump.cx/afl/)| [afl-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/afl-fuzzing-example) | +You can use the following fuzzing engines to test the specified languages. + +| Language | Fuzzing Engine | Example | +|---------------------------------------------|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| +| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/c-cpp-fuzzing-example) | +| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | +| Swift | [libFuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | +| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | +| Java | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | +| Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | +| JavaScript | [`jsfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz) | [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | +| Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz) | [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | +| AFL (any language that works on top of AFL) | [AFL](https://lcamtuf.coredump.cx/afl/) | [afl-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/afl-fuzzing-example) | ## Configuration -To enable fuzzing, you must -[include](../../../ci/yaml/index.md#includetemplate) -the [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) -provided as part of your GitLab installation. +To enable coverage-guided fuzz testing, edit the `.gitlab-ci.yml` file: + +1. Add the `fuzz` stage to the list of stages. + +1. If your application is not written in Go, [provide a Docker image](../../../ci/yaml/index.md#image) using the matching fuzzing + engine. For example: + + ```yaml + image: python:latest + ``` + +1. [Include](../../../ci/yaml/index.md#includetemplate) the + [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) + provided as part of your GitLab installation. -To do so, add the following to your `.gitlab-ci.yml` file: +1. Customize the `my_fuzz_target` job to meet your requirements. + +### Example extract of coverage-guided fuzzing configuration ```yaml stages: @@ -65,96 +75,62 @@ include: my_fuzz_target: extends: .fuzz_base script: - # Build your fuzz target binary in these steps, then run it with gitlab-cov-fuzz> + # Build your fuzz target binary in these steps, then run it with gitlab-cov-fuzz # See our example repos for how you could do this with any of our supported languages - ./gitlab-cov-fuzz run --regression=$REGRESSION -- <your fuzz target> ``` -The included template makes available the [hidden job](../../../ci/jobs/index.md#hide-jobs) -`.fuzz_base`, which you must [extend](../../../ci/yaml/index.md#extends) for each of your fuzz -targets. Each fuzz target **must** have a separate job. For example, the +The `Coverage-Fuzzing` template includes the [hidden job](../../../ci/jobs/index.md#hide-jobs) +`.fuzz_base`, which you must [extend](../../../ci/yaml/index.md#extends) for each of your fuzzing +targets. Each fuzzing target **must** have a separate job. For example, the [go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) -contains one job that extends `.fuzz_base` for its single fuzz target. +contains one job that extends `.fuzz_base` for its single fuzzing target. Note that the hidden job `.fuzz_base` uses several YAML keys that you must not override in your own -job. If you include these keys in your own job, you must copy their original content. These keys -are: +job. If you include these keys in your own job, you must copy their original content: - `before_script` - `artifacts` - `rules` -The `my_fuzz_target` job (the separate job for your fuzz target) does the following: +### Available CI/CD variables + +Use the following variables to configure coverage-guided fuzz testing in your CI/CD pipeline. -- Extends `.fuzz_base`. -- Compiles the fuzz target with [go-fuzz](https://github.com/dvyukov/go-fuzz). -- Runs the target with the `gitlab-cov-fuzz` command, which is available to each job that extends - `.fuzz_base`. -- Runs on a fuzz stage that usually comes after a test stage. +| CI/CD variable | Description | +|---------------------------|---------------------------------------------------------------------------------| +| `COVFUZZ_ADDITIONAL_ARGS` | Arguments passed to `gitlab-cov-fuzz`. Used to customize the behavior of the underlying fuzzing engine. Read the fuzzing engine's documentation for a complete list of arguments. | +| `COVFUZZ_BRANCH` | The branch on which long-running fuzzing jobs are to be run. On all other branches, only fuzzing regression tests are run. Default: Repository's default branch. | +| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. Default: empty. | +| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this value when using an offline environment. Default: `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | -The `gitlab-cov-fuzz` is a command-line tool that runs the instrumented application. It parses and -analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](../terminology/index.md#corpus) -and crash events from previous pipelines automatically. This helps your fuzz targets build on the -progress of previous fuzzing jobs. The parsed crash events and data are written to -`gl-coverage-fuzzing-report.json`. +#### Seed corpus -### Artifacts +Files in the [seed corpus](../terminology/index.md#seed-corpus) must be updated manually. They are +not updated or overwritten by the coverage-guide fuzz testing job. + +## Output Each fuzzing step outputs these artifacts: -- `gl-coverage-fuzzing-report.json`: This file's format may change in future releases. +- `gl-coverage-fuzzing-report.json`: A report containing details of the coverage-guided fuzz testing + and its results. - `artifacts.zip`: This file contains two directories: - - `corpus`: Holds all test cases generated by the current and all previous jobs. - - `crashes`: Holds all crash events the current job encountered as well as those not fixed in + - `corpus`: Contains all test cases generated by the current and all previous jobs. + - `crashes`: Contains all crash events the current job found and those not fixed in previous jobs. -### Types of fuzzing jobs - -There are two types of jobs: - -- Fuzzing: Standard fuzzing session. You can configure a long session through a user defined - timeout. -- Regression: Run the fuzz targets through the accumulated test cases generated by previous fuzzing - sessions plus fixed crashes from previous sessions. This is usually very quick. - -Here's our current suggestion for configuring your fuzz target's timeout: - -- Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (asynchronous) fuzzing - jobs. This is normally the default branch. -- Use regression or short-running fuzzing jobs for other branches or merge requests. - -This suggestion helps find new bugs on the development branch and catch old bugs in merge requests -(like unit tests). - -You can configure this by passing `--regression=false/true` to `gitlab-cov-fuzz` as the [Go example](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example/-/blob/master/.gitlab-ci.yml) -shows. Also note that `gitlab-cov-fuzz` is a wrapper, so you can pass those arguments to configure -any option available in the underlying fuzzing engine. - -### Available CI/CD variables - -| CI/CD variable | Description | -|-----------------------|--------------------------------------------------------------------------------| -| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. This is normally the default branch. | -| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | -| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | - -The files in the [seed corpus](../terminology/index.md#seed-corpus) (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new -files to your Git repository. There's usually no need to frequently update the seed corpus. As part -of the GitLab artifacts system, GitLab saves in a corpus directory the new test cases that every run -generates. In any subsequent runs, GitLab also reuses the generated corpus together with the seed -corpus. +You can download the JSON report file from the CI/CD pipelines page. For more information, see +[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). -### Reports JSON format +### Coverage-guided fuzz testing report > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in GitLab 13.3 as an [Alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). -The `gitlab-cov-fuzz` tool emits a JSON report file. For more information, see the -[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json). - -You can download the JSON report file from the CI pipelines page. For more information, see -[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +For detailed information about the `gl-coverage-fuzzing-report.json` file's format, read the +[schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json). -Here's an example coverage fuzzing report: +Example coverage-guided fuzzing report: ```json-doc { @@ -183,38 +159,30 @@ Here's an example coverage fuzzing report: } ``` -### Additional configuration - -The `gitlab-cov-fuzz` command passes all arguments it receives to the underlying fuzzing engine. You -can therefore use all the options available in that fuzzing engine. For more information on these -options, see the underlying fuzzing engine's documentation. - -### Offline environment +## Duration of coverage-guided fuzz testing -To use coverage fuzzing in an offline environment, follow these steps: +The available durations for coverage-guided fuzz testing are: 10 minutes (default) and 60 minutes. -1. Clone [`gitlab-cov-fuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz) - to a private repository that your offline GitLab instance can access. +- 10-minute duration: Recommended for the default branch. +- 60-minute duration: Recommended for the development branch and merge requests. The longer duration provides greater coverage. + In the `COVFUZZ_ADDITIONAL_ARGS` variable set the value `--regression=true`. -1. For each fuzzing step, set `COVFUZZ_URL_PREFIX` to `${NEW_URL_GITLAB_COV_FUZ}/-/raw`, where - `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the - first step. +For a complete example, read the [Go coverage-guided fuzzing example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/blob/master/.gitlab-ci.yml). -### Continuous fuzzing (long-running asynchronous fuzzing jobs) +### Continuous coverage-guided fuzz testing -It's also possible to run the fuzzing jobs longer and without blocking your main pipeline. This -configuration uses the GitLab [parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md). -The full example is available in the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing#running-go-fuzz-from-ci). -This example uses Go, but is applicable for any other supported languages. +It's also possible to run the coverage-guided fuzzing jobs longer and without blocking your main +pipeline. This configuration uses the GitLab +[parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md). -The suggested workflow in this scenario is to have long-running, asynchronous fuzzing jobs on a -main/development branch, and short, blocking sync fuzzing jobs on all other branches and MRs. This -is a good way to balance the needs of letting a developer's per-commit pipeline complete quickly, -and also giving the fuzzer a large amount of time to fully explore and test the app. +The suggested workflow in this scenario is to have long-running, asynchronous fuzzing jobs on the +main or development branch, and short synchronous fuzzing jobs on all other branches and MRs. This +balances the needs of completing the per-commit pipeline complete quickly, while also giving the +fuzzer a large amount of time to fully explore and test the app. Long-running fuzzing jobs are +usually necessary for the coverage-guided fuzzer to find deeper bugs in your codebase. -Long-running fuzzing jobs are usually necessary for the coverage guided fuzzer to find deeper bugs -in your latest codebase. The following is an example of what `.gitlab-ci.yml` looks like in this -workflow (for the full example, see the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing)): +The following is an extract of the `.gitlab-ci.yml` file for this +workflow. For the full example, see the [Go fuzzing example's repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing): ```yaml @@ -236,7 +204,7 @@ async_fuzzing: - if: $CI_COMMIT_BRANCH == 'continuous_fuzzing' && $CI_PIPELINE_SOURCE != 'merge_request_event' ``` -This essentially creates two steps: +This creates two jobs: 1. `sync_fuzzing`: Runs all your fuzz targets for a short period of time in a blocking configuration. This finds simple bugs and allows you to be confident that your MRs aren't @@ -246,6 +214,17 @@ This essentially creates two steps: The `covfuzz-ci.yml` is the same as that in the [original synchronous example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example#running-go-fuzz-from-ci). +## Offline environment + +To use coverage fuzzing in an offline environment: + +1. Clone [`gitlab-cov-fuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz) + to a private repository that your offline GitLab instance can access. + +1. For each fuzzing step, set `COVFUZZ_URL_PREFIX` to `${NEW_URL_GITLAB_COV_FUZ}/-/raw`, where + `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the + first step. + ## Interacting with the vulnerabilities After a vulnerability is found, you can [address it](../vulnerabilities/index.md). diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 4de7a566769..aeaa93f4a85 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -16,10 +16,6 @@ Dynamic Application Security Testing (DAST) examines applications for vulnerabilities like these in deployed environments. DAST uses the open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) for analysis. -INFO: -Want to try out security scanning? -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dast-docs). - After DAST creates its report, GitLab evaluates it for discovered vulnerabilities between the source and target branches. Relevant findings are noted in the merge request. @@ -57,6 +53,7 @@ results. On failure, the analyzer outputs an - [GitLab Runner](../../../ci/runners/index.md) available, with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). - Target application deployed. For more details, read [Deployment options](#deployment-options). +- DAST runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. ### Deployment options @@ -638,7 +635,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_OPENAPI` must be specified if this is omitted. | | `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. Example: `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | +| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `logger.httpsender.name=org.parosproxy.paros.network.HttpSender;logger.httpsender.level=debug;logger.sitemap.name=org.parosproxy.paros.model.SiteMap;logger.sitemap.level=debug;` | | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | 1. Available to an on-demand DAST scan. @@ -969,6 +966,8 @@ To view running completed and scheduled on-demand DAST scans for a project, go t failed, or was canceled. - To view scheduled scans, select **Scheduled**. It shows on-demand scans that have a schedule set up. Those are _not_ included in the **All** tab. +- To view saved on-demand scan profiles, select **Scan library**. + Those are _not_ included in the **All** tab. #### Cancel an on-demand scan @@ -1036,10 +1035,8 @@ The on-demand DAST scan runs and the project's dashboard shows the results. To run a saved on-demand scan: 1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. In the **DAST Profiles** row, select **Manage**. -1. Select the **Saved Scans** tab. +1. On the left sidebar, select **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the scan's row, select **Run scan**. If the branch saved in the scan no longer exists, you must first @@ -1075,27 +1072,23 @@ To schedule a scan: To list saved on-demand scans: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. #### View details of an on-demand scan To view details of an on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. #### Edit an on-demand scan To edit an on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. 1. Edit the form. 1. Select **Save scan**. @@ -1104,10 +1097,8 @@ To edit an on-demand scan: To delete an on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. 1. Select **Delete** to confirm the deletion. @@ -1132,6 +1123,9 @@ A site profile contains the following: When an API site type is selected, a [host override](#host-override) is used to ensure the API being scanned is on the same host as the target. This is done to reduce the risk of running an active scan against the wrong API. +When configured, request headers and password fields are encrypted using [`aes-256-gcm`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) before being stored in the database. +This data can only be read and decrypted with a valid secrets file. + #### Site profile validation > - Site profile validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 0db5fb2d868..f1eba505589 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -214,7 +214,7 @@ target API to test: DAST_API_PROFILE: Quick ``` -1. Provide the location of the HAR specification. You can provide the specification as a file +1. Provide the location of the HAR file. You can provide the location as a file path or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `DAST_API_HAR` variable: ```yaml @@ -314,7 +314,7 @@ information about the target API to test: DAST_API_PROFILE: Quick ``` -1. Provide the location of the Postman Collection specification. You can provide the specification as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable: +1. Provide the location of the Postman Collection file. You can provide the location as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable: ```yaml stages: @@ -637,6 +637,7 @@ can be added, removed, and modified by creating a custom configuration. |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | |[`DAST_API_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | +|[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`DAST_API_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract postman variable values. | @@ -1209,6 +1210,41 @@ deploy-test-target: - environment_url.txt ``` +### Use OpenAPI with an invalid schema + +There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `DAST_API_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. + +#### Edit a non-compliant OpenAPI file + +To detect and correct elements that don't comply with the OpenAPI specifications, we recommend using an editor. An editor commonly provides document validation, and suggestions to create a schema-compliant OpenAPI document. Suggested editors include: + +| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x | +| -- | -- | -- | -- | +| [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON | +| [Stoplight Studio](https://stoplight.io/studio/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | + +If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using. + +#### Enable OpenAPI relaxed validation + +Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema. + +API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `DAST_API_OPENAPI_RELAXED_VALIDATION` to any value, for example: + +```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OPENAPI: test-api-specification.json + DAST_API_OPENAPI_RELAXED_VALIDATION: On +``` + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 192d8449297..a8cc33d5545 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -7,10 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning **(ULTIMATE)** -INFO: -Try out Dependency Scanning in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dependency-scanning-docs). - The Dependency Scanning feature can automatically find security vulnerabilities in your software dependencies while you're developing and testing your applications. For example, dependency scanning lets you know if your application uses an external (open source) @@ -67,6 +63,9 @@ vulnerability. ## Requirements +Dependency Scanning runs in the `test` stage, which is available by default. If you redefine the +stages in the `.gitlab-ci.yml` file, the `test` stage is required. + To run dependency scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. @@ -922,6 +921,8 @@ gemnasium-dependency_scanning: ## Warnings +We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. + ### Python projects Extra care needs to be taken when using the [`PIP_EXTRA_INDEX_URL`](https://pipenv.pypa.io/en/latest/cli/#envvar-PIP_EXTRA_INDEX_URL) diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index c17ebc68b4d..4d5c1da3c47 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -14,6 +14,8 @@ Currently, IaC scanning supports configuration files for Terraform, Ansible, AWS ## Requirements +IaC Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. + To run IaC scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. @@ -48,7 +50,7 @@ as shown in the following table: | Capability | In Free | In Ultimate | |:---------------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure IaC Scanners](#configuration) v | **{check-circle}** | **{check-circle}** | +| [Configure IaC Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | | Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 5500f5a10c4..f5c727a1418 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -16,10 +16,6 @@ GitLab can check your application for security vulnerabilities including: Statistics and details on vulnerabilities are included in the merge request. Providing actionable information _before_ changes are merged enables you to be proactive. -INFO: -Want to try out security scanning? -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-application-security-docs). - GitLab also provides high-level statistics of vulnerabilities across projects and groups: - The [Security Dashboard](security_dashboard/index.md) provides a @@ -119,7 +115,9 @@ rules: If you add the security scanning jobs as described in [Security scanning with Auto DevOps](#security-scanning-with-auto-devops) or [Security scanning without Auto DevOps](#security-scanning-without-auto-devops) to your `.gitlab-ci.yml` each added [security scanning tool](#security-scanning-tools) behave as described below. -For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) that rely on this scan data only show results from pipelines on the default branch. One tool might use many analyzers. +For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. +Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) +that rely on this scan data only show results from pipelines on the default branch, only if all jobs are finished, including manual ones. One tool might use many analyzers. Our language and package manager specific jobs attempt to assess which analyzer(s) they should run for your project so that you can do less configuration. @@ -172,7 +170,7 @@ From the merge request security widget, select **Expand** to unfold the widget, A pipeline's security tab lists all findings in the current branch. It includes new findings introduced by this branch and existing vulnerabilities that were already present when the branch was created. These results likely do not match the findings displayed in the Merge Request security widget as those do not include the existing vulnerabilities (with the exception of showing any existing vulnerabilities that are no longer detected in the feature branch). -For more details, see [security tab](security_dashboard/index.md#pipeline-security). +For more details, see [security tab](security_dashboard/index.md#view-vulnerabilities-in-a-pipeline). ## View security scan information in the Security Dashboard @@ -406,9 +404,9 @@ sast: You can interact with the results of the security scanning tools in several locations: - [Scan information in merge requests](#view-security-scan-information-in-merge-requests) -- [Project Security Dashboard](security_dashboard/#project-security-dashboard) -- [Security pipeline tab](security_dashboard/#pipeline-security) -- [Group Security Dashboard](security_dashboard/#group-security-dashboard) +- [Project Security Dashboard](security_dashboard/index.md) +- [Security pipeline tab](security_dashboard/index.md) +- [Group Security Dashboard](security_dashboard/index.md) - [Security Center](security_dashboard/#security-center) - [Vulnerability Report](vulnerability_report/index.md) - [Vulnerability Pages](vulnerabilities/index.md) @@ -441,6 +439,46 @@ When customizing the configuration: version contains the most recent changes, but may have significant changes between minor GitLab versions. - Only override values in the template as needed. All other values are inherited from the template. +### Enforce scan execution + +Security and compliance teams must ensure that security scans: + +- Run on a regular basis for all projects. +- Can't be disabled by developers. + +GitLab provides two methods of accomplishing this, each with advantages and disadvantages. + +- [Compliance framework pipelines](../project/settings/#compliance-pipeline-configuration) + are recommended when: + + - Scan execution enforcement is required for SAST IaC, Container Scanning, Dependency Scanning, + License Compliance, API Fuzzing, or Coverage-guided Fuzzing. + - Scan execution enforcement of SAST or Secret Detection when customization of the default scan + variables is required. + - Scan execution enforcement is required for scanners external to GitLab. + - Enforced execution is required for custom jobs other than security scans. + +- [Scan execution policies](policies/#scan-execution-policies) + are recommended when: + + - Scan execution enforcement is required for DAST. + - Scan execution enforcement is required for SAST or Secret Detection with the default scan + variables. + - Scans are required to run on a regular, scheduled cadence. + +Additional details about the differences between the two solutions are outlined below: + +| | Compliance Framework Pipelines | Scan Execution Policies | +| ------ | ------ | ------ | +| **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, and Secret Detection scans are supported. | +| **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | +| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `gitlab-ci.yml` file. To include the project's `gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. | +| **Schedulable** | Can be scheduled through a scheduled pipeline on the group. | Can be scheduled natively through the policy configuration itself. | +| **Separation of Duties** | Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline. | Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project. | +| **Ability to apply one standard to multiple projects** | The same compliance framework label can be applied to multiple projects inside a group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | + +Feedback is welcome on our vision for [unifying the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312) + ## Troubleshooting ### Secure job failing with exit code 1 @@ -609,3 +647,15 @@ such as changing `variables` or the `stage`, but they cannot be used to define s There [is an issue open to improve extendability](https://gitlab.com/gitlab-org/gitlab/-/issues/218444). Please upvote the issue to help with prioritization, and [contributions are welcomed](https://about.gitlab.com/community/contribute/). + +### Empty Vulnerability Report, Dependency List, License list pages + +If the pipeline has manual steps with a job that has the `allow_failure: false` option, and this job is not finished, +GitLab can't populate listed pages with the data from security reports. +In this case, [the Vulnerability Report](vulnerability_report/index.md), [the Dependency List](dependency_list/index.md), +and [the License list](../compliance/license_compliance/index.md#license-list) pages will be empty. +These security pages can be populated by running the jobs from the manual step of the pipeline. + +There is [an issue open to handle this scenario](https://gitlab.com/gitlab-org/gitlab/-/issues/346843). +Please upvote the issue to help with prioritization, and +[contributions are welcomed](https://about.gitlab.com/community/contribute/). diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png Binary files differdeleted file mode 100644 index d04905eda59..00000000000 --- a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png Binary files differnew file mode 100644 index 00000000000..04768d2e18a --- /dev/null +++ b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index e6dbd96537f..11f2b91177a 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -236,20 +236,32 @@ Project owners can unlink Security Policy projects from development projects. To the steps described in [Security Policy project selection](#security-policy-project-selection), but select the trash can icon in the modal. +## Scan execution policies + +Project owners can use scan execution policies to require that security scans run on a specified +schedule or with the project pipeline. Required scans are injected into the CI pipeline as new jobs +with a long, random job name. In the unlikely event of a job name collision, the security policy job +overwrites any pre-existing job in the pipeline. + +This feature has some overlap with [compliance framework pipelines](../../project/settings/#compliance-pipeline-configuration), +as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). +For details on the similarities and differences between these features, see +[Enforce scan execution](../#enforce-scan-execution). + ### Scan Execution Policy editor NOTE: Only project Owners have the [permissions](../../permissions.md#project-members-permissions) to select Security Policy Project. -Once your policy is complete, save it by selecting **Create merge request** +Once your policy is complete, save it by selecting **Create via merge request** at the bottom of the editor. You are redirected to the merge request on the project's configured security policy project. If one does not link to your project, a security policy project is automatically created. Existing policies can also be removed from the editor interface by selecting **Delete policy** at the bottom of the editor. - + The policy editor currently only supports the YAML mode. The Rule mode is tracked in the [Allow Users to Edit Rule-mode Scan Execution Policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363) epic. @@ -301,10 +313,10 @@ Use this schema to define `clusters` objects in the [`schedule` rule type](#sche | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| -| `containers` | `array` of `string` | | The container name to be scanned (only the first value is currently supported). | -| `resources` | `array` of `string` | | The resource name to be scanned (only the first value is currently supported). | -| `namespaces` | `array` of `string` | | The namespace to be scanned (only the first value is currently supported). | -| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind to be scanned (only the first value is currently supported). | +| `containers` | `array` of `string` | | The container name that is scanned (only the first value is currently supported). | +| `resources` | `array` of `string` | | The resource name that is scanned (only the first value is currently supported). | +| `namespaces` | `array` of `string` | | The namespace that is scanned (only the first value is currently supported). | +| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | ### `scan` action type @@ -389,7 +401,7 @@ scan_execution_policy: enabled: true rules: - type: schedule - cadence: "15 3 * * * + cadence: "15 3 * * *" clusters: production-cluster: containers: diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 8c7e03f69fd..7529bf90ccf 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # SAST Analyzers **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in GitLab 10.3. -> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. +> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. SAST relies on underlying third party tools that are wrapped into what we call "Analyzers". An analyzer is a diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index fd05ecad8f2..de2f9af82c7 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -2,13 +2,11 @@ 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/#assignments -type: reference, howto --- # Static Application Security Testing (SAST) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in GitLab 10.3. -> - All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3. +> All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3. NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) @@ -51,6 +49,8 @@ the analyzer outputs an [exit code](../../../development/integrations/secure.md# ## Requirements +SAST runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. + To run SAST jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. @@ -168,10 +168,9 @@ To configure SAST for a project you can: ### Configure SAST manually -For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/index.md#includetemplate) +To enable SAST you must [include](../../../ci/yaml/index.md#includetemplate) the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) -provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you -can copy and use the job as defined that template. +provided as a part of your GitLab installation. Add the following to your `.gitlab-ci.yml` file: @@ -269,7 +268,7 @@ versions are pulled, there are certain cases where it can be beneficial to pin an analyzer to a specific release. To do so, override the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable in the job template directly. -In the example below, we pin to a specific patch version of the `spotbugs` analyzer and minor version of the `semgrep` analyzer: +In the example below, we pin to a minor version of the `semgrep` analyzer and a specific patch version of the `brakeman` analyzer: ```yaml include: @@ -277,11 +276,11 @@ include: semgrep-sast: variables: - SAST_ANALYZER_IMAGE_TAG: "2.12" + SAST_ANALYZER_IMAGE_TAG: "2.16" -spotbugs-sast: +brakeman-sast: variables: - SAST_ANALYZER_IMAGE_TAG: "2.28.1" + SAST_ANALYZER_IMAGE_TAG: "2.21.1" ``` ### Customize rulesets **(ULTIMATE)** @@ -311,9 +310,9 @@ To disable analyzer rules: 1. Set the `disabled` flag to `true` in the context of a `ruleset` section -1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: +1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: -- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. +- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. - a `value` field, to name the rule to be disabled. @@ -346,7 +345,7 @@ and `sobelow` by matching the `type` and `value` of identifiers: #### Synthesize a custom configuration -To create a custom configuration, you can use passthrough chains. +To create a custom configuration, you can use passthrough chains. A passthrough is a single step in a passthrough chain. The passthrough is evaluated in a sequence to incrementally build a configuration. The configuration is then @@ -360,8 +359,8 @@ parameters: | `description` | Description about the analyzer configuration section. | | `targetdir` | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. | | `validate` | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. | -| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | -| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | +| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | +| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20. There are several types of passthroughs: @@ -374,12 +373,12 @@ There are several types of passthroughs: | `url` | Fetch the analyzer configuration through HTTP. | If multiple passthrough sections are defined in a passthrough chain, their -position in the chain defines the order in which they are evaluated. +position in the chain defines the order in which they are evaluated. -- Passthroughs listed later in the chain sequence have a higher precedence. +- Passthroughs listed later in the chain sequence have a higher precedence. - Passthroughs with a higher precedence overwrite (default) and append data yielded by previous passthroughs. This is useful for cases where you need to - use or modify an existing configuration. + use or modify an existing configuration. Configure a passthrough these parameters: @@ -454,7 +453,7 @@ file `gosec-config.json`: ##### Passthrough chain for semgrep In the below example, we generate a custom configuration under the `/sgrules` -target directory with a total `timeout` of 60 seconds. +target directory with a total `timeout` of 60 seconds. Several passthrouh types generate a configuration for the target analyzer: @@ -463,17 +462,17 @@ Several passthrouh types generate a configuration for the target analyzer: `97f7686` from the `sast-rules` Git repostory. From the `sast-rules` Git repository, only data from the `go` subdirectory is considered. - The `sast-rules` entry has a higher precedence because it appears later in - the configuration. + the configuration. - If there is a filename collision between files in both repositories, files from the `sast` repository overwrite files from the `myrules` repository, as `sast-rules` has higher precedence. - The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The - full path is `/sgrules/insecure.yml`. + full path is `/sgrules/insecure.yml`. - The `url` entry fetches a configuration made available through a URL and - stores it in the `/sgrules/gosec.yml` file. + stores it in the `/sgrules/gosec.yml` file. Afterwards, semgrep is invoked with the final configuration located under -`/sgrules`. +`/sgrules`. ```toml [semgrep] @@ -537,17 +536,17 @@ It does not explicitly store credentials in the configuration file. To reduce th ##### Configure the append mode for passthroughs To append data to previous passthroughs, use the `append` mode for the -passthrough types `file`, `url`, and `raw`. +passthrough types `file`, `url`, and `raw`. Passthroughs in `override` mode overwrite files created when preceding passthroughs in the chain find a naming collision. If `mode` is set to `append`, a passthrough appends data to the -files created by its predecessors instead of overwriting. +files created by its predecessors instead of overwriting. In the below semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are: - `insecure` -- `secret` +- `secret` These rules add a search pattern to the analyzer and extends semgrep capabilities. @@ -1057,6 +1056,12 @@ For Maven builds, add the following to your `pom.xml` file: </properties> ``` +### SpotBugs Error: `Project couldn't be built` + +If your job is failing at the build step with the message "Project couldn't be built", it's most likely because your job is asking SpotBugs to build with a tool that isn't part of its default tools. For a list of the SpotBugs default tools, see [SpotBugs' asdf dependencies](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/raw/master/config/.tool-versions). + +The solution is to use [pre-compilation](#pre-compilation). Pre-compilation ensures the images required by SpotBugs are available in the job's container. + ### Flawfinder encoding error This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index b5e54e35e58..c5761a5743f 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -1,5 +1,4 @@ --- -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/#assignments @@ -7,38 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Secret Detection **(FREE)** -> - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in GitLab 11.9. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) from GitLab Ultimate to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) from GitLab Ultimate to GitLab Free in 13.3. -A recurring problem when developing applications is that developers may unintentionally commit -secrets and credentials to their remote repositories. If other people have access to the source, -or if the project is public, the sensitive information is then exposed and can be leveraged by -malicious users to gain access to resources like deployment environments. +A recurring problem when developing applications is that people may accidentally commit secrets to +their remote Git repositories. Secrets include keys, passwords, API tokens, and other sensitive +information. Anyone with access to the repository could use the secrets for malicious purposes. +Secrets exposed in this way must be treated as compromised, and be replaced, which can be costly. +It's important to prevent secrets from being committed to a Git repository. -GitLab 11.9 includes a new check called Secret Detection. It scans the content of the repository -to find API keys and other information that should not be there. +Secret Detection uses the [Gitleaks](https://github.com/zricethezav/gitleaks) tool to scan the +repository for secrets. All identified secrets are reported in the: -GitLab displays identified secrets visibly in a few places: - -- [Security Dashboard](../security_dashboard/) +- Merge request widget - Pipelines' **Security** tab -- Report in the merge request widget +- [Security Dashboard](../security_dashboard/)  -## Use cases - -- Detecting unintentional commit of secrets like keys, passwords, and API tokens. -- Performing a single or recurring scan of the full history of your repository for secrets. - -## Supported secrets +WARNING: +Secret Detection does not support scanning binary files. -Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). -The [default ruleset](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes **90+ secret detection patterns**. -You can contribute "well-identifiable" secrets by follow the steps detailed in the [community contributions guidelines](https://gitlab.com/gitlab-org/gitlab/-/issues/345453). +## Detected secrets -WARNING: -Gitleaks does not support scanning binary files. +Secret Detection uses a [default ruleset](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) +containing more than 90 secret detection patterns. You can also customize the secret detection +patterns using [custom rulesets](#custom-rulesets). If you want to contribute rulesets for +"well-identifiable" secrets, follow the steps detailed in the +[community contributions guidelines](https://gitlab.com/gitlab-org/gitlab/-/issues/345453). ## Requirements @@ -376,10 +370,10 @@ For information on this, see the [general Application Security troubleshooting s ### Error: `Couldn't run the gitleaks command: exit status 2` -If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable -is set to 50 (a [project default](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone)), -the Secret Detection job fails as the clone is not deep enough to contain all of the -relevant commits. +If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable's +value is less than that, the Secret Detection job fails as the clone is not deep enough to contain all of the +relevant commits. For information on the current default value, see the +[pipeline configuration documentation](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone). To confirm this as the cause of the error, set the [logging level](../../application_security/secret_detection/index.md#logging-level) to `debug`, then diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png Binary files differdeleted file mode 100644 index 4d51f57a98d..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png Binary files differdeleted file mode 100644 index ad9122ee23c..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png Binary files differdeleted file mode 100644 index cc9f0061a31..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png Binary files differdeleted file mode 100644 index 6578c0bf4cf..00000000000 --- a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 5afbe1ca54e..937ca33c3a1 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -7,193 +7,186 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Security Dashboards and Security Center **(ULTIMATE)** -INFO: -Want to try out security scanning? -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-security-dashboard-docs). +You can use Security Dashboards to view details about vulnerabilities +detected by [security scanners](../index.md#security-scanning-tools). +These details are shown in pipelines, projects, and groups. -GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: +To use the Security Dashboards, you must: -- Security dashboards: An overview of the security status in your personal [Security Center](#security-center), [groups](#group-security-dashboard), and - [projects](#project-security-dashboard). -- [Vulnerability reports](../vulnerability_report/index.md): Detailed lists of all vulnerabilities for the Security Center, group, project, or - pipeline. This is where you triage and manage vulnerabilities. -- [Security Center](#security-center): A dedicated area for personalized vulnerability management. This - includes a security dashboard, vulnerability report, and settings. +- Configure at least one [security scanner](../index.md#security-scanning-tools) in a project. +- Configure jobs to use the [`reports` syntax](../../../ci/yaml/index.md#artifactsreports). +- Use [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or later. If you use the + shared runners on GitLab.com, you are using the correct version. -You can also drill down into a vulnerability and get extra information on the -[Vulnerability Page](../vulnerabilities/index.md). This view includes the project it -comes from, any related file(s), and metadata that helps you analyze the risk it poses. -You can also confirm, dismiss, or resolve a vulnerability, create an issue for it, -and in some cases, generate a merge request to fix the vulnerability. +## When Security Dashboards are updated -To benefit from these features, you must first configure one of the -[security scanners](../index.md). +The Security Dashboards show results of the most recent security scan on the +[default branch](../../project/repository/branches/default.md). +Security scans run only when the default branch updates, so +information on the Security Dashboard might not reflect newly-discovered vulnerabilities. -## Supported reports +To run a daily security scan, +[configure a scheduled pipeline](../../../ci/pipelines/schedules.md). -The security dashboard and vulnerability report displays information about vulnerabilities detected by scanners such as: +## Reduce false negatives in dependency scans -- [Container Scanning](../container_scanning/index.md) -- [Dynamic Application Security Testing](../dast/index.md) -- [Dependency Scanning](../dependency_scanning/index.md) -- [Static Application Security Testing](../sast/index.md) -- [Cluster Image Scanning](../cluster_image_scanning/index.md) -- And [others](../index.md#security-scanning-tools)! +WARNING: +False negatives occur when you resolve dependency versions during a scan, which differ from those +resolved when your project built and released in a previous pipeline. -## Prerequisites +To reduce false negatives in [dependency scans](../../../user/application_security/dependency_scanning/index.md) in scheduled pipelines, ensure you: -1. At least one project inside a group must be configured with at least one of - the [supported reports](#supported-reports). -1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/index.md#artifactsreports). -1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. - If you're using the shared runners on GitLab.com, this is already the case. +- Include a lock file in your project. A lock file lists all transient dependencies and tracks their versions. + - Java projects can't have lock files. + - Python projects can have lock files, but GitLab Secure tools don't support them. +- Configure your project for [Continuous Delivery](../../../ci/introduction/index.md). -## Pipeline Security +## View vulnerabilities in a pipeline > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3. -At the pipeline level, the Security section displays the vulnerabilities present in the branch of -the project the pipeline ran against. - - +To view vulnerabilities in a pipeline: -Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view -the pipeline's security findings, select the **Security** tab when viewing the pipeline. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. From the list, select the pipeline you want to check for vulnerabilities. +1. Select the **Security** tab. -A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish -for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST +A pipeline consists of multiple jobs, such as SAST and DAST scans. If a job fails to finish, +the security dashboard doesn't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, -the analyzer outputs an -[exit code](../../../development/integrations/secure.md#exit-code). +the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). + +## View total number of vulnerabilities per scan + +To view the total number of vulnerabilities per scan: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. Select the **Status** of a branch. +1. Select the **Security** tab. -### Scan details +**Scan details** show the total number of vulnerabilities found per scan in the pipeline. + +### Download security scan outputs > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/333660) in GitLab 14.2. -The **Scan details** section lists the scans run in the pipeline and the total number of vulnerabilities -per scan. +Depending on the type of security scanner, you can download: + +- A JSON artifact that contains the security scanner [report]('https://docs.gitlab.com/ee/development/integrations/secure.html#report'). +- A CSV file that contains URLs and endpoints scanned by the security scanner. + +To download a security scan output: -You can download the JSON artifacts from each security scan. Select **Download results** then -select the JSON artifact. Additionally for the DAST scan, from the **Download results** dropdown select -**Download scanned resources** to download a CSV file containing details of the resources scanned. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. Select the **Status** of a branch. +1. Select the **Security** tab. +1. In **Scan details**, select **Download results**: + - To download a JSON file, select the JSON artifact. + - To download a CSV file, select **Download scanned resources**. -## Project Security Dashboard +## View vulnerabilities over time for a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in GitLab 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285476) in GitLab 13.10, options to zoom in on a date range, and download the vulnerabilities chart. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualize data between given dates. -A project's Security Dashboard displays a chart with the total number of vulnerabilities -over time with up to 365 days of historical data. Data is refreshed daily at 1:15am UTC. By default, -it shows statistics for all vulnerability severities. +The project Security Dashboard shows the total number of vulnerabilities +over time, with up to 365 days of historical data. Data refreshes daily at 01:15 UTC. +It shows statistics for all vulnerabilities. -To access the dashboard, from your project's home page go to **Security & Compliance > Security Dashboard**. +To view total number of vulnerabilities over time: - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Security Dashboard**. +1. Filter and search for what you need. + - To filter the chart by severity, select the legend name. + - To view a specific time frame, use the time range handles (**{scroll-handle}**). + - To view a specific area of the chart, select the left-most icon (**{marquee-selection}**) and drag + across the chart. + - To reset to the original range, select **Remove Selection** (**{redo}**). -### Filter the vulnerabilities chart +### Download the vulnerabilities chart -To filter the chart by vulnerability severity, select the corresponding legend name. +To download an SVG image of the vulnerabilities chart: -In the previous example, the chart shows statistics only for vulnerabilities of medium or unknown severity. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Security dashboard**. +1. Select **Save chart as an image** (**{download}**). -### Customize vulnerabilities chart display +## View vulnerabilities over time for a group -To customize the view of the vulnerability chart, you can select: +The group Security Dashboard gives an overview of vulnerabilities found in the default +branches of projects in a group and its subgroups. -- A specific time frame by using the time range handles (**{scroll-handle}**). -- A specific area of the chart by using the left-most icon (**{marquee-selection}**) then drag - across the chart. To reset to the original range, select **Remove Selection** (**{redo}**). +To view vulnerabilities over time for a group: -### Download a copy of the vulnerabilities chart +1. On the top bar, select **Menu > Groups** and select a group. +1. Select **Security > Security Dashboard**. +1. Hover over the chart to get more details about vulnerabilities. + - You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). + - To view aggregated data beyond a 90-day time frame, use the + [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). + GitLab retains the data for 365 days. -To download an SVG image of the chart, select **Save chart to an image** (**{download}**). +## View project security status for a group -## Group Security Dashboard +Use the group Security Dashboard to view the security status of projects. The security status is based +on the number of detected vulnerabilities. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in GitLab 11.5. +To view project security status for a group: -The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the -projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** -after selecting your group. By default, the Security Dashboard displays all detected and confirmed -vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you -have not selected a group. +1. On the top bar, select **Menu > Groups** and select a group. +1. Select **Security > Security Dashboard**. -Note that the Security Dashboard only shows projects with -[security reports](#supported-reports) -enabled in a group. +Projects are [graded](#project-vulnerability-grades) by vulnerability severity. Dismissed vulnerabilities are excluded. - +To view vulnerabilities, go to the group's [vulnerability report](../vulnerability_report/index.md). -There is a timeline chart that shows how many open -vulnerabilities your projects had at various points in time. You can display the vulnerability -trends over a 30, 60, or 90-day time frame (the default is 90 days). Hover over the chart to get -more details about the open vulnerabilities at a specific time. Aggregated data beyond 90 days can be accessed by querying our [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). This data is retained for 365 days. - -Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: +### Project vulnerability grades | Grade | Description | -| F | One or more "critical" | -| D | One or more "high" or "unknown" | -| C | One or more "medium" | -| B | One or more "low" | -| A | Zero vulnerabilities | - -Projects with no vulnerability tests configured don't appear in the list. Additionally, dismissed -vulnerabilities are excluded. - -Navigate to the group's [vulnerability report](../vulnerability_report/index.md) to view the vulnerabilities found. +| --- | --- | +| **F** | One or more `critical` vulnerabilities | +| **D** | One or more `high` or `unknown` vulnerabilities | +| **C** | One or more `medium` vulnerabilities | +| **B** | One or more `low` vulnerabilities | +| **A** | Zero vulnerabilities | ## Security Center > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in GitLab 13.4. -The Security Center is personal space where you manage vulnerabilities across all your projects. It -displays the vulnerabilities present in the default branches of all the projects you configure. It includes -the following: +The Security Center is a personal space where you view vulnerabilities across all your projects. It +shows the vulnerabilities present in the default branches of the projects. + +The Security Center includes: -- The [group security dashboard's](#group-security-dashboard) features. +- The group Security Dashboard. - A [vulnerability report](../vulnerability_report/index.md). -- A dedicated settings area to configure which projects to display. +- A settings area to configure which projects to display.  +### View the Security Center + To view the Security Center, on the top bar, select **Menu > Security**. -### Adding projects to the Security Center +### Add projects to the Security Center To add projects to the Security Center: -1. Click **Settings** in the left navigation bar or click the **Add projects** button. -1. Search for and add one or more projects using the **Search your projects** field. -1. Click the **Add projects** button. +1. On the top bar, select **Menu > Security**. +1. On the left sidebar, select **Settings**, or select **Add projects**. +1. Use the **Search your projects** text box to search for and select projects. +1. Select **Add projects**. - - -After you add projects, the security dashboard and vulnerability report display the vulnerabilities +After you add projects, the security dashboard and vulnerability report show the vulnerabilities found in those projects' default branches. -## Keep dashboards up to date - -The Security Dashboard displays results of the most recent security scan on the -[default branch](../../project/repository/branches/default.md). By default, security scans are run -only when the default branch is updated. Information on the Security Dashboard may not reflect -newly-discovered vulnerabilities. - -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 updates the information displayed on the Security Dashboard regardless of how often the default -branch is updated. - -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 -can occur because the dependency version resolved during the scan might differ from the ones -resolved when your project was built and released, in a previous pipeline. Java projects can't have -lock files. Python projects can have lock files, but GitLab Secure tools don't support them. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues @@ -206,4 +199,8 @@ 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. --> -Read more on how to [address the vulnerabilities](../vulnerabilities/index.md). +## Related topics + +- [Address the vulnerabilities](../vulnerabilities/index.md) +- [Vulnerability reports](../vulnerability_report/index.md) +- [Vulnerability Page](../vulnerabilities/index.md) diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 7bdc8cc8479..9aa8a0cd3cd 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -37,7 +37,7 @@ A vulnerability's status can be one of the following: | Status | Description | |:----------|:------------| -| Detected | The default state for a newly discovered vulnerability. | +| Detected | The default state for a newly discovered vulnerability. Appears as "Needs triage" in the UI. | | 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 not to be resolved. | | Resolved | The vulnerability has been fixed or is no longer present. | @@ -168,7 +168,7 @@ The following vulnerability scanners and their databases are regularly updated: | Secure scanning tool | Vulnerabilities database updates | |:----------------------------------------------------------------|----------------------------------| | [Container Scanning](../container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. | -| [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). | +| [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 on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Security Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). 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/main/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. | diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 3773bb59c5a..05ff5c511f9 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -100,7 +100,7 @@ The content of the Project filter depends on the current level: | Level | Content of the Project filter | |:---------------|:------------------------------| -| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). | +| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#add-projects-to-the-security-center). | | Group level | All projects in the group. | | Project level | Not applicable. | diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index 93768164df2..f1c49b87383 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -19,11 +19,8 @@ Only CI/CD jobs set in the configuration project can access one of the configure ## Prerequisites -- A running [`kas` instance](install/index.md#set-up-the-agent-server). -- A [configuration repository](install/index.md#define-a-configuration-repository) with an agent config file - installed (`.gitlab/agents/<agent-name>/config.yaml`). -- A [registered agent](install/index.md#register-an-agent-with-gitlab). -- The agent [installed in the cluster](install/index.md#install-the-agent-into-the-cluster). +- An existing Kubernetes cluster. +- An agent [installed on your cluster](install/index.md#install-the-agent-into-the-cluster). ## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index c950a4f0dc0..a235c0ef6f8 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -18,10 +18,6 @@ is an active in-cluster component for connecting Kubernetes clusters to GitLab s The Agent is installed into the cluster through code, providing you with a fast, safe, stable, and scalable solution. -INFO: -Get Network Security Alerts in GitLab by upgrading to Ultimate. -[Try a free 30-day trial now](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-cluster-agent-docs). - With GitOps, you can manage containerized clusters and applications from a Git repository that: - Is the single source of truth of your system. @@ -136,7 +132,22 @@ with the following differences: ## Remove an agent -1. Get the `<cluster-agent-id>` and the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer. +You can remove an agent using the [GitLab UI](#remove-an-agent-through-the-gitlab-ui) or through the [GraphQL API](#remove-an-agent-with-the-gitlab-graphql-api). + +### Remove an agent through the GitLab UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323055) in GitLab 14.7. + +To remove an agent from the UI: + +1. Go to your agent's configuration repository. +1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**. +1. Select your agent from the table, and then in the **Options** column, click the vertical ellipsis +(**{ellipsis_v}**) button and select **Delete agent**. + +### Remove an agent with the GitLab GraphQL API + +1. Get the `<cluster-agent-token-id>` from a query in the interactive GraphQL explorer. For GitLab.com, go to <https://gitlab.com/-/graphql-explorer> to open GraphQL Explorer. For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-explorer`, replacing `gitlab.example.com` with your own instance's URL. @@ -157,7 +168,7 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e } ``` -1. Remove an Agent record with GraphQL by deleting the `clusterAgent` and the `clusterAgentToken`. +1. Remove an agent record with GraphQL by deleting the `clusterAgentToken`. ```graphql mutation deleteAgent { @@ -190,6 +201,10 @@ For self-managed GitLab instances, go to `https://gitlab.example.com/-/graphql-e kubectl delete -n gitlab-kubernetes-agent -f ./resources.yml ``` +## Migrating to the GitLab Agent from the legacy certificate-based integration + +Find out how to [migrate to the GitLab Agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration depending on the features you use. + ## Troubleshooting If you face any issues while using the Agent, read the diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index cf8467a8d28..b2372789284 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -10,42 +10,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w To get started with the Agent, install it in your cluster. -Pre-requisites: +## Prerequisites **(SELF)** - An existing Kubernetes cluster. -- An account on GitLab. +- On self-managed GitLab instances, a GitLab administrator needs to set up the [GitLab Agent Server (KAS)](../../../../administration/clusters/kas.md). ## Installation steps To install the [Agent](../index.md) in your cluster: -1. [Set up the Agent Server](#set-up-the-agent-server) for your GitLab instance. 1. [Define a configuration repository](#define-a-configuration-repository). 1. [Register an agent with GitLab](#register-an-agent-with-gitlab). 1. [Install the agent into the cluster](#install-the-agent-into-the-cluster). -1. [Generate and copy a Secret token used to connect to the agent](#create-the-kubernetes-secret). -1. [Create manifest files](#create-manifest-files). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process. -### Set up the Agent Server - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. - -To use the KAS: - -- If you are a self-managed user, follow the instructions to [install the Agent Server](../../../../administration/clusters/kas.md). -- If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`. - ### Define a configuration repository > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository. > - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -To create an agent, you need: - -1. A GitLab repository to hold the configuration file. -1. Install the Agent in a cluster. +To create an agent, you need a GitLab repository to hold the configuration file. After installed, when you update the configuration file, GitLab transmits the information to the cluster automatically without downtime. @@ -62,7 +47,7 @@ WARNING: The agent is only recognized if you use `.yaml` extension for the `config.yaml` file. The extension `.yml` is **not** recognized. You **don't have to add any content** to this file when you create it. The fact that the file exists -tells GitLab that this is an agent configuration file. It doesn't do anything so far, but, later on, you can use this +tells GitLab that this is an agent configuration file and enables the [CI/CD tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel). Later on, you can use this file to [configure the agent](../repository.md) by setting up parameters such as: - Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md). @@ -71,10 +56,6 @@ file to [configure the agent](../repository.md) by setting up parameters such as To see all the settings available, read the [Agent configuration repository documentation](../repository.md). -### Access your cluster from GitLab CI/CD - -Use the [CI/CD Tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel) to access your cluster from GitLab CI/CD. - ### Register an agent with GitLab > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI. @@ -92,242 +73,53 @@ In GitLab: 1. The form reveals your registration token. Securely store this secret token as you cannot view it again. 1. Copy the command under **Recommended installation method**. +### Install the agent into the cluster + In your computer: 1. Open your local terminal and connect to your cluster. -1. Run the command you copied from the installation form. +1. Run the command you copied when registering your cluster in the previous step. -### Install the agent into the cluster +See the following sections to learn about customizing the installation. -To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace, -for example, `gitlab-kubernetes-agent`, run: +## Simple installation method -```shell -kubectl create namespace gitlab-kubernetes-agent -``` +The command provided by GitLab does the following things: -To perform a one-liner installation, run the command below. Make sure to replace: +- Creates a namespace for the deployment (`gitlab-kubernetes-agent`). +- Sets up a service account with `cluster-admin` rights. Read more on [how you can restrict this service account](#customize-the-permissions-for-the-agentk-service-account). +- Creates a `Secret` resource for the agent registration token. +- Creates a `Deployment` resource for the `agentk` pod. -- `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). -- `gitlab-kubernetes-agent` with the namespace you defined in the previous step. -- `wss://kas.gitlab.example.com` with the configured access of the Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. -- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. +The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run: ```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f - +docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help ``` WARNING: `--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for testing purposes but for production please make sure to specify a matching version explicitly. -To find out the various options the above Docker container supports, run: - -```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help -``` - -## Advanced installation +## Advanced installation method For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). Otherwise, follow the manual installation steps described below. -### Create the Kubernetes secret - -After generating the token, you must apply it to the Kubernetes cluster. - -To create your Secret, run: - -```shell -kubectl create secret generic -n gitlab-kubernetes-agent gitlab-kubernetes-agent-token --from-literal=token='YOUR_AGENT_TOKEN' -``` - -The following example file contains the -Kubernetes resources required for the Agent to be installed. You can modify this -example [`resources.yml` file](#example-resourcesyml-file) in the following ways: - -- Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. -- You can configure `kas-address` (Agent Server) in several ways. - The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. - Select the option appropriate for your cluster configuration and GitLab architecture: - - The `wss` scheme (an encrypted WebSockets connection) is specified by default - after you install 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. - - 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>:8150`) to use gRPC directly, where `gitlab-kas` - is the name of the service created by `gitlab-kas` chart, and `<your-namespace>` - is the namespace where the chart was installed. - - Specify the `grpcs` scheme to use an encrypted gRPC connection. - - 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 documentation](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-kubernetes-agent-token` with your - secret name in the `secretName:` section. - -To apply this file, run the following command: +### Customize the permissions for the `agentk` service account -```shell -kubectl apply -n gitlab-kubernetes-agent -f ./resources.yml -``` - -To review your configuration, run the following command: - -```shell -$ kubectl get pods -n gitlab-kubernetes-agent - -NAMESPACE NAME READY STATUS RESTARTS AGE -gitlab-kubernetes-agent gitlab-kubernetes-agent-77689f7dcb-5skqk 1/1 Running 0 51s -``` - -#### Example `resources.yml` file - -```yaml ---- -apiVersion: v1 -kind: Namespace -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: gitlab-kubernetes-agent -spec: - replicas: 1 - selector: - matchLabels: - app: gitlab-kubernetes-agent - template: - metadata: - labels: - app: gitlab-kubernetes-agent - spec: - serviceAccountName: gitlab-kubernetes-agent - containers: - - name: agent - # Make sure to specify a matching version for production - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z" - args: - - --token-file=/config/token - - --kas-address - - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. - # - wss://gitlab.host.tld:443/-/kubernetes-agent/ - # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. - # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. - volumeMounts: - - name: token-volume - mountPath: /config - volumes: - - name: token-volume - secret: - secretName: gitlab-kubernetes-agent-token - strategy: - type: RollingUpdate - rollingUpdate: - maxSurge: 0 - maxUnavailable: 1 ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-write -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - create - - update - - delete - - patch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-write-binding -roleRef: - name: gitlab-kubernetes-agent-write - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-read -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - get - - list - - watch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-read-binding -roleRef: - name: gitlab-kubernetes-agent-read - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent -``` - -### Create manifest files +The GitLab Agent for Kubernetes allows you to fully own your cluster and requires only the permissions you give. Still, for easy getting started, by default the generated manifests provide `cluster-admin` rights to the agent. -In a previous step, you configured a `config.yaml` to point to the GitLab projects -the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a -templating engine or other means. +As part of the advanced installation method, you can restrict the agent access rights using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation. -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). +To create restricted permissions: -Each time you push a change to a monitored manifest repository, the Agent logs the change: +1. Copy the `cluster` directory. +1. Edit the `kustomization.yaml` and `components/*` files based on your requirements. +1. Run `kustomize build <your copied directory> | kubectl apply -f -` to apply your configuration. -```plaintext -2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea -``` - -#### Example manifest file - -This file creates a minimal `ConfigMap`: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: demo-map - namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. -data: - key: value -``` +The above setup allows you to regularly update from the upstream package using `kpt pkg update gitlab-agent --strategy resource-merge` and maintain your customizations at the same time. ## Example projects diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index c8ab037118e..22964fde395 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -12,9 +12,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - The [GitLab Agent](index.md) supports hosting your configuration for multiple 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. diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 88382648b04..f880e603133 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -54,7 +54,7 @@ Supported applications: - [PostHog](#install-posthog-using-gitlab-cicd) - [Prometheus](#install-prometheus-using-gitlab-cicd) -### Usage +### Prerequisites You can find and import all the files referenced below in the [example cluster applications @@ -95,7 +95,7 @@ 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 +#### Prerequisites in GitLab versions earlier than 13.5 For GitLab versions 13.5 and earlier, the Ingress, Fluentd, Prometheus, and Sentry apps were fetched from the central Helm stable repository (`https://kubernetes-charts.storage.googleapis.com/`). @@ -443,7 +443,7 @@ You can check the recommended variables for each cluster type in the official do - [Google GKE](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-gke/#deploy-cilium) - [AWS EKS](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-eks/#deploy-cilium) -Do not use `clusterType` for sandbox environments like [Minikube](https://minikube.sigs.k8s.io/docs/). +Do not use `clusterType` for sandbox environments like [minikube](https://minikube.sigs.k8s.io/docs/). You can customize Cilium's Helm variables by defining the `.gitlab/managed-apps/cilium/values.yaml` file in your cluster diff --git a/doc/user/compliance/index.md b/doc/user/compliance/index.md index 61b65bf254f..7b46886e236 100644 --- a/doc/user/compliance/index.md +++ b/doc/user/compliance/index.md @@ -7,15 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Compliance **(ULTIMATE)** -The compliance tools provided by GitLab let you keep an eye on various aspects of your project. The -following compliance tools are available: - -- [Compliance report](compliance_report/index.md): View recent merge request activity across - all projects in a group. This lets you see if merge requests were approved, and by whom. -- [License Compliance](license_compliance/index.md): Search your project's dependencies for their - licenses. This lets you determine if the licenses of your project's dependencies are compatible - with your project's license. -- [Compliance framework labels](../project/settings/index.md#compliance-frameworks): Label your projects that have unique compliance requirements. -- [Compliance pipelines](../project/settings/index.md#compliance-pipeline-configuration): Ensure that needed compliance jobs are always run for compliance-labeled projects. -- [Audit Events](../../administration/audit_events.md): Get visibility into individual actions that have taken place in your GitLab instance, group, or project. -- [Audit Reports](../../administration/audit_reports.md): Create and access reports based on the audit events that have occurred. Use pre-built GitLab reports or the API to build your own. +The compliance tools provided by GitLab help you keep an eye on various aspects of your project. For more information +on GitLab compliance features for projects, groups, and instances, see +[Compliance features](../../administration/compliance.md). diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index f89165e7e2d..04d3cc0595e 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -5,7 +5,7 @@ group: Composition Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# License Compliance **(ULTIMATE)** +# License compliance **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5483) in GitLab 11.0. @@ -14,10 +14,6 @@ project's dependencies for their licenses. You can then decide whether to allow each license. For example, if your application uses an external (open source) library whose license is incompatible with yours, then you can deny the use of that license. -INFO: -Try License Compliance scanning to search project dependencies in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-compliance-docs). - You can take advantage of License Compliance by either: - [Including the job](#configuration) @@ -73,7 +69,7 @@ Gradle 1.x projects are not supported. The minimum supported version of Maven is | Language | Package managers | Notes | |------------|----------------------------------------------------------------------------------------------|-------| | JavaScript | [Bower](https://bower.io/), [npm](https://www.npmjs.com/) (7 and earlier) | | -| Go | [Godep](https://github.com/tools/godep), [go mod](https://github.com/golang/go/wiki/Modules) | | +| Go | [Godep](https://github.com/tools/godep) ([deprecated](../../../update/deprecations.md#godep-support-in-license-compliance)), [go mod](https://github.com/golang/go/wiki/Modules) | | | Java | [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) | | | .NET | [NuGet](https://www.nuget.org/) | The .NET Framework is supported via the [mono project](https://www.mono-project.com/). There are, however, some limitations. The scanner doesn't support Windows-specific dependencies and doesn't report dependencies of your project's listed dependencies. Also, the scanner always marks detected licenses for all dependencies as `unknown`. | | Python | [pip](https://pip.pypa.io/en/stable/) | Python is supported through [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) and [Pipfile.lock](https://github.com/pypa/pipfile#pipfilelock). | @@ -92,7 +88,6 @@ The reported licenses might be incomplete or inaccurate. | 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/) | @@ -809,6 +804,10 @@ An approval is optional when a license report: - Contains no software license violations. - Contains only new licenses that are `allowed` or unknown. +## Warnings + +We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. + ## Troubleshooting ### ASDF_PYTHON_VERSION does not automatically install the version diff --git a/doc/user/crm/index.md b/doc/user/crm/index.md index d68ce0a4f7a..f0f9a907a73 100644 --- a/doc/user/crm/index.md +++ b/doc/user/crm/index.md @@ -6,13 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Customer relations management (CRM) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `customer_relations`. -On GitLab.com, this feature is not available. -You should not use this feature for production environments. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2256) in GitLab 14.6 [with a flag](../../administration/feature_flags.md) named `customer_relations`. Disabled by default. With customer relations management (CRM) you can create a record of contacts (individuals) and organizations (companies) and relate them to issues. @@ -20,6 +14,25 @@ With customer relations management (CRM) you can create a record of contacts You can use contacts and organizations to tie work to customers for billing and reporting purposes. To read more about what is planned for the future, see [issue 2256](https://gitlab.com/gitlab-org/gitlab/-/issues/2256). +## Permissions + +| Permission | Guest | Reporter | Developer, Maintainer, and Owner | +| ---------- | ---------------- | -------- | -------------------------------- | +| View contacts/organizations | | ✓ | ✓ | +| View issue contacts | | ✓ | ✓ | +| Add/remove issue contacts | | ✓ | ✓ | +| Create/edit contacts/organizations | | | ✓ | + +## Enable customer relations management (CRM) + +To enable customer relations management in a group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Permissions and group features** section. +1. Select **Enable customer relations**. +1. Select **Save changes**. + ## Contacts ### View contacts linked to a group @@ -118,10 +131,6 @@ API. ### Add or remove issue contacts -Prerequisites: - -- You must have at least the [Developer role](../permissions.md#project-members-permissions) for a group. - ### Add contacts to an issue To add contacts to an issue use the `/add_contacts` diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 8d858a282dd..f02073b477b 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -70,7 +70,7 @@ To back up an entire project on GitLab.com, you can export it either: can also use the API to programmatically upload exports to a storage platform, such as Amazon S3. -With exports, be aware of [what is and is not](../project/settings/import_export.md#exported-contents) +With exports, be aware of [what is and is not](../project/settings/import_export.md#items-that-are-exported) included in a project export. GitLab is built on Git, so you can back up just the repository of a project by @@ -162,17 +162,18 @@ varies by format: ## Account and limit settings -GitLab.com has the following [account limits](../admin_area/settings/account_and_limit_settings.md) -enabled. If a setting is not listed, it is set to the default value. +GitLab.com has the following account limits enabled. If a setting is not listed, +the default value [is the same as for self-managed instances](../admin_area/settings/account_and_limit_settings.md): -If you are near or over the repository size limit, you can either -[reduce your repository size with Git](../project/repository/reducing_the_repo_size_using_git.md) or [purchase additional storage](https://about.gitlab.com/pricing/licensing-faq/#can-i-buy-more-storage). +| Setting | GitLab.com default | +|-------------------------------|--------------------| +| [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | +| Maximum import size | 5 GB | +| Maximum attachment size | 10 MB | -| Setting | GitLab.com | Default | -|-------------------------------|-------------|---------| -| [Repository size including LFS](../admin_area/settings/account_and_limit_settings.md#repository-size-limit) | 10 GB | Unlimited | -| Maximum import size | 5 GB | Unlimited ([Modified](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50MB to unlimited in GitLab 13.8.) | -| Maximum attachment size | 10 MB | 10 MB | +If you are near or over the repository size limit, you can either +[reduce your repository size with Git](../project/repository/reducing_the_repo_size_using_git.md) +or [purchase additional storage](https://about.gitlab.com/pricing/licensing-faq/#can-i-buy-more-storage). NOTE: `git push` and GitLab project imports are limited to 5 GB per request through @@ -209,13 +210,17 @@ also load certain page content directly from common public CDN hostnames. ## Webhooks -The following limits apply for [Webhooks](../project/integrations/webhooks.md): +The following limits apply for [webhooks](../project/integrations/webhooks.md): + +| Setting | Default for GitLab.com | +|----------------------|-------------------------| +| Webhook rate limit | `120` calls per minute for GitLab Free, unlimited for GitLab Premium and GitLab Ultimate | +| Number of webhooks | `100` per project, `50` per group | +| Maximum payload size | 25 MB | -| Setting | GitLab.com | Default | -|----------------------|-------------|---------| -| [Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit) | `120` calls per minute for GitLab Free, unlimited for GitLab Premium and GitLab Ultimate | Unlimited | -| [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks) | `100` per project, `50` per group | `100` per project, `50` per group | -| Maximum payload size | 25 MB | 25 MB | +For self-managed instance limits, see +[Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit) +and [Number of webhooks](../../administration/instance_limits.md#number-of-webhooks). ## Runner SaaS diff --git a/doc/user/group/epics/epic_boards.md b/doc/user/group/epics/epic_boards.md index 1bc1e4d703b..d184030718a 100644 --- a/doc/user/group/epics/epic_boards.md +++ b/doc/user/group/epics/epic_boards.md @@ -9,10 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5067) in GitLab 13.10. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290039) in GitLab 14.1. -INFO: -Try epic boards and more with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-epics-boards-docs). - Epic boards build on the existing [epic tracking functionality](index.md) and [labels](../../project/labels.md). Your epics appear as cards in vertical lists, organized by their assigned labels. diff --git a/doc/user/group/epics/img/epics_search_v13_11.png b/doc/user/group/epics/img/epics_search_v13_11.png Binary files differdeleted file mode 100644 index c11aca96a99..00000000000 --- a/doc/user/group/epics/img/epics_search_v13_11.png +++ /dev/null diff --git a/doc/user/group/epics/img/epics_search_v14_7.png b/doc/user/group/epics/img/epics_search_v14_7.png Binary files differnew file mode 100644 index 00000000000..baed532c736 --- /dev/null +++ b/doc/user/group/epics/img/epics_search_v14_7.png diff --git a/doc/user/group/epics/img/epics_sort.png b/doc/user/group/epics/img/epics_sort.png Binary files differdeleted file mode 100644 index b23c65fd0ef..00000000000 --- a/doc/user/group/epics/img/epics_sort.png +++ /dev/null diff --git a/doc/user/group/epics/img/epics_sort_14_7.png b/doc/user/group/epics/img/epics_sort_14_7.png Binary files differnew file mode 100644 index 00000000000..df84dccd06c --- /dev/null +++ b/doc/user/group/epics/img/epics_sort_14_7.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 3889398e2f8..d6f87a026b8 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -8,10 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Single-level epics were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. -INFO: -Check out [multi-level child epics](manage_epics.md#multi-level-child-epics) with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-epics-docs). - When [issues](../../project/issues/index.md) share a theme across projects and milestones, you can manage them by using epics. diff --git a/doc/user/group/epics/manage_epics.md b/doc/user/group/epics/manage_epics.md index f5b1a2a6ee6..caca10a05a2 100644 --- a/doc/user/group/epics/manage_epics.md +++ b/doc/user/group/epics/manage_epics.md @@ -163,6 +163,8 @@ than 1000. The cached value is rounded to thousands or millions and updated ever > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) from GitLab Ultimate to GitLab Premium in 12.8. > - Searching by the user's reaction emoji [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325630) in GitLab 13.11. > - Sorting by epic titles [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/331625) in GitLab 14.1. +> - Searching by milestone and confidentiality [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/268372) in GitLab 14.2 [with a flag](../../../administration/feature_flags.md) named `vue_epics_list`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/276189) in GitLab 14.7. You can search for an epic from the list of epics using filtered search bar based on following parameters: @@ -170,9 +172,11 @@ parameters: - Title or description - Author name / username - Labels +- Milestones +- Confidentiality - Reaction emoji - + To search: @@ -184,8 +188,6 @@ To search: You can also sort epics list by: -- Created date -- Last updated - Start date - Due date - Title @@ -194,7 +196,7 @@ Each option contains a button that can toggle the order between **Ascending** an The sort option and order is saved and used wherever you browse epics, including the [Roadmap](../roadmap/index.md). - + ## Change activity sort order diff --git a/doc/user/group/img/group_code_coverage_analytics_v13_9.png b/doc/user/group/img/group_code_coverage_analytics_v13_9.png Binary files differdeleted file mode 100644 index 8cd71396381..00000000000 --- a/doc/user/group/img/group_code_coverage_analytics_v13_9.png +++ /dev/null diff --git a/doc/user/group/index.md b/doc/user/group/index.md index db6ed02f405..8aa9b8e799d 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -100,6 +100,14 @@ You can give a user access to all projects in a group. 1. Fill in the fields. - The role applies to all projects in the group. [Learn more about permissions](../permissions.md). - On the **Access expiration date**, the user can no longer access projects in the group. +1. Select **Invite**. + +Members that are not automatically added are displayed on the **Invited** tab. +Users can be on this tab because they: + +- Have not yet accepted the invitation. +- Are waiting for [approval from an administrator](../admin_area/moderate_users.md). +- [Exceed the group user cap](#user-cap-for-groups). ## Request access to a group @@ -123,7 +131,7 @@ your group. 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Clear the **Allow users to request access** checkbox. 1. Select **Save changes**. @@ -219,7 +227,7 @@ To change this setting for a specific group: 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select the desired option in the **Default branch protection** dropdown list. 1. Select **Save changes**. @@ -250,7 +258,7 @@ To change this setting for a specific group: 1. Select **Your Groups**. 1. Find the group and select it. 1. From the left menu, select **Settings > General**. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select the desired option in the **Allowed to create projects** dropdown list. 1. Select **Save changes**. @@ -489,7 +497,7 @@ If you select this setting in the **Animals** group: To prevent sharing outside of the group's hierarchy: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Prevent members from sending invitations to groups outside of `<group_name>` and its subgroups**. 1. Select **Save changes**. @@ -501,13 +509,81 @@ a project with another group](../project/members/share_project_with_groups.md) t To prevent a project from being shared with other groups: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Prevent sharing a project within `<group_name>` with other groups**. 1. Select **Save changes**. This setting applies to all subgroups unless overridden by a group owner. Groups already added to a project lose access when the setting is enabled. +## User cap for groups + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330027) in GitLab 14.7. + +FLAG: +On self-managed GitLab, this feature is not available. On GitLab.com, this feature is available for some groups. +This feature is not ready for production use. + +When the number of billable members reaches the user cap, new users can't be added to the group +without being approved by the group owner. + +Groups with the user cap feature enabled have [group sharing](#share-a-group-with-another-group) +disabled for the group and its subgroups. + +### Specify a user cap for a group + +Prerequisite: + +- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. + +To specify a user cap: + +1. On the top bar, select **Menu > Groups** and find your group. + You can set a cap on the top-level group only. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. In the **User cap** box, enter the desired number of users. +1. Select **Save changes**. + +If you already have more users in the group than the user cap value, users +are not removed. However, you can't add more without approval. + +Increasing the user cap does not approve pending members. + +### Remove the user cap for a group + +You can remove the user cap, so there is no limit on the number of members you can add to a group. + +Prerequisite: + +- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. + +To remove the user cap: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. In the **User cap** box, delete the value. +1. Select **Save changes**. + +Decreasing the user cap does not approve pending members. + +### Approve pending members for a group + +When the number of billable users reaches the user cap, any new member is put in a pending state +and must be approved. + +Prerequisite: + +- You must be assigned the [Owner role](../permissions.md#group-members-permissions) for the group. + +To approve members that are pending because they've exceeded the user cap: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Usage Quotas**. +1. On the **Seats** tab, under the alert, select **View pending approvals**. +1. For each member you want to approve, select **Approve**. + ## Prevent members from being added to projects in a group **(PREMIUM)** As a group owner, you can prevent any new project membership for all @@ -523,7 +599,7 @@ The setting does not cascade. Projects in subgroups observe the subgroup configu To prevent members from being added to projects in a group: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Under **Member lock**, select **Prevent adding new members to project membership within this group**. 1. Select **Save changes**. @@ -535,9 +611,9 @@ API requests to add a new user to a project are not possible. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/287940) in GitLab 14.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/336520) in GitLab 14.5. -You can export a list of members in a group as a CSV. +You can export a list of members in a group or subgroup as a CSV. -1. Go to your project and select **Project information > Members**. +1. Go to your group or subgroup and select either **Group information > Members** or **Subgroup information > Members**. 1. Select **Export as CSV**. 1. Once the CSV file has been generated, it is emailed as an attachment to the user that requested it. @@ -574,7 +650,7 @@ You should consider these security implications before configuring IP address re To restrict group access by IP address: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. In the **Allow access to the following IP addresses** field, enter IP address ranges in CIDR notation. 1. Select **Save changes**. @@ -591,13 +667,15 @@ You can prevent users with email addresses in specific domains from being added To restrict group access by domain: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. In the **Restrict membership by email** field, enter the domain names. 1. Select **Save changes**.  -Any time you attempt to add a new user, they are compared against this list. +Any time you attempt to add a new user, the user's [primary email](../profile/index.md#change-your-primary-email) is compared against this list. +Only users with a [primary email](../profile/index.md#change-your-primary-email) that matches any of the configured email domain restrictions +can be added to the group. Some domains cannot be restricted. These are the most popular public email domains, such as: @@ -645,7 +723,7 @@ You can disable all email notifications related to the group, which includes its To disable email notifications: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Disable email notifications**. 1. Select **Save changes**. @@ -663,7 +741,7 @@ This is particularly helpful for groups with a large number of users. To disable group mentions: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Select **Disable group mentions**. 1. Select **Save changes**. @@ -688,7 +766,7 @@ the default setting. To enable delayed deletion of projects in a group: 1. Go to the group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Check **Enable delayed project deletion**. 1. Optional. To prevent subgroups from changing this setting, select **Enforce for all subgroups**. 1. Select **Save changes**. @@ -713,7 +791,7 @@ If even one is set to `true`, then the group does not allow outside forks. To prevent projects from being forked outside the group: 1. Go to the top-level group's **Settings > General** page. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Check **Prevent project forking outside current group**. 1. Select **Save changes**. @@ -774,7 +852,7 @@ To view the merge request approval rules for a group: - [Webhooks](../project/integrations/webhooks.md). - [Kubernetes cluster integration](clusters/index.md). - [Audit Events](../../administration/audit_events.md#group-events). -- [Pipelines quota](../admin_area/settings/continuous_integration.md): Keep track of the pipeline quota for the group. +- [CI/CD minutes quota](../../ci/pipelines/cicd_minutes.md): Keep track of the CI/CD minute quota for the group. - [Integrations](../admin_area/settings/project_integration_management.md). - [Transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). - [Share a project with a group](../project/members/share_project_with_groups.md): Give all group members access to the project at once. diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index ac5df6b052f..62337dabcc0 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -5,15 +5,18 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Issue Analytics **(PREMIUM)** +# Issue analytics for groups **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7478) in GitLab 11.5. -Issue Analytics is a bar graph which illustrates the number of issues created each month. +Issue analytics is a bar graph which illustrates the number of issues created each month. The default time span is 13 months, which includes the current month, and the 12 months prior. -To access the chart, navigate to your group sidebar and select **{chart}** **Analytics > Issue Analytics**. +To access the chart: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Analytics > Issue Analytics**. Hover over each bar to see the total number of issues. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index c6cd763355b..2487ab188e8 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -5,11 +5,15 @@ 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/#assignments --- -# Repositories Analytics **(PREMIUM)** +# Repositories analytics for groups **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in GitLab 13.4. - +Repositories analytics for groups provides information about test coverage for all projects in a group. An +[issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/273527) to also extend support for all projects in +subgroups. + +It is similar to [repository analytics for projects](../../analytics/repository_analytics.md). ## Current group code coverage diff --git a/doc/user/group/saml_sso/group_managed_accounts.md b/doc/user/group/saml_sso/group_managed_accounts.md index d62b569a795..06e666f4d24 100644 --- a/doc/user/group/saml_sso/group_managed_accounts.md +++ b/doc/user/group/saml_sso/group_managed_accounts.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -113,7 +113,7 @@ on the lifetime of personal access tokens apply. To set a limit on how long personal access tokens are valid for users in a group managed account: 1. Navigate to the **Settings > General** page in your group's sidebar. -1. Expand the **Permissions, LFS, 2FA** section. +1. Expand the **Permissions and group features** section. 1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 7443be250bb..20ff4a201f5 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,7 +1,7 @@ --- type: reference, howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -14,10 +14,6 @@ This page describes SAML for groups. For instance-wide SAML on self-managed GitL SAML on GitLab.com allows users to sign in through their SAML identity provider. If the user is not already a member, the sign-in process automatically adds the user to the appropriate group. -INFO: -Use your own SAML authentication to log in to [GitLab.com](http://gitlab.com/). -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-saml-sso-docs). - User synchronization of SAML SSO groups is supported through [SCIM](scim_setup.md). SCIM supports adding and removing users from the GitLab group automatically. For example, if you remove a user from the SCIM app, SCIM removes that same user from the GitLab group. @@ -72,10 +68,10 @@ To create users with the correct information for improved [user access and manag the user's details must be passed to GitLab as attributes in the SAML assertion. At a minimum, the user's email address must be specified as an attribute named `email` or `mail`. -GitLab.com supports the following attributes: +You can configure the following attributes with GitLab.com Group SAML: - `username` or `nickname`. We recommend you configure only one of these. -- The [attributes also available](../../../integration/saml.md#assertions) to self-managed GitLab instances. +- The [attributes available](../../../integration/saml.md#assertions) to self-managed GitLab instances. ### Metadata configuration @@ -110,6 +106,7 @@ The certificate [fingerprint algorithm](../../../integration/saml.md#notes-on-co > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/292811) in GitLab 13.8, with an updated timeout experience. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/211962) in GitLab 13.8 with allowing group owners to not go through SSO. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/9152) in GitLab 13.11 with enforcing open SSO session to use Git if this setting is switched on. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/339888) in GitLab 14.7 to not enforce SSO checks for Git activity originating from CI/CD jobs. With this option enabled, users (except users with the Owner role) must access GitLab using your group GitLab single sign-on URL to access group resources. Users added manually as members can't access group resources. @@ -127,6 +124,7 @@ SSO has the following effects when enabled: even if the project is forked. - For Git activity over SSH and HTTPS, users must have at least one active session signed-in through SSO before they can push to or pull from a GitLab repository. +- Git activity originating from CI/CD jobs do not have the SSO check enforced. - Credentials that are not tied to regular users (for example, access tokens and deploy keys) do not have the SSO check enforced. - Users must be signed-in through SSO before they can pull images using the [Dependency Proxy](../../packages/dependency_proxy/index.md). <!-- Add bullet for API activity when https://gitlab.com/gitlab-org/gitlab/-/issues/9152 is complete --> @@ -137,8 +135,6 @@ When SSO is enforced, users are not immediately revoked. If the user: - Has an active session, they can continue accessing the group for up to 24 hours until the identity provider session times out. -When SCIM updates, the user's access is immediately revoked. - ## Providers The SAML standard means that you can use a wide range of identity providers with GitLab. Your identity provider might have relevant documentation. It can be generic SAML documentation or specifically targeted for GitLab. @@ -167,10 +163,11 @@ objectID mapping and the [SCIM documentation should be followed](scim_setup.md#a | Identity provider single sign-on URL | Login URL | | Certificate fingerprint | Thumbprint | -We recommend: +The recommended attributes and claims settings are: - **Unique User Identifier (Name identifier)** set to `user.objectID`. - **nameid-format** set to persistent. +- Additional claims set to [supported attributes](#user-attributes). If using [Group Sync](#group-sync), customize the name of the group claim to match the required attribute. @@ -304,7 +301,14 @@ If a user is already a member of the group, linking the SAML identity does not c ### Blocking access -Please refer to [Blocking access via SCIM](scim_setup.md#blocking-access). +To rescind a user's access to the group when only SAML SSO is configured, either: + +- Remove (in order) the user from: + 1. The user data store on the identity provider or the list of users on the specific app. + 1. The GitLab.com group. +- Use Group Sync at the top-level of your group to [automatically remove the user](#automatic-member-removal). + +To rescind a user's access to the group when also using SCIM, refer to [Blocking access](scim_setup.md#blocking-access). ### Unlinking accounts @@ -349,6 +353,10 @@ Ensure your SAML identity provider sends an attribute statement named `Groups` o </saml:AttributeStatement> ``` +WARNING: +Setting up Group Sync can disconnect users from SAML IDP if there is any mismatch in the configuration. Ensure the +`Groups` attribute is included in the SAML response, and the **SAML Group Name** matches the `AttributeValue` attribute. + Other attribute names such as `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` are not accepted as a source of groups. See the [SAML troubleshooting page](../../../administration/troubleshooting/group_saml_scim.md) diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 2651bcb9e12..d7d663f4115 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,7 +1,7 @@ --- type: howto, reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -184,8 +184,7 @@ For role information, please see the [Group SAML page](index.md#user-access-and- ### Blocking access To rescind access to the top-level group, all sub-groups, and projects, remove or deactivate the user -on the identity provider. SCIM providers generally update GitLab with the changes on demand, which -is minutes at most. The user's membership is revoked and they immediately lose access. +on the identity provider. After the identity provider performs a sync, based on its configured schedule, the user's membership is revoked and they lose access. NOTE: Deprovisioning does not delete the GitLab user account. diff --git a/doc/user/group/settings/group_access_tokens.md b/doc/user/group/settings/group_access_tokens.md new file mode 100644 index 00000000000..816edb629f5 --- /dev/null +++ b/doc/user/group/settings/group_access_tokens.md @@ -0,0 +1,147 @@ +--- +stage: Manage +group: Authentication & Authorization +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" +type: reference, howto +--- + +# Group access tokens + +With group access tokens, you can use a single token to: + +- Perform actions for groups. +- Manage the projects within the group. + +You can use a group access token to authenticate: + +- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). +- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. + +After you configure a group access token, you don't need a password when you authenticate. +Instead, you can enter any non-blank value. + +Group access tokens are similar to [project access tokens](../../project/settings/project_access_tokens.md) +and [personal access tokens](../../profile/personal_access_tokens.md), except they are +associated with a group rather than a project or user. + +You can use group access tokens: + +- On GitLab SaaS if you have the Premium license tier or higher. Group access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). +- On self-managed instances of GitLab, with any license tier. If you have the Free tier: + - Review your security and compliance policies around + [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). + - Consider [disabling group access tokens](#enable-or-disable-group-access-token-creation) to + lower potential abuse. + +Group access tokens inherit the [default prefix setting](../../admin_area/settings/account_and_limit_settings.md#personal-access-token-prefix) +configured for personal access tokens. + +## Create a group access token using UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7. + +To create a group access token: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Enter a name. +1. Optional. Enter an expiry date for the token. The token will expire on that date at midnight UTC. +1. Select a role for the token. +1. Select the [desired scopes](#scopes-for-a-group-access-token). +1. Select **Create group access token**. + +A group access token is displayed. Save the group access token somewhere safe. After you leave or refresh the page, you can't view it again. + +## Create a group access token using Rails console + +GitLab 14.6 and earlier doesn't support creating group access tokens using the UI +or API. However, administrators can use a workaround: + +1. Run the following commands in a [Rails console](../../../administration/operations/rails_console.md): + + ```ruby + # Set the GitLab administration user to use. If user ID 1 is not available or is not an administrator, use 'admin = User.admins.first' instead to select an administrator. + admin = User.find(1) + + # Set the group group you want to create a token for. For example, group with ID 109. + group = Group.find(109) + + # Create the group bot user. For further group access tokens, the username should be group_#{group.id}_bot#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com. + bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute + + # Confirm the group bot. + bot.confirm + + # Add the bot to the group with the required role. + group.add_user(bot, :maintainer) + + # Give the bot a personal access token. + token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') + + # Get the token value. + gtoken = token.token + ``` + +1. Test if the generated group access token works: + + 1. Use the group access token in the `PRIVATE-TOKEN` header with GitLab REST APIs. For example: + + - [Create an epic](../../../api/epics.md#new-epic) in the group. + - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) in one of the group's projects. + - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. + + 1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) + using HTTPS. + +## Revoke a group access token using the UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) in GitLab 14.7. + +To revoke a group access token: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Access Tokens**. +1. Next to the group access token to revoke, select **Revoke**. + +## Revoke a group access token using Rails console + +GitLab 14.6 and earlier doesn't support revoking group access tokens using the UI +or API. However, administrators can use a workaround. + +To revoke a group access token, run the following command in a [Rails console](../../../administration/operations/rails_console.md): + +```ruby +bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke +token = bot.personal_access_tokens.last # the token you want to revoke +token.revoke! +``` + +## Scopes for a group access token + +The scope determines the actions you can perform when you authenticate with a group access token. + +| Scope | Description | +|:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `api` | Grants complete read and write access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_api` | Grants read access to the scoped group and related project API, including the [Package Registry](../../packages/package_registry/index.md). | +| `read_registry` | Allows read access (pull) to the [Container Registry](../../packages/container_registry/index.md) images if any project within a group is private and authorization is required. | +| `write_registry` | Allows write access (push) to the [Container Registry](../../packages/container_registry/index.md). | +| `read_repository` | Allows read access (pull) to all repositories within a group. | +| `write_repository` | Allows read and write access (pull and push) to all repositories within a group. | + +## Enable or disable group access token creation + +To enable or disable group access token creation for all sub-groups in a top-level group: + +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Permissions and group features**. +1. Under **Permissions**, turn on or off **Allow project and group access token creation**. + +Even when creation is disabled, you can still use and revoke existing group access tokens. + +## Bot users + +Each time you create a group access token, a bot user is created and added to the group. +These bot users are similar to [project bot users](../../project/settings/project_access_tokens.md#project-bot-users), but are added to groups instead of projects. For more information, see +[Project bot users](../../project/settings/project_access_tokens.md#project-bot-users). diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index acce296da93..ef984a76a7d 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto, concepts --- @@ -101,7 +101,7 @@ You can change this setting: - As group owner: 1. Select the group. 1. On the left sidebar, select **Settings > General**. - 1. Expand **Permissions, LFS, 2FA**. + 1. Expand **Permissions and group features**. - As an administrator: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. diff --git a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png Binary files differdeleted file mode 100644 index 24d485306be..00000000000 --- a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v13_12.png +++ /dev/null diff --git a/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png Binary files differnew file mode 100644 index 00000000000..c9074cbb5ea --- /dev/null +++ b/doc/user/group/value_stream_analytics/img/vsa_stage_table_v14_7.png diff --git a/doc/user/group/value_stream_analytics/index.md b/doc/user/group/value_stream_analytics/index.md index b91e258b04a..4663cfc8bfd 100644 --- a/doc/user/group/value_stream_analytics/index.md +++ b/doc/user/group/value_stream_analytics/index.md @@ -5,34 +5,35 @@ 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)** +# Value stream analytics for groups **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196455) in GitLab 12.9 for groups. -Value Stream Analytics measures the time spent to go from an +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 +(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 +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). +For information on how to contribute to the development of value stream analytics, see our [contributor documentation](../../../development/value_stream_analytics.md). -To view group-level Value Stream Analytics: +To view value stream analytics for groups: 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Analytics > Value stream**. -Value Stream Analytics at the group level includes data for the selected group and its subgroups. +Value stream analytics at the group level includes data for the selected group and its subgroups. NOTE: -[Project-level Value Stream Analytics](../../analytics/value_stream_analytics.md) is also available. +[Value stream analytics for projects](../../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. +The stages tracked by value stream analytics by default represent the [GitLab flow](../../../topics/gitlab_flow.md). +These stages can be customized in value stream analytics for groups. - **Issue** (Tracker) - Time to schedule an issue (by milestone or by adding it to an issue board) @@ -100,8 +101,7 @@ sole discretion of GitLab Inc. ## How metrics are measured -> DORA API-based deployment metrics for group-level Value Stream Analytics were -> [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in 14.3. +> DORA API-based deployment metrics for value stream analytics for groups were [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/337256) from GitLab Ultimate to GitLab Premium in 14.3. The "Time" metrics near the top of the page are measured as follows: @@ -134,11 +134,11 @@ You can learn more about these metrics in our [analytics definitions](../../anal ## How the stages are measured -Value Stream Analytics measures each stage from its start event to its end event. +Value stream analytics measures each stage from its start event to its end event. For example, a stage might start when one label is added to an issue, and end when another label is added. -Value Stream Analytics excludes work in progress, meaning it ignores any items that have not reached the end event. +Value stream analytics excludes work in progress, meaning it ignores any items that have not reached the end event. -Each stage of Value Stream Analytics is further described in the table below. +Each stage of value stream analytics is further described in the table below. | **Stage** | **Description** | | --------- | --------------- | @@ -162,7 +162,7 @@ How this works, behind the scenes: and so on. To sum up, anything that doesn't follow [GitLab flow](../../../topics/gitlab_flow.md) is not tracked and the -Value Stream Analytics dashboard does not present any data for: +value stream analytics dashboard does 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. @@ -170,7 +170,7 @@ Value Stream Analytics dashboard does not present any data for: ## How the production environment is identified -Value Stream Analytics identifies production environments by looking for project +Value stream analytics identifies production environments by looking for project [environments](../../../ci/yaml/index.md#environment) with a name matching any of these patterns: - `prod` or `prod/*` @@ -228,7 +228,7 @@ A few notes: 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. + value stream analytics is showing. ## Custom value streams @@ -236,7 +236,7 @@ A few notes: 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. +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. @@ -272,7 +272,7 @@ Hovering over a stage item displays a popover with the following information: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321438) in GitLab 13.11. - + The stream overview provides access to key metrics and charts summarizing all the stages in the value stream based on selected filters. @@ -288,7 +288,7 @@ Shown metrics and charts includes: > Sorting the stage table [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/301082) in GitLab 13.12. - + The stage table shows a list of related workflow items for the selected stage. This can include: @@ -378,7 +378,7 @@ In this example, we'd like to measure times for deployment from a staging enviro - When the code is deployed to staging, the `workflow::staging` label is added to the merge request. - When the code is deployed to production, the `workflow::production` label is added to the merge request. - + ### Editing a value stream @@ -443,14 +443,14 @@ select up to a total of 15 labels. ## Permissions -To access Group-level Value Stream Analytics, users must have at least the Reporter role. +To access value stream analytics for groups, users must have at least the Reporter role. You can [read more about permissions](../../permissions.md) in general. ## More resources -Learn more about Value Stream Analytics in the following 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/). +- [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/infrastructure/clusters/manage/management_project_applications/cilium.md b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md index b5959624954..5d704a2c6df 100644 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md +++ b/doc/user/infrastructure/clusters/manage/management_project_applications/cilium.md @@ -37,7 +37,7 @@ You can check the recommended variables for each cluster type in the official do - [Google GKE](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-gke/#deploy-cilium) - [AWS EKS](https://docs.cilium.io/en/v1.8/gettingstarted/k8s-install-eks/#deploy-cilium) -Do not use `clusterType` for sandbox environments like [Minikube](https://minikube.sigs.k8s.io/docs/). +Do not use `clusterType` for sandbox environments like [minikube](https://minikube.sigs.k8s.io/docs/). You can customize Cilium's Helm variables by defining the `applications/cilium/values.yaml` file in your cluster diff --git a/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md new file mode 100644 index 00000000000..1dd1c760bcc --- /dev/null +++ b/doc/user/infrastructure/clusters/migrate_to_gitlab_agent.md @@ -0,0 +1,88 @@ +--- +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/#assignments +--- + +# Migrate to the GitLab Agent for Kubernetes **(FREE)** + +The first integration between GitLab and Kubernetes used cluster certificates +to connect the cluster to GitLab. +This method was [deprecated](https://about.gitlab.com/blog/2021/11/15/deprecating-the-cert-based-kubernetes-integration/) +in GitLab 14.5 in favor of the [GitLab Agent for Kubernetes](../../clusters/agent/index.md). + +To make sure your clusters connected to GitLab do not break in the future, +we recommend you migrate to the GitLab Agent as soon as possible by following +the processes described in this document. + +The certificate-based integration was used for some popular GitLab features such as, +GitLab Managed Apps, GitLab-managed clusters, and Auto DevOps. + +As a general rule, migrating clusters that rely on GitLab CI/CD can be +achieved using the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md) +provided by the Agent. + +NOTE: +The GitLab Agent for Kubernetes does not intend to provide feature parity with the +certificate-based cluster integrations. As a result, the Agent doesn't support +all the features available to clusters connected through certificates. + +## Migrate cluster application deployments + +### Migrate from GitLab-managed clusters + +With GitLab-managed clusters, GitLab creates separate service accounts and namespaces +for every branch and deploys using these resources. + +To achieve a similar result with the GitLab Agent, you can use [impersonation](../../clusters/agent/repository.md#use-impersonation-to-restrict-project-and-group-access) +strategies to deploy to your cluster with restricted account access. To do so: + +1. Choose the impersonation strategy that suits your needs. +1. Use Kubernetes RBAC rules to manage impersonated account permissions in Kubernetes. +1. Use the `access_as` attribute in your Agent’s configuration file to define the impersonation. + +### Migrate from Auto DevOps + +To configure your Auto DevOps project to use the GitLab Agent: + +1. Follow the steps to [install an agent](../../clusters/agent/install/index.md) on your cluster. +1. Go to the project in which you use Auto DevOps. +1. From the sidebar, select **Settings > CI/CD** and expand **Variables**. +1. Select **Add new variable**. +1. Add `KUBE_CONTEXT` as the key, `path/to/agent/project:agent-name` as the value, and select the environment scope of your choice. +1. Select **Add variable**. +1. Repeat the process to add another variable, `KUBE_NAMESPACE`, setting the value for the Kubernetes namespace you want your deployments to target, and set the same environment scope from the previous step. +1. From the sidebar, select **Infrastructure > Kubernetes clusters**. +1. From the certificate-based clusters section, open the cluster that serves the same environment scope. +1. Select the **Details** tab and disable the cluster. +1. To activate the changes, from the project's sidebar, select **CI/CD > Variables > Run pipeline**. + +### Migrate generic deployments + +When you use Kubernetes contexts to reach the cluster from GitLab, you can use the [CI/CD Tunnel](../../clusters/agent/ci_cd_tunnel.md) +directly. It injects the available contexts into your CI environment automatically: + +1. Follow the steps to [install an agent](../../clusters/agent/install/index.md) on your cluster. +1. Go to the project in which you use Auto DevOps. +1. From the sidebar, select **Settings > CI/CD** and expand **Variables**. +1. Select **Add new variable**. +1. Add `KUBE_CONTEXT` as the key, `path/to/agent-configuration-project:your-agent-name` as the value, and select the environment scope of your choice. +1. Edit your `.gitlab-ci.yml` file and set the Kubernetes context to the `KUBE_CONTEXT` you defined in the previous step: + + ```yaml + <your job name>: + script: + - kubectl config use-context $KUBE_CONTEXT + ``` + +## Migrate from GitLab Managed Applications + +Follow the process to [migrate from GitLab Managed Apps to the Cluster Management Project](../../clusters/migrating_from_gma_to_project_template.md). + +## Migrating a Cluster Management project + +See [how to use a cluster management project with the GitLab Agent](../../clusters/management_project_template.md#use-the-agent-with-the-cluster-management-project-template). + +## Migrate cluster monitoring features + +Cluster monitoring features are not supported by the GitLab Agent for Kubernetes yet. diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 15a680e2193..ceb6101688b 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -15,12 +15,14 @@ GitLab, and support Terraform best practices. ## Quick Start +> SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6. + Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration for GitLab versions 14.0 and later: ```yaml include: - - template: Terraform.gitlab-ci.yml + - template: Terraform.latest.gitlab-ci.yml variables: # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables @@ -30,15 +32,23 @@ variables: # TF_ROOT: terraform/production ``` -This template includes some opinionated decisions, which you can override: +This template includes the following parameters that you can override: -- Including the latest [GitLab Terraform Image](https://gitlab.com/gitlab-org/terraform-images). -- Using the [GitLab managed Terraform State](#gitlab-managed-terraform-state) as +- Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images). +- Uses the [GitLab-managed Terraform State](#gitlab-managed-terraform-state) as the Terraform state storage backend. -- Creating [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml): - `init`, `validate`, `build`, and `deploy`. These stages - [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) - `init`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch. +- Creates [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): + `test`, `validate`, `build`, and `deploy`. These stages + [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) + `test`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch. +- Runs the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually), + that you can disable by creating a `SAST_DISABLED` environment variable and setting it to `1`. + +The latest template described above might contain breaking changes between major GitLab releases. For users requiring more stable setups, we +recommend using the stable templates: + +- [A ready to use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) +- [A base template for customized setups](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) This video from January 2021 walks you through all the GitLab Terraform integration features: diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 1b3cd5d4478..3d640185a55 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,8 +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/#assignments" -type: reference, howto +info: To 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 Flavored Markdown **(FREE)** @@ -1507,56 +1506,3 @@ entry and paste the spreadsheet: at Daring Fireball is an excellent resource for a detailed explanation of standard Markdown. - You can find the detailed specification for CommonMark in the [CommonMark Spec](https://spec.commonmark.org/current/). - The [CommonMark Dingus](https://spec.commonmark.org/dingus/) helps you test CommonMark syntax. - -## Transition from Redcarpet to CommonMark - -- In GitLab 11.8, the [Redcarpet Ruby library](https://github.com/vmg/redcarpet) - was removed. All issues and comments, including those in 11.1 and earlier, are now processed - by using the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker). -- In GitLab 11.3 and later, CommonMark processes wiki pages and Markdown - files (`*.md`) in repositories. -- In GitLab 11.1 and later, the [CommonMark Ruby Library](https://github.com/gjtorikian/commonmarker) - for Markdown processes all new issues, merge requests, comments, and other Markdown - content. - -The documentation website migrated its Markdown engine -[from Redcarpet to Kramdown](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/108) -in October 2018. - -You may have older issues, merge requests, or Markdown documents in your -repository that relied upon nuances of the GitLab RedCarpet version -of Markdown. Because CommonMark uses slightly stricter syntax, these documents -may now appear differently after the transition to CommonMark. - -For example, numbered lists with nested lists may -render incorrectly: - -```markdown -1. Chocolate - - dark - - milk -``` - -To fix this issue, add a space to each nested item. The `-` must be aligned with the first -character of the top list item (`C` in this case): - -```markdown -1. Chocolate - - dark - - milk -``` - -1. Chocolate - - dark - - milk - -We flag any significant differences between Redcarpet and CommonMark Markdown in this document. - -If you have many Markdown files, it can be tedious to determine -if they display correctly or not. You can use the -[`diff_redcarpet_cmark`](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) -tool to generate a list of files and the -differences between how RedCarpet and CommonMark render the files. It indicates -if any changes are needed. - -`diff_redcarpet_cmark` is not an officially supported product. diff --git a/doc/user/operations_dashboard/index.md b/doc/user/operations_dashboard/index.md index 47c41e85345..20284328918 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -6,9 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Operations Dashboard **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5781) in GitLab 11.5. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/9218) from GitLab Ultimate to GitLab Premium in 11.10. - The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 9497dd1625b..c77fc5a0f4b 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -6,13 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Container Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4040) in GitLab 8.8. -> - Docker Registry manifest `v1` support was added in GitLab 8.9 to support Docker -> versions earlier than 1.10. -> - Starting in GitLab 8.12, if you have [two-factor authentication](../../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 to -> sign in to the Container Registry. -> - Support for multiple level image names was added in GitLab 9.1. > - 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. @@ -42,6 +35,21 @@ Only members of the project or group can access a private project's Container Re If a project is public, so is the Container Registry. +### View the tags of a specific image + +You can view a list of tags associated with a given container image: + +1. Go to your project or group. +1. Go to **Packages & Registries > Container Registry**. +1. Select the container image you are interested in. + +This brings up the Container Registry **Tag Details** page. You can view details about each tag, +such as when it was published, how much storage it consumes, and the manifest and configuration +digests. + +You can search, sort (by tag name), filter, and [delete](#delete-images-from-within-gitlab) +tags on this page. You can share a filtered view by copying the URL from your browser. + ## Use images from the Container Registry To download and run a container image hosted in the GitLab Container Registry: @@ -306,7 +314,7 @@ is set to `always`. To use your own Docker images for Docker-in-Docker, follow these steps in addition to the steps in the -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section: +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) section: 1. Update the `image` and `service` to point to your registry. 1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). @@ -336,7 +344,7 @@ error during connect: Get http://docker:2376/v1.39/info: dial tcp: lookup docker To use your own Docker images with Dependency Proxy, follow these steps in addition to the steps in the -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section: +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) section: 1. Update the `image` and `service` to point to your registry. 1. Add a service [alias](../../../ci/services/index.md#available-settings-for-services). @@ -475,256 +483,9 @@ defined in the `delete_image` job. ### Delete images by using a cleanup policy -You can create a per-project [cleanup policy](#cleanup-policy) to ensure older tags and images are regularly removed from the +You can create a per-project [cleanup policy](reduce_container_registry_storage.md#cleanup-policy) to ensure older tags and images are regularly removed from the Container Registry. -## Cleanup policy - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/218737) from "expiration policy" to "cleanup policy" in GitLab 13.2. - -The cleanup policy is a scheduled job you can use to remove tags from the Container Registry. -For the project where it's defined, tags matching the regex pattern are removed. -The underlying layers and images remain. - -To delete the underlying layers and images that aren't associated with any tags, administrators can use -[garbage collection](../../../administration/packages/container_registry.md#removing-untagged-manifests-and-unreferenced-layers) with the `-m` switch. - -### Enable the cleanup policy - -Cleanup policies can be run on all projects, with these exceptions: - -- For GitLab.com, the project must have been created after 2020-02-22. - Support for projects created earlier is tracked - [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/196124). -- For self-managed GitLab instances, the project must have been created - in GitLab 12.8 or later. However, an administrator can enable the cleanup policy - for all projects (even those created before 12.8) in - [GitLab application settings](../../../api/settings.md#change-application-settings) - by setting `container_expiration_policies_enable_historic_entries` to true. - Alternatively, you can execute the following command in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): - - ```ruby - ApplicationSetting.last.update(container_expiration_policies_enable_historic_entries: true) - ``` - - There are performance risks with enabling it for all projects, especially if you - are using an [external registry](index.md#use-with-external-container-registries). -- For self-managed GitLab instances, you can enable or disable the cleanup policy for a specific - project. - - To enable it: - - ```ruby - Feature.enable(:container_expiration_policies_historic_entry, Project.find(<project id>)) - ``` - - To disable it: - - ```ruby - Feature.disable(:container_expiration_policies_historic_entry, Project.find(<project id>)) - ``` - -WARNING: -For performance reasons, enabled cleanup policies are automatically disabled for projects on -GitLab.com that don't have a container image. - -### How the cleanup policy works - -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. -1. Excludes the tag named `latest` from the list. -1. Evaluates the `name_regex` (tags to expire), excluding non-matching names from the list. -1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). -1. Excludes any tags that do not have a manifest (not part of the options in the UI). -1. Orders the remaining tags by `created_date`. -1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain). -1. Excludes from the list the tags more recent than the `older_than` value (Expiration interval). -1. Finally, the remaining tags in the list are deleted from the Container Registry. - -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. - -WARNING: -GitLab self-managed installs support for third-party container registries that comply with the -[Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api/) -specification. However, this specification does not include a tag delete operation. Therefore, when -interacting with third-party container registries, GitLab uses a workaround to delete tags. See the -[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15737) -for more information. Due to possible implementation variations, this workaround is not guaranteed -to work with all third-party registries in the same predictable way. If you use the GitLab Container -Registry, this workaround is not required because we implemented a special tag delete operation. In -this case, you can expect cleanup policies to be consistent and predictable. - -### Create a cleanup policy - -You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI. - -To create a cleanup policy in the UI: - -1. For your project, go to **Settings > Packages & Registries**. -1. Expand the **Clean up image tags** section. -1. Complete the fields. - - | Field | Description | - |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| - | **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 **Save**. - -Depending on the interval you chose, the policy is scheduled to run. - -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: - - ```plaintext - .* - ``` - - This is the default value for the expiration regex. - -- Match tags that start with `v`: - - ```plaintext - v.+ - ``` - -- Match only the tag named `main`: - - ```plaintext - main - ``` - -- Match tags that are either named or start with `release`: - - ```plaintext - release.* - ``` - -- Match tags that either start with `v`, are named `main`, or begin with `release`: - - ```plaintext - (?:v.+|main|release.*) - ``` - -### Set cleanup limits to conserve resources - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/288812) in GitLab 13.9. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's enabled 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-cleanup-policy-limits). - -Cleanup policies are executed as a background process. This process is complex, and depending on the number of tags to delete, -the process can take time to finish. - -To prevent server resource starvation, the following application settings are available: - -- `container_registry_expiration_policies_worker_capacity`. The maximum number of cleanup workers running concurrently. This must be greater than `1`. - We recommend starting with a low number and increasing it after monitoring the resources used by the background workers. -- `container_registry_delete_tags_service_timeout`. The maximum time, in seconds, that the cleanup process can take to delete a batch of tags. -- `container_registry_cleanup_tags_service_max_list_size`. The maximum number of tags that can be deleted in a single execution. Additional tags must be deleted in another execution. - We recommend starting with a low number, like `100`, and increasing it after monitoring that container images are properly deleted. - -For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): - - ```ruby - ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) - ``` - -Alternatively, once the limits are [enabled](#enable-or-disable-cleanup-policy-limits), -they are available in the [administrator area](../../admin_area/index.md): - -1. On the top bar, select **Menu > Admin**. -1. Go to **Settings > CI/CD > Container Registry**. - -#### Enable or disable cleanup policy limits - -The cleanup policies limits are under development and not ready for production use. They are -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(:container_registry_expiration_policies_throttling) -``` - -To disable it: - -```ruby -Feature.disable(:container_registry_expiration_policies_throttling) -``` - -### Use the cleanup policy API - -You can set, update, and disable the cleanup policies using the GitLab API. - -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 `main` 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":".*-main"}}' \ - "https://gitlab.example.com/api/v4/projects/2" - ``` - -Valid values for `cadence` when using the API are: - -- `1d` (every day) -- `7d` (every week) -- `14d` (every two weeks) -- `1month` (every month) -- `3month` (every quarter) - -See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). - -### Use with external container registries - -When using an [external container registry](../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), -running a cleanup policy on a project may have some performance risks. -If a project runs a policy to remove thousands of tags -the GitLab background jobs may get backed up or fail completely. -It is recommended you only enable container cleanup -policies for projects that were created before GitLab 12.8 if you are confident the number of tags -being cleaned up is minimal. - -### Troubleshooting cleanup policies - -If you see the following message: - -"Something went wrong while updating the cleanup policy." - -Check the regex patterns to ensure they are valid. - -GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in the cleanup policy. You can test them with the [regex101 regex tester](https://regex101.com/). -View some common [regex pattern examples](#regex-pattern-examples). - ## Limitations - Moving or renaming existing Container Registry repositories is not supported @@ -844,7 +605,7 @@ There can be different reasons behind this: To fix this, there are two workarounds: - - If you are on GitLab 13.9 or later, you can [set limits for the cleanup policy](#set-cleanup-limits-to-conserve-resources). + - If you are on GitLab 13.9 or later, you can [set limits for the cleanup policy](reduce_container_registry_storage.md#set-cleanup-limits-to-conserve-resources). This limits the cleanup execution in time, and avoids the expired token error. - Extend the expiration delay of the Container Registry authentication tokens. This defaults to 5 @@ -869,14 +630,14 @@ these steps: If you have Rails console access, you can enter the following commands to retrieve a list of tags limited by date: - ```shell + ```shell output = File.open( "/tmp/list_o_tags.out","w" ) Project.find(<Project_id>).container_repositories.find(<container_repo_id>).tags.each do |tag| output << tag.name + "\n" if tag.created_at < 1.month.ago end;nil output.close ``` - + This set of commands creates a `/tmp/list_o_tags.out` file listing all tags with a `created_at` date of older than one month. 1. Remove from the `list_o_tags.out` file any tags that you want to keep. Here are some example @@ -963,3 +724,55 @@ Use your own URLs to complete the following steps: ``` Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/18383) for details. + +### Tags on S3 backend remain after successful deletion requests + +With S3 as your storage backend, tags may remain even though: + +- In the UI, you see that the tags are scheduled for deletion. +- In the API, you get an HTTP `200` response. +- The registry log shows a successful `Delete` request. + +An example `DELETE` request in the registry log: + +```shell +{"content_type":"","correlation_id":"01FQGNSKVMHQEAVE21KYTJN2P4","duration_ms":62,"host":"localhost:5000","level":"info","method":"DELETE","msg":"access","proto":"HTTP/1.1","referrer":"","remote_addr":"127.0.0.1:47498","remote_ip":"127.0.0.1","status":202,"system":"http","time":"2021-12-22T08:58:15Z","ttfb_ms":62,"uri":"/v2/<path to repo>/tags/reference/<tag_name>","user_agent":"GitLab/<version>","written_bytes":0} +``` + +There may be some errors not properly cached. Follow these steps to investigate further: + +1. In your configuration file, set the registry's log level to `debug`, and the S3 driver's log + level to `logdebugwithhttpbody`. For Omnibus, make these edits in the `gitlab.rb` file: + + ```shell + # Change the registry['log_level'] to debug + registry['log_level'] = 'debug' + + # Set log level for registry log from storage side + registry['storage'] = { + 's3' => { + 'bucket' => 'your-s3-bucket', + 'region' => 'your-s3-region' + }, + + 'loglevel' = "logdebugwithhttpbody" + } + ``` + + Then save and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Attempt to delete one or more tags using the GitLab UI or API. + +1. Inspect the registry logs and look for a response from S3. Although the response could be + `200 OK`, the body might have the error `AccessDenied`. This indicates a permission problem from + the S3 side. + +1. Ensure your S3 configuration has the `deleteObject` permisson scope. Here's an + [example role for an S3 bucket](../../../administration/object_storage.md#iam-permissions). + Once adjusted, trigger another tag deletion. You should be able to successfully delete tags. + +Follow [this issue](https://gitlab.com/gitlab-org/container-registry/-/issues/551) for details. diff --git a/doc/user/packages/container_registry/reduce_container_registry_storage.md b/doc/user/packages/container_registry/reduce_container_registry_storage.md new file mode 100644 index 00000000000..e2242a85b75 --- /dev/null +++ b/doc/user/packages/container_registry/reduce_container_registry_storage.md @@ -0,0 +1,272 @@ +--- +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 +--- + +# Reduce Container Registry Storage **(FREE)** + +Container registries become large over time without cleanup. When a large number of images or tags are added: + +- Fetching the list of available tags or images becomes slower. +- They take up a large amount of storage space on the server. + +We recommend deleting unnecessary images and tags, and setting up a [cleanup policy](#cleanup-policy) +to automatically manage your container registry usage. + +## Check Container Registry Storage Use + +The Usage Quotas page (**Settings > Usage Quotas > Storage**) displays storage usage for Packages, which includes Container Registry, +however, the storage is not being calculated. + +## Cleanup policy + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15398) in GitLab 12.8. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/218737) from "expiration policy" to "cleanup policy" in GitLab 13.2. + +The cleanup policy is a scheduled job you can use to remove tags from the Container Registry. +For the project where it's defined, tags matching the regex pattern are removed. +The underlying layers and images remain. + +To delete the underlying layers and images that aren't associated with any tags, administrators can use +[garbage collection](../../../administration/packages/container_registry.md#removing-untagged-manifests-and-unreferenced-layers) with the `-m` switch. + +### Enable the cleanup policy + +Cleanup policies can be run on all projects, with these exceptions: + +- For self-managed GitLab instances, the project must have been created + in GitLab 12.8 or later. However, an administrator can enable the cleanup policy + for all projects (even those created before 12.8) in + [GitLab application settings](../../../api/settings.md#change-application-settings) + by setting `container_expiration_policies_enable_historic_entries` to true. + Alternatively, you can execute the following command in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ApplicationSetting.last.update(container_expiration_policies_enable_historic_entries: true) + ``` + + There are performance risks with enabling it for all projects, especially if you + are using an [external registry](#use-with-external-container-registries). +- For self-managed GitLab instances, you can enable or disable the cleanup policy for a specific + project. + + To enable it: + + ```ruby + Feature.enable(:container_expiration_policies_historic_entry, Project.find(<project id>)) + ``` + + To disable it: + + ```ruby + Feature.disable(:container_expiration_policies_historic_entry, Project.find(<project id>)) + ``` + +WARNING: +For performance reasons, enabled cleanup policies are automatically disabled for projects on +GitLab.com that don't have a container image. + +### How the cleanup policy works + +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. +1. Excludes the tag named `latest` from the list. +1. Evaluates the `name_regex` (tags to expire), excluding non-matching names from the list. +1. Excludes from the list any tags matching the `name_regex_keep` value (tags to preserve). +1. Excludes any tags that do not have a manifest (not part of the options in the UI). +1. Orders the remaining tags by `created_date`. +1. Excludes from the list the N tags based on the `keep_n` value (Number of tags to retain). +1. Excludes from the list the tags more recent than the `older_than` value (Expiration interval). +1. Finally, the remaining tags in the list are deleted from the Container Registry. + +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. + +WARNING: +GitLab self-managed installs support for third-party container registries that comply with the +[Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api/) +specification. However, this specification does not include a tag delete operation. Therefore, when +interacting with third-party container registries, GitLab uses a workaround to delete tags. See the +[related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15737) +for more information. Due to possible implementation variations, this workaround is not guaranteed +to work with all third-party registries in the same predictable way. If you use the GitLab Container +Registry, this workaround is not required because we implemented a special tag delete operation. In +this case, you can expect cleanup policies to be consistent and predictable. + +### Create a cleanup policy + +You can create a cleanup policy in [the API](#use-the-cleanup-policy-api) or the UI. + +To create a cleanup policy in the UI: + +1. For your project, go to **Settings > Packages & Registries**. +1. Expand the **Clean up image tags** section. +1. Complete the fields. + + | Field | Description | + |---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| + | **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 **Save**. + +Depending on the interval you chose, the policy is scheduled to run. + +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: + + ```plaintext + .* + ``` + + This is the default value for the expiration regex. + +- Match tags that start with `v`: + + ```plaintext + v.+ + ``` + +- Match only the tag named `main`: + + ```plaintext + main + ``` + +- Match tags that are either named or start with `release`: + + ```plaintext + release.* + ``` + +- Match tags that either start with `v`, are named `main`, or begin with `release`: + + ```plaintext + (?:v.+|main|release.*) + ``` + +### Set cleanup limits to conserve resources + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/288812) in GitLab 13.9. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's enabled 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-cleanup-policy-limits). + +Cleanup policies are executed as a background process. This process is complex, and depending on the number of tags to delete, +the process can take time to finish. + +To prevent server resource starvation, the following application settings are available: + +- `container_registry_expiration_policies_worker_capacity`. The maximum number of cleanup workers running concurrently. This must be greater than `1`. + We recommend starting with a low number and increasing it after monitoring the resources used by the background workers. +- `container_registry_delete_tags_service_timeout`. The maximum time, in seconds, that the cleanup process can take to delete a batch of tags. +- `container_registry_cleanup_tags_service_max_list_size`. The maximum number of tags that can be deleted in a single execution. Additional tags must be deleted in another execution. + We recommend starting with a low number, like `100`, and increasing it after monitoring that container images are properly deleted. + +For self-managed instances, those settings can be updated in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + + ```ruby + ApplicationSetting.last.update(container_registry_expiration_policies_worker_capacity: 3) + ``` + +Alternatively, once the limits are [enabled](#enable-or-disable-cleanup-policy-limits), +they are available in the [administrator area](../../admin_area/index.md): + +1. On the top bar, select **Menu > Admin**. +1. Go to **Settings > CI/CD > Container Registry**. + +#### Enable or disable cleanup policy limits + +The cleanup policies limits are under development and not ready for production use. They are +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(:container_registry_expiration_policies_throttling) +``` + +To disable it: + +```ruby +Feature.disable(:container_registry_expiration_policies_throttling) +``` + +### Use the cleanup policy API + +You can set, update, and disable the cleanup policies using the GitLab API. + +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 `main` 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":".*-main"}}' \ + "https://gitlab.example.com/api/v4/projects/2" + ``` + +Valid values for `cadence` when using the API are: + +- `1d` (every day) +- `7d` (every week) +- `14d` (every two weeks) +- `1month` (every month) +- `3month` (every quarter) + +See the API documentation for further details: [Edit project](../../../api/projects.md#edit-project). + +### Use with external container registries + +When using an [external container registry](../../../administration/packages/container_registry.md#use-an-external-container-registry-with-gitlab-as-an-auth-endpoint), +running a cleanup policy on a project may have some performance risks. +If a project runs a policy to remove thousands of tags +the GitLab background jobs may get backed up or fail completely. +It is recommended you only enable container cleanup +policies for projects that were created before GitLab 12.8 if you are confident the number of tags +being cleaned up is minimal. + +## Related topics + +- [Delete images](index.md#delete-images) +- [Delete registry repository](../../../api/container_registry.md#delete-registry-repository) +- [Delete a registry repository tag](../../../api/container_registry.md#delete-a-registry-repository-tag) +- [Delete registry repository tags in bulk](../../../api/container_registry.md#delete-registry-repository-tags-in-bulk) +- [Delete a package](../package_registry/index.md#delete-a-package) + +## Troubleshooting cleanup policies + +If you see the following message: + +"Something went wrong while updating the cleanup policy." + +Check the regex patterns to ensure they are valid. + +GitLab uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax) for regular expressions in the cleanup policy. You can test them with the [regex101 regex tester](https://regex101.com/). +View some common [regex pattern examples](#regex-pattern-examples). diff --git a/doc/user/packages/debian_repository/index.md b/doc/user/packages/debian_repository/index.md index 89427174dcd..a8f0672e376 100644 --- a/doc/user/packages/debian_repository/index.md +++ b/doc/user/packages/debian_repository/index.md @@ -67,7 +67,7 @@ Creating a Debian package is documented [on the Debian Wiki](https://wiki.debian To create a distribution, publish a package, or install a private package, you need one of the following: -- [Personal access token](../../../api/index.md#personalproject-access-tokens) +- [Personal access token](../../../api/index.md#personalprojectgroup-access-tokens) - [CI/CD job token](../../../ci/jobs/ci_job_token.md) - [Deploy token](../../project/deploy_tokens/index.md) diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 8b34634318c..52f5a1fcc0d 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -6,7 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Proxy **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in GitLab 11.11. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11582) support for private groups in GitLab 13.7. > - Anonymous access to images in public groups is no longer available starting in GitLab 13.7. @@ -20,7 +19,8 @@ upstream image from a registry, acting as a pull-through cache. ## Prerequisites -- The Dependency Proxy is enabled by default but can be [turned off by an administrator](../../../administration/packages/dependency_proxy.md). +To use the Dependency Proxy, it must be enabled for the GitLab instance. It's enabled by default, +but [administrators can turn it off](../../../administration/packages/dependency_proxy.md). ### Supported images and packages @@ -33,13 +33,17 @@ 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). -## Enable or disable the Dependency Proxy for a group +## Enable or turn off the Dependency Proxy for a group -To enable or disable the Dependency Proxy for a group: +To enable or turn off the Dependency Proxy for a group: 1. Go to your group's **Settings > Packages & Registries**. 1. Expand the **Dependency Proxy** section. -1. To enable the proxy, turn on **Enable Proxy**. To disable it, turn the toggle off. +1. To enable the proxy, turn on **Enable Proxy**. To turn it off, turn the toggle off. + +This setting only affects the Dependency Proxy for a group. Only an administrator can +[turn the Dependency Proxy on or off](../../../administration/packages/dependency_proxy.md) +for the entire GitLab instance. ## View the Dependency Proxy @@ -227,7 +231,7 @@ You can enable an automatic time-to-live (TTL) policy for the Dependency Proxy f interface. To do this, navigate to your group's **Settings > Packages & Registries > Dependency Proxy** and enable the setting to automatically clear items from the cache after 90 days. -#### Enable cleanup policies with GraphQL +#### Enable cleanup policies with GraphQL > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294187) in GitLab 14.4. @@ -259,7 +263,7 @@ mutation { ``` See the [Getting started with GraphQL](../../../api/graphql/getting_started.md) -guide to learn how to make GraphQL queries. +guide to learn how to make GraphQL queries. When the policy is initially enabled, the default TTL setting is 90 days. Once enabled, stale dependency proxy files are queued for deletion each day. Deletion may not occur right away due to diff --git a/doc/user/packages/generic_packages/index.md b/doc/user/packages/generic_packages/index.md index 5b7316a495e..7b44b5bcbb7 100644 --- a/doc/user/packages/generic_packages/index.md +++ b/doc/user/packages/generic_packages/index.md @@ -13,20 +13,17 @@ 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). -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. ## Authenticate to the Package Registry -To authenticate to the Package Registry, you need either a [personal access token](../../../api/index.md#personalproject-access-tokens), +To authenticate to the Package Registry, you need either a [personal access token](../../../api/index.md#personalprojectgroup-access-tokens), [CI/CD job token](../../../ci/jobs/ci_job_token.md), or [deploy token](../../project/deploy_tokens/index.md). In addition to the standard API authentication mechanisms, the generic package API allows authentication with HTTP Basic authentication for use with tools that do not support the other available mechanisms. The `user-id` is not checked and -may be any value, and the `password` must be either a [personal access token](../../../api/index.md#personalproject-access-tokens), +may be any value, and the `password` must be either a [personal access token](../../../api/index.md#personalprojectgroup-access-tokens), a [CI/CD job token](../../../ci/jobs/ci_job_token.md), or a [deploy token](../../project/deploy_tokens/index.md). ## Publish a package file diff --git a/doc/user/packages/helm_repository/index.md b/doc/user/packages/helm_repository/index.md index 488345965f9..73298afc9cd 100644 --- a/doc/user/packages/helm_repository/index.md +++ b/doc/user/packages/helm_repository/index.md @@ -30,7 +30,7 @@ Read more in the Helm documentation about these topics: To authenticate to the Helm repository, you need either: -- A [personal access token](../../../api/index.md#personalproject-access-tokens) with the scope set to `api`. +- A [personal access token](../../../api/index.md#personalprojectgroup-access-tokens) with the scope set to `api`. - A [deploy token](../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 6646f18e6fe..21fecc16602 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Maven packages in the Package Repository **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in GitLab 11.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -418,8 +417,7 @@ repositories { ### Group-level Maven endpoint -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in GitLab 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the group-level endpoint for @@ -476,8 +474,7 @@ repositories { ### Instance-level Maven endpoint -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in GitLab 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. If you rely on many packages, it might be inefficient to include the `repository` section with a unique URL for each package. Instead, you can use the instance-level endpoint for diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 1086de1fa92..5338e546625 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # npm packages in the Package Registry **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in GitLab 11.7. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. Publish npm packages in your project's Package Registry. Then install the packages whenever you need to use them as a dependency. @@ -579,8 +578,6 @@ If you get this error, ensure that: by default, it's possible to [disable it](../package_registry/#disable-the-package-registry). - Your token is not expired and has appropriate permissions. - A package with the same name or version doesn't already exist within the given scope. -- Your NPM package name does not contain a dot `.`. This is a [known issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/10248) - in GitLab 11.9 and earlier. - The scoped packages URL includes a trailing slash: - Correct: `//gitlab.example.com/api/v4/packages/npm/` - Incorrect: `//gitlab.example.com/api/v4/packages/npm` diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 28e1571b4f8..3311b271126 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -32,6 +32,25 @@ When you view packages in a group: For information on how to create and upload a package, view the GitLab documentation for your package type. +## Authenticate with the registry + +Authentication depends on the package manager being used. For more information, see the docs on the +specific package format you want to use. + +For most package types, the following credential types are valid: + +- [Personal access token](../../profile/personal_access_tokens.md): + authenticates with your user permissions. Good for personal and local use of the package registry. +- [Project deploy token](../../project/deploy_tokens/index.md): + allows access to all packages in a project. Good for granting and revoking project access to many + users. +- [Group deploy token](../../project/deploy_tokens/index.md#group-deploy-token): + allows access to all packages in a group and its subgroups. Good for granting and revoking access + to a large number of packages to sets of users. +- [Job token](../../../ci/jobs/ci_job_token.md): + allows access to packages in the project running the job for the users running the pipeline. + Access to other external projects can be configured. + ## Use GitLab CI/CD to build packages You can use [GitLab CI/CD](../../../ci/index.md) to build packages. diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index b8dc071fc30..bb9f32d1144 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -15,7 +15,7 @@ as a Terraform module registry. To authenticate to the Terraform module registry, you need either: -- A [personal access token](../../../api/index.md#personalproject-access-tokens) with at least `read_api` rights. +- A [personal access token](../../../api/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). ## Publish a Terraform Module diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 4336c58b56c..36c49e39151 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -46,168 +46,169 @@ The following table lists project permissions available for each role: <!-- Keep this table sorted: By topic first, then by minimum role, then alphabetically. --> -| Action | Guest | Reporter | Developer | Maintainer | Owner | -|-------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|-------| -| [Analytics](analytics/index.md):<br>View issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | -| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | -| [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) **(ULTIMATE)** | | | | | ✓ | -| [CI/CD](../ci/index.md):<br>Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>View a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>View list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>View [environments](../ci/environments/index.md) | | ✓ | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Cancel and retry jobs | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Create new [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Stop [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | ✓ | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Manage CI/CD variables | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Manage job triggers | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Manage runners | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals-deprecated) | | | | ✓ | ✓ | -| [CI/CD](../ci/index.md):<br>Delete pipelines | | | | | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | -| [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Remove a container registry image | | | ✓ | ✓ | ✓ | -| [Container Registry](packages/container_registry/index.md):<br>Update container registry | | | ✓ | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | -| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [alerts](../operations/incident_management/alerts.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Assign an alert | ✓| ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [incident](../operations/incident_management/incidents.md) | ✓| ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Create [incident](../operations/incident_management/incidents.md) | (*17*) | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [on-call schedules](../operations/incident_management/oncall_schedules.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Participate in on-call rotation | ✓| ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | -| [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md)| | | | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Assign | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set weight | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Close / reopen | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Move issues (*15*) | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | -| [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Approve (*9*) | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Create (*18*) | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Manage merge approval rules (project settings) | | | | ✓ | ✓ | -| [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | -| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Pull package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Publish package | | | ✓ | ✓ | ✓ | -| [Package registry](packages/index.md):<br>Delete package | | | | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | -| [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*10*) | ✓ (*10*) | ✓ (*10*) | ✓ | ✓ | -| [Projects](project/index.md):<br>View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View Requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | -| [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*11*) | ✓ | ✓ | -| [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (14) | ✓ | -| [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** **(PREMIUM SAAS)** (*12*) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*8*) | ✓ (*8*) | -| [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | -| [Projects](project/index.md):<br>Administer project compliance frameworks | | | | | ✓ | -| [Projects](project/index.md):<br>Archive project | | | | | ✓ | -| [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | -| [Projects](project/index.md):<br>Delete project | | | | | ✓ | -| [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | -| [Projects](project/index.md):<br>Rename project | | | | | ✓ | -| [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*5*) | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Push to protected branches (*5*) | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | -| [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | -| [Repository](project/repository/index.md):<br>Force push to protected branches (*4*) | | | | | | -| [Repository](project/repository/index.md):<br>Remove protected branches (*4*) | | | | | | -| [Requirements Management](project/requirements/index.md):<br>Archive / reopen **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [Requirements Management](project/requirements/index.md):<br>Create / edit **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [Requirements Management](project/requirements/index.md):<br>Import / export **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Resolve vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Revert vulnerability to detected state **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | -| [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | -| [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | -| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | +| Action | Guest | Reporter | Developer | Maintainer | Owner | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------|-----------|------------|-------| +| [Analytics](analytics/index.md):<br>View issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [merge request analytics](analytics/merge_request_analytics.md) **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View value stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [CI/CD analytics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [code review analytics](analytics/code_review_analytics.md) **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| [Analytics](analytics/index.md):<br>View [repository analytics](analytics/repository_analytics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View licenses in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create and run [on-demand DAST scans](application_security/dast/index.md#on-demand-scans) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Manage [security policy](application_security/policies/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>View [threats list](application_security/threat_monitoring/index.md#threat-monitoring) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create a [CVE ID Request](application_security/cve_id_request.md) **(FREE SAAS)** | | | | ✓ | ✓ | +| [Application security](application_security/index.md):<br>Create or assign [security policy project](application_security/policies/index.md) **(ULTIMATE)** | | | | | ✓ | +| [CI/CD](../ci/index.md):<br>Download and browse job artifacts | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>View a job log | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>View list of jobs | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>View [environments](../ci/environments/index.md) | | ✓ | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Cancel and retry jobs | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Create new [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Run CI/CD pipeline against a protected branch | | | ✓ (*5*) | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Stop [environments](../ci/environments/index.md) | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>View a job with [debug logging](../ci/variables/index.md#debug-logging) | | | ✓ | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Manage CI/CD variables | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Manage job triggers | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Manage group runners | | | | | ✓ | +| [CI/CD](../ci/index.md):<br>Manage project runners | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Use [environment terminals](../ci/environments/index.md#web-terminals-deprecated) | | | | ✓ | ✓ | +| [CI/CD](../ci/index.md):<br>Delete pipelines | | | | | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>View [pod logs](project/clusters/kubernetes_pod_logs.md) | | | ✓ | ✓ | ✓ | +| [Clusters](infrastructure/clusters/index.md):<br>Manage clusters | | | | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Create, edit, delete cleanup policies | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Remove a container registry image | | | ✓ | ✓ | ✓ | +| [Container Registry](packages/container_registry/index.md):<br>Update container registry | | | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>View Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | +| [GitLab Pages](project/pages/index.md):<br>Remove GitLab Pages | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [alerts](../operations/incident_management/alerts.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Assign an alert | ✓| ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [incident](../operations/incident_management/incidents.md) | ✓| ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Create [incident](../operations/incident_management/incidents.md) | (*17*) | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [on-call schedules](../operations/incident_management/oncall_schedules.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Participate in on-call rotation | ✓| ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>View [escalation policies](../operations/incident_management/escalation_policies.md) | | ✓ | ✓ | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [on-call schedules](../operations/incident_management/oncall_schedules.md) | | | | ✓ | ✓ | +| [Incident Management](../operations/incident_management/index.md):<br>Manage [escalation policies](../operations/incident_management/escalation_policies.md) | | | | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Add Labels | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Assign | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Create [confidential issues](project/issues/confidential_issues.md) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [Design Management](project/issues/design_management.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View related issues | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set weight | ✓ (*16*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>View [confidential issues](project/issues/confidential_issues.md) | (*2*) | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Close / reopen | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Lock threads | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage related issues | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Manage tracker | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Move issues (*15*) | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Set issue [time tracking](project/time_tracking.md) estimate and time spent | | ✓ | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | +| [Issues](project/issues/index.md):<br>Delete | | | | | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View allowed and denied licenses **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License Compliance reports **(ULTIMATE)** | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>View License list **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [License Compliance](compliance/license_compliance/index.md):<br>Manage license policy **(ULTIMATE)** | | | | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign reviewer | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>See list | | ✓ | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Apply code change suggestions | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Approve (*9*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Assign | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Create (*18*) | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Add labels | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Lock threads | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Manage or accept | | | ✓ | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Manage merge approval rules (project settings) | | | | ✓ | ✓ | +| [Merge requests](project/merge_requests/index.md):<br>Delete | | | | | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | +| [Metrics dashboards](../operations/metrics/dashboards/index.md):<br>Create/edit/delete metrics dashboard annotations | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Pull package | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Publish package | | | ✓ | ✓ | ✓ | +| [Package registry](packages/index.md):<br>Delete package | | | | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>View [Error Tracking](../operations/error_tracking.md) list | | ✓ | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | | | ✓ | ✓ | ✓ | +| [Project operations](../operations/index.md):<br>Manage [Error Tracking](../operations/error_tracking.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Download project | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Leave comments | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Reposition comments on images (posted by any user) | ✓ (*10*) | ✓ (*10*) | ✓ (*10*) | ✓ | ✓ | +| [Projects](project/index.md):<br>View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [releases](project/releases/index.md) | ✓ (*6*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View Requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [time tracking](project/time_tracking.md) reports | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [wiki](project/wiki/index.md) pages | ✓ | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create [snippets](snippets.md) | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage labels | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View [project traffic statistics](../api/project_statistics.md) | | ✓ | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [milestones](project/milestones/index.md). | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Create, edit, delete [releases](project/releases/index.md) | | | ✓ (*13*) | ✓ (*13*) | ✓ (*13*) | +| [Projects](project/index.md):<br>Create, edit [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Enable Review Apps | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>View project [Audit Events](../administration/audit_events.md) | | | ✓ (*11*) | ✓ | ✓ | +| [Projects](project/index.md):<br>Add deploy keys | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Add new team members | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Change [project features visibility](../public_access/public_access.md) level | | | | ✓ (14) | ✓ | +| [Projects](project/index.md):<br>Configure [webhooks](project/integrations/webhooks.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Delete [wiki](project/wiki/index.md) pages | | | ✓ | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit comments (posted by any user) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project badges | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Edit project settings | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Export project | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [project access tokens](project/settings/project_access_tokens.md) **(FREE SELF)** **(PREMIUM SAAS)** (*12*) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Manage [Project Operations](../operations/index.md) | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Share (invite) projects with groups | | | | ✓ (*8*) | ✓ (*8*) | +| [Projects](project/index.md):<br>View 2FA status of members | | | | ✓ | ✓ | +| [Projects](project/index.md):<br>Administer project compliance frameworks | | | | | ✓ | +| [Projects](project/index.md):<br>Archive project | | | | | ✓ | +| [Projects](project/index.md):<br>Change project visibility level | | | | | ✓ | +| [Projects](project/index.md):<br>Delete project | | | | | ✓ | +| [Projects](project/index.md):<br>Disable notification emails | | | | | ✓ | +| [Projects](project/index.md):<br>Rename project | | | | | ✓ | +| [Projects](project/index.md):<br>Transfer project to another namespace | | | | | ✓ | +| [Repository](project/repository/index.md):<br>Pull project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View project code | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>View a commit status | | ✓ | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Add tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create new branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Create or update commit status | | | ✓ (*5*) | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Force push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove non-protected branches | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Rewrite or remove Git tags | | | ✓ | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable branch protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Enable or disable tag protection | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Manage [push rules](../push_rules/push_rules.md) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Push to protected branches (*5*) | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Turn on or off protected branch push for developers | | | | ✓ | ✓ | +| [Repository](project/repository/index.md):<br>Remove fork relationship | | | | | ✓ | +| [Repository](project/repository/index.md):<br>Force push to protected branches (*4*) | | | | | | +| [Repository](project/repository/index.md):<br>Remove protected branches (*4*) | | | | | | +| [Requirements Management](project/requirements/index.md):<br>Archive / reopen **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Create / edit **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Requirements Management](project/requirements/index.md):<br>Import / export **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View Security reports **(ULTIMATE)** | ✓ (*3*) | ✓ | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create issue from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Create vulnerability from vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Dismiss vulnerability finding **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Resolve vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Revert vulnerability to detected state **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>Use security dashboard **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Security dashboard](application_security/security_dashboard/index.md):<br>View vulnerability findings in [dependency list](application_security/dependency_list/index.md) **(ULTIMATE)** | | | ✓ | ✓ | ✓ | +| [Terraform](infrastructure/index.md):<br>Read Terraform state | | | ✓ | ✓ | ✓ | +| [Terraform](infrastructure/index.md):<br>Manage Terraform state | | | | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Archive | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Create | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Move | | ✓ | ✓ | ✓ | ✓ | +| [Test cases](../ci/test_cases/index.md):<br>Reopen | | ✓ | ✓ | ✓ | ✓ | 1. On self-managed GitLab instances, guest users are able to perform this action only on public and internal projects (not on private projects). [External users](#external-users) @@ -512,6 +513,7 @@ instance and project. | Change project configuration | | | ✓ | ✓ | | Add specific runners | | | ✓ | ✓ | | Add shared runners | | | | ✓ | +| Clear runner caches manually | | | ✓ | ✓ | | See events in the system | | | | ✓ | | Admin Area | | | | ✓ | diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index ab0cae976d2..32b8d2b33ee 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -1,7 +1,7 @@ --- type: reference stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 96415279de4..365f96b48b3 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,7 +1,7 @@ --- type: howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 343f8e328ba..3af8c1c1b5a 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,59 +1,51 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Two-factor authentication **(FREE)** -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 are prompted for a code generated by your one-time -password authenticator (for example, a password manager on one of your devices). +Two-factor authentication (2FA) provides an additional level of security to your GitLab account. For others to access +your account, they would need your username and password _and_ access to your second factor of authentication. -By enabling 2FA, the only way someone other than you can sign in to your account -is to know your username and password _and_ have access to your one-time -password secret. +GitLab supports as a second factor of authentication: -## Overview +- Time-based one-time passwords ([TOTP](https://datatracker.ietf.org/doc/html/rfc6238)). When enabled, GitLab prompts + you for a code when you sign in. Codes are generated by your one-time password authenticator (for example, a password + manager on one of your devices). +- U2F or WebAuthn devices. You're prompted to activate your U2F or WebAuthn device (usually by pressing a button on it) when + you supply your username and password to sign in. This performs secure authentication on your behalf. -NOTE: -When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)! +If you set up a device, also set up a TOTP so you can still access your account if you lose the device. -In addition to time-based one time passwords (TOTP), GitLab supports WebAuthn 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. +## Use personal access tokens with two-factor authentication -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. +When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/index.md). +You must use a [personal access token](../personal_access_tokens.md) instead. -## Enabling 2FA +## Enable two-factor authentication > - Account email confirmation requirement [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35102) in GitLab 14.3. [Deployed behind the `ensure_verified_primary_email_for_2fa` flag](../../../administration/feature_flags.md), enabled by default. > - Account email confirmation requirement generally available and [feature flag `ensure_verified_primary_email_for_2fa` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340151) in GitLab 14.4. -There are multiple ways to enable two-factor authentication (2FA): +You can enable 2FA: -- Using a one-time password authenticator. -- Using a U2F / WebAuthn device. +- Using a one-time password authenticator. After you enable 2FA, back up your [recovery codes](#recovery-codes). +- Using a U2F or WebAuthn device. -In GitLab 14.3 and later, your account email must be confirmed to enable two-factor authentication. +In GitLab 14.3 and later, your account email must be confirmed to enable 2FA. -### One-time password +### Enable one-time password -To enable 2FA: +To enable 2FA with a one-time password: 1. **In GitLab:** - 1. Sign in to your GitLab account. - 1. Go to your [**User settings**](../index.md#access-your-user-settings). - 1. Go to **Account**. + 1. Access your [**User settings**](../index.md#access-your-user-settings). + 1. Select **Account**. 1. Select **Enable Two-factor Authentication**. 1. **On your device (usually your phone):** - 1. Install a compatible application, like: + 1. Install a compatible application. For example: - [Authy](https://authy.com/) - [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) - [LastPass Authenticator](https://lastpass.com/auth/) @@ -63,37 +55,36 @@ To enable 2FA: - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app) - [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp) 1. In the application, add a new entry in one of two ways: - - Scan the code presented in GitLab with your device's camera to add the - entry automatically. + - Scan the code displayed by GitLab with your device's camera to add the entry automatically. - Enter the details provided to add the entry manually. 1. **In GitLab:** - 1. Enter the six-digit pin number from the entry on your device into the **Pin - code** field. + 1. Enter the six-digit pin number from the entry on your device into **Pin code**. 1. Enter your current password. 1. Select **Submit**. -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 +If you entered the correct pin, GitLab displays a list of [recovery codes](#recovery-codes). Download them and keep them in a safe place. -### One-time password via FortiAuthenticator +### Enable one-time password using FortiAuthenticator + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `forti_authenticator`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to +[enable the feature flag](../../../administration/feature_flags.md) named `forti_authenticator`. On GitLab.com, this +feature is not available. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) in GitLab 13.5. -> - It's deployed behind a feature flag, disabled by default. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-fortiauthenticator-integration). +You can use FortiAuthenticator as a one-time password (OTP) provider in GitLab. Users must: -You can use FortiAuthenticator as a one-time password (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. +- Exist in both FortiAuthenticator and GitLab with the same username. +- Have FortiToken configured in FortiAuthenticator. -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). +You need a username and access token for FortiAuthenticator. The `access_token` shown below is the FortAuthenticator +access key. To get the token, see the REST API Solution Guide at +[Fortinet Document Library](https://docs.fortinet.com/document/fortiauthenticator/6.2.0/rest-api-solution-guide/158294/the-fortiauthenticator-api). GitLab 13.5 has been tested with FortAuthenticator version 6.2.0. -First configure FortiAuthenticator in GitLab. On your GitLab server: +Configure FortiAuthenticator in GitLab. On your GitLab server: 1. Open the configuration file. @@ -134,43 +125,27 @@ First configure FortiAuthenticator in GitLab. On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - or [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source) - for the changes to take effect if you installed GitLab via Omnibus or from - source respectively. - -#### Enable FortiAuthenticator integration - -This feature comes with the `:forti_authenticator` feature flag disabled by -default. - -To enable this feature, ask a GitLab administrator with [Rails console access](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) -to run the following command: +1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or + [restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source). -```ruby -Feature.enable(:forti_authenticator, User.find(<user ID>)) -``` +### Enable one-time password using FortiToken Cloud -### One-time password via FortiToken Cloud +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212313) in GitLab 13.7 [with a flag](../../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212313) in GitLab 13.7. -> - 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). +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to +[enable the feature flag](../../../administration/feature_flags.md) named `forti_token_cloud`. On GitLab.com, this +feature is not available. The feature is not ready for production use. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +You can use FortiToken Cloud as a one-time password (OTP) provider in GitLab. Users must: -You can use FortiToken Cloud as a one-time password (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. +- Exist in both FortiToken Cloud and GitLab with the same username. +- 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/latest/rest-api). +You 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/latest/rest-api/456035/overview). -First configure FortiToken Cloud in GitLab. On your GitLab server: +Configure FortiToken Cloud in GitLab. On your GitLab server: 1. Open the configuration file. @@ -207,215 +182,184 @@ First configure FortiToken Cloud in GitLab. On your GitLab server: ``` 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: +1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or + [restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source). -```ruby -Feature.disable(:forti_token_cloud, User.find(<user ID>)) -``` +### Set up a U2F device -### U2F device +GitLab officially supports [YubiKey](https://www.yubico.com/products/) U2F devices, but users have successfully used +[SoloKeys](https://solokeys.com/) and [Google Titan Security Key](https://cloud.google.com/titan-security-key). -GitLab officially only supports [YubiKey](https://www.yubico.com/products/) -U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/) -or [Google Titan Security Key](https://cloud.google.com/titan-security-key). - -NOTE: -2FA must be configured before U2F. - -The U2F workflow is [supported by](https://caniuse.com/#search=U2F) the -following desktop browsers: +U2F is [supported by](https://caniuse.com/#search=U2F) the following desktop browsers: - Chrome - Edge -- Firefox 67+ - Opera +- Firefox 67+. For Firefox 47-66: -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`. + 1. Enable the FIDO U2F API in [`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). + 1. Search for `security.webauth.u2f` and select it to toggle to `true`. To set up 2FA with a U2F device: -1. Sign in to your GitLab account. -1. Go to your [**User settings**](../index.md#access-your-user-settings). -1. Go to **Account**. -1. Click **Enable Two-Factor Authentication**. +1. Access your [**User settings**](../index.md#access-your-user-settings). +1. Select **Account**. +1. Select **Enable Two-Factor Authentication**. 1. Connect your U2F device. -1. Click on **Set up New U2F Device**. +1. Select on **Set up New U2F Device**. 1. A light begins blinking on your device. Activate it by pressing its button. -A message displays, indicating that your device was successfully set up. -Click on **Register U2F Device** to complete the process. +A message displays indicating that your device was successfully set up. Select **Register U2F Device** to complete the +process. Recovery codes are not generated for U2F devices. -### WebAuthn device +### Set up a WebAuthn device > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `webauthn`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/232671) in GitLab 14.6. FLAG: -On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `webauthn`. If you disable the WebAuthn feature flag after WebAuthn devices have been registered, these devices are not usable until you re-enable this feature. On GitLab.com, this feature is available. - -The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the -following desktop browsers: - -- Chrome -- Edge -- Firefox -- Opera -- Safari - -and the following mobile browsers: - -- Chrome for Android -- Firefox for Android -- iOS Safari (since iOS 13.3) - -To set up 2FA with a WebAuthn compatible device: - -1. Sign in to your GitLab account. -1. Go to your [**User settings**](../index.md#access-your-user-settings). -1. Go to **Account**. +On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to +[disable the feature flag](../../../administration/feature_flags.md) named `webauthn`. If you disable the WebAuthn +feature flag after WebAuthn devices have been registered, these devices are not usable until you re-enable this feature. +On GitLab.com, this feature is available. + +WebAuthn [supported by](https://caniuse.com/#search=webauthn): + +- The following desktop browsers: + - Chrome + - Edge + - Firefox + - Opera + - Safari +- The following mobile browsers: + - Chrome for Android + - Firefox for Android + - iOS Safari (since iOS 13.3) + +To set up 2FA with a WebAuthn-compatible device: + +1. Access your [**User settings**](../index.md#access-your-user-settings). +1. Select **Account**. 1. Select **Enable Two-Factor Authentication**. 1. Plug in your WebAuthn device. 1. Select **Set up New WebAuthn Device**. -1. Depending on your device, you might need to press a button or touch a sensor. +1. Depending on your device, you might have to press a button or touch a sensor. -A message displays, indicating that your device was successfully set up. -Recovery codes are not generated for WebAuthn devices. +A message displays indicating that your device was successfully set up. Recovery codes are not generated for WebAuthn +devices. ## Recovery codes -NOTE: -Recovery codes are not generated for U2F / WebAuthn devices. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267730) in GitLab 13.7, **Copy codes** and **Print codes** buttons. + +Immediately after successfully enabling 2FA with a one-time password, you're prompted to download +a set of generated recovery codes. If you ever lose access to your one-time password authenticator, you can use one of +these recovery codes to sign in to your account. WARNING: Each code can be used only once to sign in to your account. -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 sign 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 is called `gitlab-recovery-codes.txt`. +We recommend 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 is called `gitlab-recovery-codes.txt`. + +NOTE: +Recovery codes are not generated for U2F or WebAuthn devices. + +If you lose the recovery codes, or want to generate new ones, you can use either: + +- The [2FA account settings](#regenerate-two-factor-authentication-recovery-codes) page. +- [SSH](#generate-new-recovery-codes-using-ssh). + +### Regenerate two-factor authentication recovery codes -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. +To regenerate 2FA recovery codes, you need access to a desktop browser: -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 -[using SSH](#generate-new-recovery-codes-using-ssh). +1. Access your [**User settings**](../index.md#access-your-user-settings). +1. Select **Account > Two-Factor Authentication (2FA)**. +1. If you've already configured 2FA, select **Manage two-factor authentication**. +1. In the **Register Two-Factor Authenticator** pane, enter your current password and select **Regenerate recovery codes**. -## Signing in with 2FA Enabled +NOTE: +If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. + +## Sign in with two-factor authentication enabled -Signing in with 2FA enabled is only slightly different than the normal sign-in process. -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. +Signing in with 2FA enabled is only slightly different than the normal sign-in process. Enter your username and password +and you're presented with a second prompt, depending on which type of 2FA you've enabled. -### Sign in by using a one-time password +### Sign in using a one-time password -When asked, enter the pin from your one time password authenticator's application or a -recovery code to sign in. +When asked, enter the pin from your one time password authenticator's application or a recovery code to sign in. -### Sign in by using a U2F device +### Sign in using a U2F device To sign in by using a U2F device: -1. Click **Login via U2F Device**. +1. Select **Login via U2F Device**. 1. A light begins blinking on your device. Activate it by touching/pressing its button. -A message displays, indicating that your device responded to the authentication -request, and you're automatically signed in. +A message displays indicating that your device responded to the authentication request, and you're automatically signed +in. -### Sign in by using a WebAuthn device +### Sign in using a WebAuthn device -In supported browsers you should be automatically prompted to activate your WebAuthn device -(for example, by touching or pressing its button) after entering your credentials. +In supported browsers, you should be automatically prompted to activate your WebAuthn device (for example, by touching +or pressing its button) after entering your credentials. -A message displays, indicating that your device responded to the authentication -request and you're automatically signed in. +A message displays indicating that your device responded to the authentication request and you're automatically signed +in. -## Disabling 2FA +## Disable two-factor authentication -If you ever need to disable 2FA: +To disable 2FA: -1. Sign in to your GitLab account. -1. Go to your [**User settings**](../index.md#access-your-user-settings). -1. Go to **Account**. +1. Access your [**User settings**](../index.md#access-your-user-settings). +1. Select **Account**. 1. Select **Manage two-factor authentication**. -1. Under **Two-Factor Authentication**, enter your current password and select **Disable**. - -This clears all your two-factor authentication registrations, including mobile -applications and U2F / WebAuthn devices. +1. Under **Register Two-Factor Authenticator**, enter your current password and select **Disable two-factor + authentication**. -Support for disabling 2FA is limited, depending on your subscription level. For more information, see the -[Account Recovery](https://about.gitlab.com/support/#account-recovery) section of our website. +This clears all your 2FA registrations, including mobile applications and U2F or 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 -the [GitLab API](../../../api/index.md). You must use a -[personal access token](../personal_access_tokens.md) instead. +Support Team support for disabling 2FA is limited, depending on your subscription level. For more information, see the +[Account Recovery](https://about.gitlab.com/support/#account-recovery-and-2fa-resets) section of our website. ## Recovery options -To disable two-factor authentication on your account (for example, if you -have lost your code generation device) you can: +If you don't have access to your code generation device, you can recover access to your account: -- [Use a saved recovery code](#use-a-saved-recovery-code). -- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh). -- [Regenerate 2FA recovery codes](#regenerate-2fa-recovery-codes). -- [Have 2FA disabled on your account](#have-2fa-disabled-on-your-account). +- [Use a saved recovery code](#use-a-saved-recovery-code), if you saved them when you enabled two-factor + authentication. +- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh), if you didn't save your original + recovery codes but have an SSH key. +- [Have 2FA disabled on your account](#have-two-factor-authentication-disabled-on-your-account), if you don't have your + recovery codes or an SSH key. ### Use a saved recovery code -Enabling two-factor authentication for your account generated several recovery -codes. If you saved these codes, you can use one of them to sign in. +To use a recovery code: -To use a recovery code, enter your username/email and password on the GitLab -sign-in page. When prompted for a two-factor code, enter the recovery code. +1. Enter your username or email, and password, on the GitLab sign-in page. +1. When prompted for a two-factor code, enter the recovery code. -After you use a recovery code, you cannot re-use it. You can still use the other -recovery codes you saved. +After you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved. ### Generate new recovery codes using SSH -Users often forget to save their recovery codes when enabling two-factor -authentication. If an SSH key is added to your GitLab account, you can generate -a new set of recovery codes with SSH: +Users often forget to save their recovery codes when enabling 2FA. If you added an SSH key to your +GitLab account, you can generate a new set of recovery codes with SSH: -1. Run: +1. In a terminal, run: ```shell ssh git@gitlab.com 2fa_recovery_codes ``` - NOTE: - On self-managed instances, replace **`gitlab.com`** in the command above - with the GitLab server hostname (`gitlab.example.com`). + On self-managed instances, replace **`gitlab.com`** in the command above with the GitLab server hostname (`gitlab.example.com`). -1. You are prompted to confirm that you want to generate new codes. - Continuing this process invalidates previously saved codes: +1. You are prompted to confirm that you want to generate new codes. This process invalidates previously-saved codes. For + example: ```shell Are you sure you want to generate new two-factor recovery codes? @@ -441,49 +385,30 @@ a new set of recovery codes with SSH: so you do not lose access to your account again. ``` -1. Go to the GitLab sign-in page and enter your username/email and password. - When prompted for a two-factor code, enter one of the recovery codes obtained - from the command-line output. - -After signing in, visit your **User settings > Account** immediately to set -up two-factor authentication with a new device. - -### Regenerate 2FA recovery codes - -To regenerate 2FA recovery codes, you need access to a desktop browser: - -1. Navigate to GitLab. -1. Sign in to your GitLab account. -1. Go to your [**User settings**](../index.md#access-your-user-settings). -1. Select **Account > Two-Factor Authentication (2FA)**. -1. If you've already configured 2FA, click **Manage two-factor authentication**. -1. In the **Register Two-Factor Authenticator** pane, enter your current password and select **Regenerate recovery codes**. +1. Go to the GitLab sign-in page and enter your username or email, and password. When prompted for a two-factor code, + enter one of the recovery codes obtained from the command-line output. -NOTE: -If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. +After signing in, immediately set up 2FA with a new device. -### Have 2FA disabled on your account +### Have two-factor authentication disabled on your account **(PREMIUM SAAS)** -If you can't use a saved recovery code or generate new recovery codes, submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) to -request a GitLab global administrator disable two-factor authentication for your account. Note that: +If other methods are unavailable, submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) to request +a GitLab global administrator disable 2FA for your account: - Only the owner of the account can make this request. - This service is only available for accounts that have a GitLab.com subscription. For more information, see our [blog post](https://about.gitlab.com/blog/2020/08/04/gitlab-support-no-longer-processing-mfa-resets-for-free-users/). -- Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor authentication - as soon as possible. +- Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor + authentication as soon as possible. -## Note to GitLab administrators +## Information for GitLab administrators **(FREE SELF)** -- You need to take special care to that 2FA keeps working after - [restoring a GitLab backup](../../../raketasks/backup_restore.md). -- To ensure 2FA authorizes correctly with time-based one time passwords (TOTP) server, you may want to ensure - your GitLab server's time is synchronized via a service like NTP. Otherwise, - you may have cases where authorization always fails because of time differences. -- The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from - multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at - the time of registration, and cannot be used for other hostnames/FQDNs. The same applies to - WebAuthn registrations. +- Take care that 2FA keeps working after [restoring a GitLab backup](../../../raketasks/backup_restore.md). +- To ensure 2FA authorizes correctly with a time-based one time passwords (TOTP) server, synchronize your GitLab + server's time using a service like NTP. Otherwise, authorization can always fail because of time differences. +- The GitLab U2F and WebAuthn implementation does _not_ work when the GitLab instance is accessed from multiple hostnames + or FQDNs. Each U2F or WebAuthn registration is linked to the _current hostname_ at the time of registration, and + cannot be used for other hostnames or FQDNs. For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`: @@ -492,13 +417,13 @@ request a GitLab global administrator disable two-factor authentication for your - The user signs out and attempts to sign in by using `second.host.xyz` - U2F authentication fails, because the U2F key has only been registered on `first.host.xyz`. -- To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md). +- To enforce 2FA at the system or group levels see, [Enforce two-factor authentication](../../../security/two_factor_authentication.md). ## Troubleshooting -If you are receiving an `invalid pin code` error, this may indicate that there is a time sync issue between the authentication application and the GitLab instance itself. - -To avoid the time sync issue, enable time synchronization in the device that generates the codes. For example: +If you receive an `invalid pin code` error, this can indicate that there is a time sync issue between the authentication +application and the GitLab instance itself. To avoid the time sync issue, enable time synchronization in the device that +generates the codes. For example: - For Android (Google Authenticator): 1. Go to the Main Menu in Google Authenticator. @@ -510,15 +435,3 @@ To avoid the time sync issue, enable time synchronization in the device that gen 1. Select General. 1. Select Date & Time. 1. Enable Set Automatically. If it's already enabled, disable it, wait a few seconds, and re-enable. - -<!-- ## 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. - -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. --> diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index 90cb6502bbd..89e4ea6ea5b 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -1,7 +1,7 @@ --- type: index, howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index ea66f3e508f..45cff326332 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -1,7 +1,7 @@ --- type: concepts, howto stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -14,7 +14,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Personal access tokens can be an alternative to [OAuth2](../../api/oauth2.md) and used to: -- Authenticate with the [GitLab API](../../api/index.md#personalproject-access-tokens). +- Authenticate with the [GitLab API](../../api/index.md#personalprojectgroup-access-tokens). - Authenticate with Git using HTTP Basic Authentication. In both cases, you authenticate with a personal access token in place of your password. @@ -33,7 +33,7 @@ Though required, GitLab usernames are ignored when authenticating with a persona There is an [issue for tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/212953) to make GitLab use the username. -For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/index.md#personalproject-access-tokens). +For examples of how you can use a personal access token to authenticate with the API, see the [API documentation](../../api/index.md#personalprojectgroup-access-tokens). Alternately, GitLab administrators can use the API to create [impersonation tokens](../../api/index.md#impersonation-tokens). Use impersonation tokens to automate authentication as a specific user. diff --git a/doc/user/profile/unknown_sign_in_notification.md b/doc/user/profile/unknown_sign_in_notification.md index be86db3daf5..0ed2a11d363 100644 --- a/doc/user/profile/unknown_sign_in_notification.md +++ b/doc/user/profile/unknown_sign_in_notification.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index 9ca11d43864..79d395d51c3 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Badges **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41174) in GitLab 10.7. - Badges are a unified way to present condensed pieces of information about your projects. They consist of a small image and a URL that the image points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge), @@ -87,7 +84,7 @@ Badges directly associated with a project can be configured on the ## Placeholders -The URL a badge points to, as well as the image URL, can contain placeholders +Both the URL a badge points to and the image URL can contain placeholders which are evaluated when displaying the badge. The following placeholders are available: diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index ccf90a3d3dd..cf571abbf8a 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -394,6 +394,8 @@ stages: production: stage: deploy before_script: + - apt-get update + - apt-get install -y python3-pip - pip3 install awscli --upgrade - pip3 install aws-sam-cli --upgrade script: diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index a95e4d2bc26..4068d8e056c 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -1,19 +1,12 @@ --- 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/#assignments" -type: reference +info: To 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 Owners **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3. -> - Code Owners for merge request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9. -> - Moved to GitLab Premium in 13.9. - -INFO: -Get access to Code Owners and more with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-code-owners-docs). +> Moved to GitLab Premium in 13.9. Code Owners define who owns specific files or directories in a repository. @@ -283,3 +276,26 @@ model/db @database [DOCUMENTATION] README.md @docs ``` + +## Troubleshooting + +### Approvals shown as optional + +A Code Owner approval rule is optional if these conditions are not met: + +- The user or group are not a member of the project or parent group. +- [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up. +- The section is [marked as optional](#make-a-code-owners-section-optional). + +### Approvals do not show + +Code Owner approval rules only update when the merge request is created. +If you update the `CODEOWNERS` file, close the merge request and create a new one. + +### User not shown as possible approver + +A user might not show as an approver on the Code Owner merge request approval rules. + +This result occurs when a rule prevents the specific user from approving the merge request. +Check the project +[merge request approval setting](merge_requests/approvals/settings.md#edit-merge-request-approval-settings). diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index c5950347ae9..2e876b24b53 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: howto, reference --- -# Deploy keys +# Deploy keys **(FREE)** Deploy keys allow read-only or read-write access to your repositories by importing an SSH public key into your GitLab instance. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index c840f6c8698..f57fa5aa57d 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -4,12 +4,12 @@ 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 +# Deploy tokens **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** in GitLab 12.9. -> - [Added `write_registry` scope](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** in GitLab 12.10.1. -> - [Added package registry scopes](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in GitLab 13.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199370) from **Settings > Repository** to **Settings > CI/CD** in GitLab 12.9. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/22743) `write_registry` scope in GitLab 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29280) from **Settings > CI/CD** to **Settings > Repository** in GitLab 12.10.1. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) package registry scopes in GitLab 13.0. Deploy tokens allow you to download (`git clone`) or push and pull packages and container registry images of a project without having a user and a password. diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 66e5931fa4c..6c17964f3a5 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -6,73 +6,42 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Description templates **(FREE)** -We all know that a properly submitted issue is more likely to be addressed in -a timely manner by the developers of a project. +You can define templates to use as descriptions +for your [issues](issues/index.md) and [merge requests](merge_requests/index.md). -With description templates, you can define context-specific templates for issue and merge request -description fields for your project, and filter out unnecessary noise from issues. +You can define these templates in a project, group, or instance. Projects +inherit the templates defined at a higher level. -By using the description templates, users that create a new issue or merge -request can select a description template to help them communicate with other -contributors effectively. +You might want to use these templates: -Every GitLab project can define its own set of description templates as they -are added to the root directory of a GitLab project's repository. +- For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report. +- For every issue or merge request for a specific project, so the layout is consistent. +- For a [Service Desk email template](service_desk.md#new-service-desk-issues). -Description templates must be written in [Markdown](../markdown.md) and stored -in your project's repository in the `.gitlab` directory. Only the -templates of the default branch are taken into account. +For description templates to work, they must be: -To learn how to create templates for various file types in groups, visit -[Group file templates](../group/index.md#group-file-templates). - -## Use cases - -These are some situations when you might find description templates useful: - -- You can create issues and merge request templates for different - stages of your workflow, for example, feature proposal, feature improvement, or a bug report. -- Add a template to be used in every issue for a specific project, - giving instructions and guidelines, requiring for information specific to that subject. - For example, if you have a project for tracking new blog posts, you can require the - title, outlines, author name, and author social media information. -- Following the previous example, you can make a template for every MR submitted - with a new blog post, requiring information about the post date, front matter data, - images guidelines, link to the related issue, reviewer name, and so on. -- You can also create issues and merge request templates for different - stages of your workflow, for example, feature proposal, feature improvement, or a bug report. -- You can use an [issue description template](#create-an-issue-template) as a - [Service Desk email template](service_desk.md#new-service-desk-issues). +- Saved with the `.md` extension. +- Stored in your project's repository in the `.gitlab/issue_templates` + or `.gitlab/merge_request_templates` directory. +- Be present on the default branch. ## Create an issue template Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/` -directory in your repository. Commit and push to your default branch. +directory in your repository. -To create a Markdown file: +To create an issue description template: -1. In a project, go to **Repository**. -1. Next to the default branch, select the **{plus}** button. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository**. +1. Next to the default branch, select **{plus}**. 1. Select **New file**. -1. Next to the default branch, in the **File name** field, add the name of your issue template. - Make sure that your file has the `.md` extension, for - 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 need to create it. - -To create the `.gitlab/issue_templates` directory: - -1. In a project, go to **Repository**. -1. Next to the default branch, select the **{plus}** button. -1. Select **New directory**. -1. Name this new directory `.gitlab` and commit to your default branch. -1. Next to the default branch, select the **{plus}** button. -1. Select **New directory**. -1. Name your directory `issue_templates` and commit to your default branch. +1. Next to the default branch, in the **File name** text box, enter `.gitlab/issue_templates/mytemplate.md`, + where `mytemplate` is the name of your issue template. +1. Commit to your default branch. To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-an-issue) -and see if you can choose a description template. +and see if you can find your description template in the **Choose a template** dropdown list. ## Create a merge request template @@ -80,51 +49,48 @@ Similarly to issue templates, create a new Markdown (`.md`) file inside the `.gitlab/merge_request_templates/` directory in your repository. Commit and push to your default branch. -## Use the templates - -Let's take for example that you've created the file `.gitlab/issue_templates/Bug.md`. -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. +To create a merge request description template: -NOTE: -You can create shortcut links to create an issue using a designated template. -For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Repository**. +1. Next to the default branch, select **{plus}**. +1. Select **New file**. +1. Next to the default branch, in the **File name** text box, enter `.gitlab/merge_request_templates/mytemplate.md`, + where `mytemplate` is the name of your merge request template. +1. Commit to your default branch. - +To check if this has worked correctly, [create a new merge request](merge_requests/creating_merge_requests.md) +and see if you can find your description template in the **Choose a template** dropdown list. -You can set description templates at various levels: +## Use the templates -- The entire [instance](#set-instance-level-description-templates) -- A specific [group or subgroup](#set-group-level-description-templates) -- A specific [project](#set-a-default-template-for-merge-requests-and-issues) +When you create or edit an issue or a merge request, it shows in the **Choose a template** dropdown list. -The templates are inherited. For example, in a project, you can also access templates set for the -instance or the project's parent groups. +To apply a template: -### Set instance-level description templates **(PREMIUM SELF)** +1. Create or edit an issue or a merge request. +1. Select the **Choose a template** dropdown list. +1. If the **Description** text box hasn't been empty, to confirm, select **Apply template**. +1. Select **Save changes**. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0. +When you select a description template, its content is copied to the description text box. -You can set a description template at the **instance level** for issues -and merge requests. -As a result, these templates are available in all projects within the instance. +To discard any changes to the description you've made after selecting the template: expand the **Choose a template** dropdown list and select **Reset template**. -Only instance administrators can set instance-level templates. + -To set the instance-level description template repository: +NOTE: +You can create shortcut links to create an issue using a designated template. +For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. Read more about [creating issues using a URL with prefilled values](issues/managing_issues.md#using-a-url-with-prefilled-values). -1. On the top bar, select **Menu > Admin**. -1. On the left sidebar, select **Settings > Templates**. -1. Expand **Templates** -1. From the dropdown, select your template project as the template repository at instance level. -1. Select **Save changes**. +### Set instance-level description templates **(PREMIUM SELF)** - +You can set a description template at the **instance level** for issues +and merge requests by using an [instance template repository](../admin_area/settings/instance_template_repository.md). +You can also use the instance template repository for file templates. -Learn more about [instance template repository](../admin_area/settings/instance_template_repository.md). +You might also be interested [project templates](../admin_area/custom_project_templates.md) +that you can use when creating a new project in the instance. ### Set group-level description templates **(PREMIUM)** @@ -137,23 +103,27 @@ As a result, you can use the same templates in issues and merge requests in all To re-use templates [you've created](../project/description_templates.md#create-an-issue-template): -1. Go to the group's **Settings > General > Templates**. -1. From the dropdown, select your template project as the template repository at group level. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > General**. +1. Expand **Templates**. +1. From the dropdown list, select your template project as the template repository at group level. 1. Select **Save changes**.  +You might also be interested in templates for various +[file types in groups](../group/index.md#group-file-templates). + ### Set a default template for merge requests and issues **(PREMIUM)** In a project, you can choose a default description template for new issues and merge requests. As a result, every time a new merge request or issue is created, it's pre-filled with the text you entered in the template. -The visibility of issues 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 don't show. This is the default behavior, so in most cases -you should be fine. +Prerequisites: + +- On your project's left sidebar, select **Settings > General** and expand **Visibility, project features, permissions**. + Ensure issues or merge requests are set to either **Everyone with access** or **Only Project Members**. To set a default description template for merge requests: @@ -170,11 +140,10 @@ To set a default description template for issues: Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format headings, lists, and so on. -[GitLab versions 13.10 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/885) -provide `issues_template` and `merge_requests_template` attributes in the -[Projects API](../../api/projects.md) to help you keep your templates up to date. +You can also provide `issues_template` and `merge_requests_template` attributes in the +[Projects REST API](../../api/projects.md) to keep your default issue and merge request templates up to date. -## Description template example +## Example description template We use description templates for issues and merge requests in the [`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/-/tree/master/.gitlab) of the diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 10dcbddac17..1d06b605aa9 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -2,7 +2,6 @@ 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/#assignments -type: reference, howto --- # File Locking **(FREE)** @@ -43,8 +42,6 @@ locked by Administrator`. ## Exclusive file locks **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35856) in GitLab 10.5. - This process allows you to lock single files or file extensions and it is done through the command line. It doesn't require GitLab paid subscriptions. diff --git a/doc/user/project/img/description_templates.png b/doc/user/project/img/description_templates.png Binary files differdeleted file mode 100644 index e9d45029532..00000000000 --- a/doc/user/project/img/description_templates.png +++ /dev/null diff --git a/doc/user/project/img/description_templates_v14_7.png b/doc/user/project/img/description_templates_v14_7.png Binary files differnew file mode 100644 index 00000000000..acb1b9f79d9 --- /dev/null +++ b/doc/user/project/img/description_templates_v14_7.png diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index 81e7d159a06..da47b673c29 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -33,6 +33,7 @@ created as private in GitLab as well. and quote part of the original comment. - Declined pull requests have unreachable commits, which prevents the GitLab importer from generating a proper diff. These pull requests show up as empty changes. +- Pull request approvals are not imported. - Attachments in Markdown are not imported. - Task lists are not imported. - Emoji reactions are not imported. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 72bf0841687..d4cca723333 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -26,6 +26,7 @@ The following aspects of a project are imported: - Regular issue and pull request comments - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md) - Pull request comments replies in discussions ([GitLab.com & 14.5+](https://gitlab.com/gitlab-org/gitlab/-/issues/336596)) +- Diff Notes suggestions ([GitLab.com & 14.7+](https://gitlab.com/gitlab-org/gitlab/-/issues/340624)) [with a flag](../../../administration/feature_flags.md) named `github_importer_use_diff_note_with_suggestions`. Enabled by default. References to pull requests and issues are preserved (GitLab.com & 8.7+), and each imported repository maintains visibility level unless that [visibility @@ -164,16 +165,16 @@ your GitHub repositories are listed.  -## Mirror a repository and share pipeline status +## Mirror a repository and share pipeline status **(PREMIUM)** Depending on your GitLab tier, [repository mirroring](../repository/mirror/index.md) can be set up to keep your imported repository in sync with its GitHub copy. -Additionally, you can configure GitLab to send pipeline status updates back GitHub with the -[GitHub Project Integration](../integrations/github.md). **(PREMIUM)** +Additionally, you can configure GitLab to send pipeline status updates back to GitHub with the +[GitHub Project Integration](../integrations/github.md). If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/index.md), then both -of the above are automatically configured. **(PREMIUM)** +of the above are automatically configured. NOTE: Mirroring does not sync any new or updated pull requests from your GitHub project. diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 9d7ed593d41..001f0d56cc5 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -28,7 +28,7 @@ See these documents to migrate to GitLab: You can also import any Git repository through HTTP from the **New Project** page. Note that if the repository is too large, the import can timeout. -You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** +You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). ## LFS authentication @@ -42,7 +42,10 @@ However, you can't import issues and merge requests this way. To retain all meta merge requests, use the [import/export feature](../settings/import_export.md) to export projects from self-managed GitLab and import those projects into GitLab.com. All GitLab user associations (such as comment author) are changed to the user importing the project. For more -information, see [the import notes](../settings/import_export.md#important-notes). +information, see the prerequisites and important notes in these sections: + +- [Export a project and its data](../settings/import_export.md#export-a-project-and-its-data). +- [Import the project](../settings/import_export.md#import-a-project-and-its-data). NOTE: When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md) @@ -56,7 +59,7 @@ Migrate the assets in this order: 1. [Projects](../../../api/projects.md) 1. [Project variables](../../../api/project_level_variables.md) -Keep in mind the limitations of the [import/export feature](../settings/import_export.md#exported-contents). +Keep in mind the limitations of the [import/export feature](../settings/import_export.md#items-that-are-exported). You must still migrate your [Container Registry](../../packages/container_registry/) over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts. @@ -87,7 +90,7 @@ to migrate users. ## Project aliases **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab 12.1. GitLab repositories are usually accessed with a namespace and a project name. When migrating frequently accessed repositories to GitLab, however, you can use project aliases to access those diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 07e8ea1dc06..bee097cdcbe 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -1,8 +1,7 @@ --- stage: Manage group: Workspace -info: "To determine 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 +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Organize work with projects **(FREE)** @@ -43,9 +42,9 @@ Projects include the following [features](https://about.gitlab.com/features/): - [Issue tracker](issues/index.md): Discuss implementations with your team. - [Issue boards](issue_board.md): Organize and prioritize your workflow. - [Multiple issue boards](issue_board.md#multiple-issue-boards): Create team-specific workflows (issue boards) for a project. -- [Merge Requests](merge_requests/index.md): Apply a branching +- [Merge requests](merge_requests/index.md): Apply a branching strategy and get reviewed by your team. - - [Merge Request Approvals](merge_requests/approvals/index.md): Ask for approval before + - [Merge request approvals](merge_requests/approvals/index.md): Ask for approval before implementing a change. - [Fix merge conflicts from the UI](merge_requests/conflicts.md): View Git diffs from the GitLab UI. - [Review Apps](../../ci/review_apps/index.md): By branch, preview the results @@ -144,7 +143,7 @@ There are numerous [APIs](../../api/index.md) to use with your projects: - [Issue board](../../api/boards.md) - [Labels](../../api/labels.md) - [Markdown](../../api/markdown.md) -- [Merge Requests](../../api/merge_requests.md) +- [Merge requests](../../api/merge_requests.md) - [Milestones](../../api/milestones.md) - [Services](../../api/integrations.md) - [Snippets](../../api/project_snippets.md) diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 957290c5f20..0609b843e86 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Insights **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/725) in GitLab 12.0. Configure the Insights that matter for your projects to explore data such as triage hygiene, issues created/closed per a given period, average time for merge @@ -297,7 +297,7 @@ you may see `created_at` in place of `merged_at`. `created_at` is used instead. ### `projects` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10904) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10904) in GitLab 12.4. You can limit where the "issuables" can be queried from: diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index c9333b879f3..ad7719f0e5b 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Discord Notifications service **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22684) in GitLab 11.6. - The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. To send GitLab event notifications to a Discord channel, [create a webhook in Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) @@ -17,10 +15,12 @@ and configure it in GitLab. 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 to post the messages. Optionally, edit the avatar. -1. Note the URL from the **WEBHOOK URL** field. -1. Click the **Save** button. +1. Select **Integrations**. +1. If there are no existing webhooks, select **Create Webhook**. Otherwise, select **View Webhooks** then **New Webhook**. +1. Enter the name of the bot to post the message. +1. Optional. Edit the avatar. +1. Copy the URL from the **WEBHOOK URL** field. +1. Select **Save**. ## Configure created webhook in GitLab diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 9f1ea3796c6..c07142d6edf 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitHub project integration **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3836) in GitLab 10.6. - You can update GitHub with pipeline status updates from GitLab. This integration can help you if you use GitLab for CI/CD. @@ -46,8 +44,7 @@ to configure pipelines to run for open pull requests. ### Static or dynamic status check names -> - Introduced in GitLab 11.5 with static status check names as an opt-in option. -> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/9931) in GitLab 12.4 to make static status check names the default behavior for new projects. +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/9931) in GitLab 12.4 to make static status check names the default behavior for new projects. A status check name can be static or dynamic: diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 0d8ea636eba..0a685ad0efb 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -6,9 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Slack application **(FREE SAAS)** -> - Introduced in GitLab 9.4. -> - Distributed to Slack App Directory in GitLab 10.2. - NOTE: The GitLab Slack application is only configurable for GitLab.com. It will **not** work for on-premises installations where you can configure the diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 7a96bb74e3f..fbfa7d914a5 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Google Chat integration **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/43756) in GitLab 11.2. - Integrate your project to send notifications from GitLab to a room of your choice in [Google Chat](https://chat.google.com/) (former Google Hangouts). diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 819c17c12fd..5b83df9b22e 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -51,7 +51,7 @@ Click on the service links to see further configuration instructions and details | [Mattermost slash commands](mattermost_slash_commands.md) | Perform common tasks with slash commands. | **{dotted-circle}** No | | [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications. | **{dotted-circle}** No | | Packagist | Keep your PHP dependencies updated on Packagist. | **{check-circle}** Yes | -| Pipelines emails | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | +| [Pipelines emails](pipeline_status_emails.md) | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | | [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No | | [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | | Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | diff --git a/doc/user/project/integrations/pipeline_status_emails.md b/doc/user/project/integrations/pipeline_status_emails.md new file mode 100644 index 00000000000..742ab977090 --- /dev/null +++ b/doc/user/project/integrations/pipeline_status_emails.md @@ -0,0 +1,23 @@ +--- +stage: Ecosystem +group: Integrations +info: To 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 status emails **(FREE)** + +You can send notifications about pipeline status changes in a group or +project to a list of email addresses. + +## Enable pipeline status email notifications + +To enable pipeline status emails: + +1. In your project or group, on the left sidebar, select **Settings > Integrations**. +1. Select **Pipeline status emails**. +1. Ensure the **Active** checkbox is selected. +1. In **Recipients**, enter a comma-separated list of email addresses. +1. Optional. To receive notifications for broken pipelines only, select + **Notify only broken pipelines**. +1. Select the branches to send notifications for. +1. Select **Save changes**. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 680f787c83c..de7ac6782d6 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Prometheus integration **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. - GitLab offers powerful integration with [Prometheus](https://prometheus.io) for monitoring key metrics of your apps, directly in GitLab. Metrics for each environment are retrieved from Prometheus, and then displayed @@ -41,10 +39,9 @@ See [Prometheus cluster integration](../../clusters/integrations.md#prometheus-c Integration with Prometheus requires the following: -1. GitLab 9.0 or higher -1. Prometheus must be configured to collect one of the [supported metrics](prometheus_library/index.md) -1. Each metric must be have a label to indicate the environment -1. GitLab must have network connectivity to the Prometheus server +- Prometheus must be configured to collect one of the [supported metrics](prometheus_library/index.md) +- Each metric must have a label to indicate the environment +- GitLab must have network connectivity to the Prometheus server #### Getting started @@ -113,9 +110,6 @@ can use only one: ## Determining the performance impact of a merge -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10408) in GitLab 9.2. -> - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27439) of the 30 minute averages. - Developers can view the performance impact of their changes in the merge request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index b35ebacbd31..a07abf26fba 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -4,7 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Monitoring AWS resources (DEPRECATED) **(FREE)** + +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab supports automatically detecting and monitoring AWS resources, starting with the [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/) (ELB). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 11b74c35a74..97f69d65412 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -4,9 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Monitoring HAProxy (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab has support for automatically detecting and monitoring HAProxy. This is provided by leveraging the [HAProxy Exporter](https://github.com/prometheus/haproxy_exporter), which translates HAProxy statistics into a Prometheus readable form. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index fe74ea6834b..a5fc398e558 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -4,9 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Prometheus Metrics library (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 429df7f7e27..26d006adeb9 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -4,9 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Monitoring Kubernetes (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8935) in GitLab 9.0. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab has support for automatically detecting and monitoring Kubernetes metrics. @@ -44,8 +48,6 @@ Instead, the [Deployment](https://kubernetes.io/docs/concepts/workloads/controll ## Displaying Canary metrics **(PREMIUM)** -> Introduced in [GitLab 10.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15201). - GitLab also gathers Kubernetes metrics for [canary deployments](../../canary_deployments.md), allowing easy comparison between the current deployed version and the canary. These metrics expect the [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) or [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) name to begin with `$CI_ENVIRONMENT_SLUG-canary`, to isolate the canary metrics. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 3f888a89b1b..ad89543e9a6 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -4,9 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Monitoring NGINX (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12621) in GitLab 9.4 +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. GitLab has support for automatically detecting and monitoring NGINX. This is provided by leveraging the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter), which translates [VTS statistics](https://github.com/vozlt/nginx-module-vts) into a Prometheus readable form. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 6478011b730..03bf9258659 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -4,9 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Monitoring NGINX Ingress Controller (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22133) in GitLab 11.7. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. 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. 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 6bdd2c64dcf..89c174f8fb9 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -4,9 +4,13 @@ group: Monitor info: To 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 **(FREE)** +# Monitoring NGINX Ingress Controller with VTS metrics (DEPRECATED) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13438) in GitLab 9.5. +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. + +WARNING: +This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) +for use in GitLab 14.7, and is planned for removal in GitLab 15.0. NOTE: [NGINX Ingress version 0.16](nginx_ingress.md) and above have built-in Prometheus metrics, which are different than the VTS based metrics. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 87f38c3482b..870554100b7 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -59,20 +59,20 @@ Your Slack team now starts receiving GitLab event notifications as configured. The following triggers are available for Slack notifications: -| Trigger name | Trigger event | -| ------------------------ | ------------------------------------------------------ | -| **Push** | A push to the repository. | -| **Issue** | An issue is created, updated, or closed. | -| **Confidential issue** | A confidential issue is created, updated, or closed. | -| **Merge request** | A merge request is created, updated, or merged. | -| **Note** | A comment is added. | -| **Confidential note** | A confidential note is added. | -| **Tag push** | A new tag is pushed to the repository. | -| **Pipeline** | A pipeline status changed. | -| **Wiki page** | A wiki page is created or updated. | -| **Deployment** | A deployment starts or finishes. | -| **Alert** | A new, unique alert is recorded. | -| **Vulnerability** | **(ULTIMATE)** A new, unique vulnerability is recorded. | +| Trigger name | Trigger event | +|--------------------------------------------------------------------------|------------------------------------------------------| +| **Push** | A push to the repository. | +| **Issue** | An issue is created, updated, or closed. | +| **Confidential issue** | A confidential issue is created, updated, or closed. | +| **Merge request** | A merge request is created, updated, or merged. | +| **Note** | A comment is added. | +| **Confidential note** | A confidential note is added. | +| **Tag push** | A new tag is pushed to the repository. | +| **Pipeline** | A pipeline status changed. | +| **Wiki page** | A wiki page is created or updated. | +| **Deployment** | A deployment starts or finishes. | +| **Alert** | A new, unique alert is recorded. | +| [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | ## Troubleshooting diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index e0405955d3d..8bc2b51276a 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -21,11 +21,10 @@ you can use webhooks to: every time an issue is created for a specific project or group in GitLab. - [Automatically assign labels to merge requests](https://about.gitlab.com/blog/2016/08/19/applying-gitlab-labels-automatically/). -You can configure your GitLab project or [group](#group-webhooks) to trigger -a percent-encoded webhook URL when an event occurs. For example, when new code -is pushed or a new issue is created. -The webhook listens for specific [events](#events) and -GitLab sends a POST request with data to the webhook URL. +You can configure your GitLab project or [group](#group-webhooks) to trigger a +[percent-encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding) webhook URL +when an event occurs. For example, when new code is pushed or a new issue is created. The webhook +listens for specific [events](#events) and GitLab sends a POST request with data to the webhook URL. Usually, you set up your own [webhook receiver](#create-an-example-webhook-receiver) to receive information from GitLab and send it to another app, according to your requirements. @@ -55,7 +54,7 @@ You can configure a webhook for a group or a project. 1. In your project or group, on the left sidebar, select **Settings > Webhooks**. 1. In **URL**, enter the URL of the webhook endpoint. - The URL must be percentage-encoded, if necessary. + The URL must be percent-encoded if it contains one or more special characters. 1. In **Secret token**, enter the [secret token](#validate-payloads-by-using-a-secret-token) to validate payloads. 1. In the **Trigger** section, select the [events](webhook_events.md) to trigger the webhook. 1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](#verify-an-ssl-certificate). @@ -135,8 +134,6 @@ in your GitLab projects. ## Filter push events by branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/20338) in GitLab 11.3. - Push events can be filtered by branch using a branch name or wildcard pattern to limit which push events are sent to your webhook endpoint. By default, all push events are sent to your webhook endpoint. You can configure branch filtering @@ -159,8 +156,6 @@ GitLab webhooks, keep in mind the following: ## How image URLs are displayed in the webhook body -> Introduced in GitLab 11.2. - Relative image references are rewritten to use an absolute URL in the body of a webhook. For example, if an image, merge request, comment, or wiki page includes the diff --git a/doc/user/project/issues/img/issue_board.png b/doc/user/project/issues/img/issue_board.png Binary files differdeleted file mode 100644 index dd40740aec5..00000000000 --- a/doc/user/project/issues/img/issue_board.png +++ /dev/null diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 1a23902514a..d120df82dbf 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -22,7 +22,7 @@ You can create an issue in many ways in GitLab: - [From another issue](#from-another-issue) - [From an issue board](#from-an-issue-board) - [By sending an email](#by-sending-an-email) -- Using a URL with prefilled fields +- [Using a URL with prefilled values](#using-a-url-with-prefilled-values) - [Using Service Desk](#using-service-desk) ### From a project @@ -639,6 +639,9 @@ You can then see the issue's status in the issues list and the epic tree. After an issue is closed, its health status can't be edited and the **Edit** button becomes disabled until the issue is reopened. +You can also set and clear health statuses using the `/health_status` and `/clear_health_status` +[quick actions](../quick_actions.md#issues-merge-requests-and-epics). + ## Publish an issue **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906) in GitLab 13.1. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 8874512f9c3..7ccc39eeb8b 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -90,9 +90,10 @@ label section of the right sidebar of an issue or a merge request: color value for a specific color. 1. Click **Create**. -Once created, you can edit a label by clicking the pencil (**{pencil}**), or delete -a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** button -and selecting **Delete**. +To edit a label after you create it, select (**{pencil}**). + +To delete a project label, select (**{ellipsis_v}**) next to the **Subscribe** button +and select **Delete** or select **Delete** when you edit a label. 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. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 283576fb4e9..2dc29f5d725 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -211,7 +211,7 @@ Instead of adding users one by one, you can [share a project with an entire grou > - Enabled on GitLab.com. > - Recommended for production use. > - Replaces the existing form with buttons to open a modal window. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-modal-window). **(FREE SELF)** +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-modal-window). WARNING: This feature might not be available to you. Check the **version history** note above for details. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 4c96c4d9f56..4e3bae2dc30 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -52,7 +52,7 @@ Administrators can share projects with any group in the system. > - Enabled on GitLab.com. > - Recommended for production use. > - Replaces the existing form with buttons to open a modal window. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-modal-window). **(FREE SELF)** +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-modal-window). WARNING: This feature might not be available to you. Check the **version history** note above for details. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 8f803f9207c..e67af8dc936 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -9,71 +9,69 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. -If your application offers a web interface and you are using -[GitLab CI/CD](../../../ci/index.md), you can quickly determine the accessibility +If your application offers a web interface, you can use +[GitLab CI/CD](../../../ci/index.md) to determine the accessibility impact of pending code changes. -## Overview - -GitLab uses [pa11y](https://pa11y.org/), a free and open source tool for -measuring the accessibility of web sites, and has built a simple +[Pa11y](https://pa11y.org/) is a free and open source tool for +measuring the accessibility of web sites. GitLab integrates Pa11y into a [CI job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). -This job outputs accessibility violations, warnings, and notices for each page -analyzed to a file called `accessibility`. +The `a11y` job analyzes a defined set of web pages and reports +accessibility violations, warnings, and notices in a file named +`accessibility`. -From [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), the version of `pa11y` uses -[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1), which may report more issues. +As of [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), Pa11y uses +[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1). ## Accessibility merge request widget > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 13.0 behind the disabled [feature flag](../../../administration/feature_flags.md) `:accessibility_report_view`. > - [Feature Flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217372) in GitLab 13.1. -In addition to the report artifact that is created, GitLab will also show the -Accessibility Report in the merge request widget area: +GitLab displays an **Accessibility Report** in the merge request widget area:  -## Configure Accessibility Testing - -This example shows how to run [pa11y](https://pa11y.org/) -on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility). +## Configure accessibility testing -For GitLab 12.9 and later, to define the `a11y` job, you must -[include](../../../ci/yaml/index.md#includetemplate) the -[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) -included with your GitLab installation, as shown below. +You can run Pa11y with GitLab CI/CD using the +[GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility). -Add the following to your `.gitlab-ci.yml` file: +To define the `a11y` job for GitLab 12.9 and later: -```yaml -stages: - - accessibility +1. [Include](../../../ci/yaml/index.md#includetemplate) the + [`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) + from your GitLab installation. +1. Add the following configuration to your `.gitlab-ci.yml` file. -variables: - a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in" + ```yaml + stages: + - accessibility + + variables: + a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in" + + include: + - template: "Verify/Accessibility.gitlab-ci.yml" + ``` -include: - - template: "Verify/Accessibility.gitlab-ci.yml" -``` +1. Customize the `a11y_urls` variable to list the URLs of the web pages to test with Pa11y. -creates an `a11y` job in your CI/CD pipeline, runs -Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each. +The `a11y` job in your CI/CD pipeline generates these files: -The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +- One HTML report per URL listed in the `a11y_urls` variable. +- One file containing the collected report data. In GitLab versions 12.11 and later, this + file is named `gl-accessibility.json`. In GitLab versions 12.10 and earlier, this file + is named [`accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). -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: -For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9). +You can [view job artifacts in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). NOTE: -For GitLab versions earlier than 12.9, you can use `include:remote` and use a +For GitLab versions earlier than 12.9, use `include:remote` and link to the [current template in the default branch](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) NOTE: -The job definition provided by the template does not support Kubernetes yet. +The job definition provided by the template does not support Kubernetes. -It is not yet possible to pass configurations into Pa11y via CI configuration. To change anything, -copy the template to your CI file and make the desired edits. +You cannot pass configurations into Pa11y via CI configuration. +To change the configuration, edit a copy of the template in your CI file. diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 5d1a04e1fe0..b10d6597c1e 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -2,77 +2,99 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- -# Allow collaboration on merge requests across forks **(FREE)** +# Collaborate on merge requests across forks **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17395) in GitLab 10.6. +When you open a merge request from your fork, you can allow upstream +members to collaborate with you on your branch. +When you enable this option, members who have permission to merge to the target branch get +permission to write to the merge request's source branch. -When a user opens a merge request from a fork, they are given the option to allow -upstream members to collaborate with them on the source branch. This allows -the members of the upstream project to make small fixes or rebase branches -before merging, reducing the back and forth of accepting external contributions. +The members of the upstream project can then make small fixes or rebase branches +before merging. This feature is available for merge requests across forked projects that are publicly accessible. -When enabled for a merge request, members with merge access to the target -branch of the project is granted write permissions to the source branch -of the merge request. +## Allow commits from upstream members -## Enabling commit edits from upstream members +> Enabled by default in [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308). -In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308), -this setting is enabled by default. It can be changed by users with the -Developer [role](../../permissions.md) for the source project. After it's enabled, -upstream members can retry the pipelines and jobs of the merge request: +As the author of a merge request, you can allow commit edits from +upstream members of the project you're contributing to: 1. While creating or editing a merge request, scroll to **Contribution** and - then select the **Allow commits from members who can merge to the target branch**. + select the **Allow commits from members who can merge to the target branch** checkbox. 1. Finish creating your merge request. -After you create the merge request, the merge request widget displays a message: -**Members who can merge are allowed to add commits.** +After you create the merge request, the merge request widget displays the message +**Members who can merge are allowed to add commits**. Upstream members can then +commit directly to your branch, as well as retry the pipelines and jobs of the +merge request. -## Pushing to the fork as the upstream member +## Prevent commits from upstream members -If the creator of the merge request has enabled contributions from upstream -members, you can push directly to the branch of the forked repository. +As the author of a merge request, you can prevent commit edits from +upstream members of the project you're contributing to: -Assuming that: +1. While creating or editing a merge request, scroll to **Contribution** and + clear the **Allow commits from members who can merge to the target branch** + checkbox. +1. Finish creating your merge request. + +## Push to the fork as the upstream member -- The forked project URL is `git@gitlab.com:thedude/awesome-project.git`. -- The branch of the merge request is `update-docs`. +You can push directly to the branch of the forked repository if: -To find and work with the changes from the fork: +- The author of the merge request has enabled contributions from upstream + members. +- You have at least the [Developer role](../../permissions.md) in the + upstream project. + +In the following example: + +- The forked repository URL is `git@gitlab.com:contributor/forked-project.git`. +- The branch of the merge request is `fork-branch`. + +To change or add a commit to the contributor's merge request: 1. Open the merge request page, and select the **Overview** tab. -1. Scroll to the merge request widget, and select **Check out branch**: -  -1. In the modal window, select **{copy-to-clipboard}** (**Copy**) for step 1 - to copy the `git fetch` and `git checkout` instructions to your clipboard. - Paste the commands (which look like this example) into your terminal: +1. Scroll to the merge request widget, and select **Check out branch**. +1. In the modal window, select **Copy** (**{copy-to-clipboard}**). +1. In your terminal, navigate to your cloned version of the repository, and + paste the commands. For example: ```shell - git fetch git@gitlab.com:thedude/awesome-project.git update-docs - git checkout -b thedude-awesome-project-update-docs FETCH_HEAD + git fetch "git@gitlab.com:contributor/forked-project.git" 'fork-branch' + git checkout -b contributor/fork-branch' FETCH_HEAD ``` - These commands fetch the branch from the forked project, and create a local branch - based off the fetched branch. + Those commands fetch the branch from the forked project, and create a local branch + for you to work on. + +1. Make your changes to your local copy of the branch, and then commit them. +1. Push your local changes to the forked project. The following command pushes + the local branch `contributor/fork-branch` to the `fork-branch` branch of + the `git@gitlab.com:contributor/forked-project.git` repository: -1. Make your changes to the local copy of the branch, and then commit them. -1. In your terminal, push your local changes back up to the forked project. This - command pushes the local branch `thedude-awesome-project-update-docs` to the - `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository: + ```shell + git push git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch + ``` + + If you have amended or squashed any commits, you must force push. Proceed + with caution as this command rewrites the commit history: ```shell - git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs + git push --force git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch ``` - Note the colon (`:`) between the two branches. + Note the colon (`:`) between the two branches. The general scheme is: + + ```shell + git push <forked_repository_git_url> <local_branch>:<fork_branch> + ``` ## Troubleshooting @@ -89,14 +111,3 @@ going back to the original project: 1. Create a group containing all the upstream members. 1. Go to the **Project information > Members** page in the forked project and invite the newly-created group to the forked project. - -<!-- ## 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. - -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. --> diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index f4393b2b76d..129010010e7 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -1,8 +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/#assignments" -type: reference, concepts +info: To 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 approval rules **(PREMIUM)** @@ -146,8 +145,7 @@ approve in these ways: ### Code owners as eligible approvers **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7933) in GitLab 11.5. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. If you add [code owners](../../code_owners.md) to your repository, the owners of files become eligible approvers in the project. To enable this merge request approval rule: diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index a6ca9423df0..1e1c8ccb241 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -1,8 +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/#assignments" -type: reference, concepts +info: To 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 approval settings **(PREMIUM)** @@ -32,8 +31,7 @@ In this section of general settings, you can configure the following settings: ## Prevent approval by author -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3349) in GitLab 11.3. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. By default, the author of a merge request cannot approve it. To change this setting: @@ -54,8 +52,7 @@ this setting, unless you configure one of these options: ## Prevent approvals by users who add commits -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10441) in GitLab 11.10. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. By default, users who commit to a merge request can still approve it. At both the project level or [instance level](../../../admin_area/merge_requests_approvals.md) diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index e59456e5b34..6668e1736cf 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -63,7 +63,7 @@ on your code by using GitLab CI/CD and [sitespeed.io](https://www.sitespeed.io) using Docker-in-Docker. 1. First, set up GitLab Runner with a - [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). + [Docker-in-Docker build](../../../ci/docker/using_docker_build.md#use-docker-in-docker). 1. Configure the default Browser Performance Testing CI/CD job as follows in your `.gitlab-ci.yml` file: ```yaml diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index b791bce5749..30d463efa69 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -2,13 +2,11 @@ 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/#assignments -type: reference, howto --- # Code Quality **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. To ensure your project's code stays simple, readable, and easy to contribute to, you can use [GitLab CI/CD](../../../ci/index.md) to analyze your source code quality. @@ -32,8 +30,7 @@ Code Quality: ## Code Quality Widget -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. Going a step further, GitLab can show the Code Quality report right in the merge request widget area if a report from the target branch is available to compare to: @@ -69,11 +66,8 @@ the merge request's diff view displays an indicator next to lines with new Code ## Example configuration This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. -It requires GitLab 11.11 or later, and GitLab Runner 11.5 or later. If you are using -GitLab 11.4 or earlier, you can view the deprecated job definitions in the -[documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). -- Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). +- Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker). - Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running Code Quality analysis more efficiently. In either configuration, the runner must have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. @@ -232,7 +226,7 @@ are configured with `privileged=true`, and they do not expose `docker.sock` into the job container. As a result, socket binding cannot be used to make `docker` available in the context of the job script. -[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-docker-in-docker) was chosen as an operational decision by the runner team, instead of exposing `docker.sock`. ### Disabling the code quality job diff --git a/doc/user/project/merge_requests/commit_templates.md b/doc/user/project/merge_requests/commit_templates.md index bffb66755e0..0cc18d2117b 100644 --- a/doc/user/project/merge_requests/commit_templates.md +++ b/doc/user/project/merge_requests/commit_templates.md @@ -67,6 +67,8 @@ GitLab creates a squash commit message with this template: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5. > - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/346805) `first_commit` and `first_multiline_commit` variables in GitLab 14.6. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75639) `url`, `approved_by`, and `merged_by` variables in GitLab 14.7. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/20421) `co_authored_by` variable in GitLab 14.7. Commit message templates support these variables: @@ -80,8 +82,13 @@ Commit message templates support these variables: | `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` | | `%{first_commit}` | Full message of the first commit in merge request diff. | `Update README.md` | | `%{first_multiline_commit}` | Full message of the first commit that's not a merge commit and has more than one line in message body. Merge Request title if all commits aren't multiline. | `Update README.md`<br><br>`Improved project description in readme file.` | +| `%{url}` | Full URL to the merge request. | `https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1` | +| `%{approved_by}` | Line-separated list of the merge request approvers. This value is not updated until the first page refresh after an approval. | `Approved-by: Sidney Jones <sjones@example.com>` <br> `Approved-by: Zhang Wei <zwei@example.com>` | +| `%{merged_by}` | User who merged the merge request. | `Alex Garcia <agarcia@example.com>` | +| `%{co_authored_by}` | Names and emails of commit authors in a `Co-authored-by` Git commit trailer format. Limited to authors of 100 most recent commits in merge request. | `Co-authored-by: Zane Doe <zdoe@example.com>` <br> `Co-authored-by: Blake Smith <bsmith@example.com>` | -Empty variables that are the only word in a line are removed, along with all newline characters preceding it. +Any line containing only an empty variable is removed. If the line to be removed is both +preceded and followed by an empty line, the preceding empty line is also removed. ## Related topics diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 220049d9a88..6ee02238a22 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -2,7 +2,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/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' --- @@ -78,7 +77,7 @@ You can create a merge request by running Git commands on your local machine. ```plaintext ... - remote: To create a merge request for docs-new-merge-request, visit: + remote: To create a merge request for my-new-branch, visit: remote: https://gitlab.example.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch ``` @@ -111,10 +110,6 @@ For more information, [see the forking workflow documentation](../repository/for ## By sending an email -> The format of the generated email address changed in GitLab 11.7. - The earlier format is still supported so existing aliases - or contacts still work. - You can create a merge request by sending an email message to GitLab. The merge request target branch is the project's default branch. @@ -142,8 +137,6 @@ A merge request is created. ### Add attachments when creating a merge request by email -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5. - You can add commits to a merge request by adding patches as attachments to the email. All attachments with a filename ending in `.patch` are considered patches and are processed diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 0d87a04461b..3cb50195f5a 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -42,7 +42,7 @@ This template requires: - A project built in Rails that uses RSpec for testing. - CI/CD configured to: - Use a Docker image with Ruby available. - - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#configure-pipelines-for-merge-requests) + - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#prerequisites) - [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results) enabled in the project settings. - A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#override-included-configuration-values) this. diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 078f8048900..cd65fe20e66 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -38,9 +38,12 @@ Now, when you visit the merge request page, you can accept it If a fast-forward merge is not possible but a conflict free rebase is possible, a rebase button is offered. +You can also rebase without running a CI/CD pipeline. +[Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/118825) GitLab 14.7. + The rebase action is also available as a [quick action command: `/rebase`](../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui). - + If the target branch is ahead of the source branch and a conflict free rebase is not possible, you need to rebase the @@ -48,6 +51,13 @@ source branch locally before you can do a fast-forward merge.  +## Fast-forward merges prevent squashing commits + +If your project has enabled fast-forward merges, to merge cleanly, the code in a +merge request cannot use [squashing during merge](squash_and_merge.md). Squashing +is available only when accepting a merge request. Rebasing may be required before +squashing, even though squashing can itself be considered equivalent to rebasing. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index 323b7505190..ec509f58723 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -2,7 +2,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: index, reference description: "Getting started with merge requests." --- @@ -92,8 +91,7 @@ and the merge request is added to their #### Multiple assignees **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2004) in GitLab 11.11. -> - Moved to GitLab Premium in 13.9 +> Moved to GitLab Premium in 13.9 Multiple people often review merge requests at the same time. GitLab allows you to have multiple assignees for merge requests @@ -207,7 +205,7 @@ This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitla - When working locally in your branch, add multiple commits and only push when you're done, so GitLab runs only one pipeline for all the commits pushed - at once. By doing so, you save pipeline minutes. + at once. By doing so, you save CI/CD minutes. - Delete feature branches on merge or after merging them to keep your repository clean. - Take one thing at a time and ship the smallest changes possible. By doing so, reviews are faster and your changes are less prone to errors. diff --git a/doc/user/project/merge_requests/img/commit-button_v13_12.png b/doc/user/project/merge_requests/img/commit-button_v13_12.png Binary files differdeleted file mode 100644 index be154b9e60b..00000000000 --- a/doc/user/project/merge_requests/img/commit-button_v13_12.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase.png b/doc/user/project/merge_requests/img/ff_merge_rebase.png Binary files differdeleted file mode 100644 index f6139f189ce..00000000000 --- a/doc/user/project/merge_requests/img/ff_merge_rebase.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png Binary files differnew file mode 100644 index 00000000000..3c845d277e4 --- /dev/null +++ b/doc/user/project/merge_requests/img/ff_merge_rebase_v14_7.png diff --git a/doc/user/project/merge_requests/img/squash_edit_form.png b/doc/user/project/merge_requests/img/squash_edit_form.png Binary files differdeleted file mode 100644 index 326d74b68cb..00000000000 --- a/doc/user/project/merge_requests/img/squash_edit_form.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_mr_commits.png b/doc/user/project/merge_requests/img/squash_mr_commits.png Binary files differdeleted file mode 100644 index dfc1ee38435..00000000000 --- a/doc/user/project/merge_requests/img/squash_mr_commits.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_mr_message.png b/doc/user/project/merge_requests/img/squash_mr_message.png Binary files differdeleted file mode 100644 index 8c7dc7886f7..00000000000 --- a/doc/user/project/merge_requests/img/squash_mr_message.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_mr_widget.png b/doc/user/project/merge_requests/img/squash_mr_widget.png Binary files differdeleted file mode 100644 index 81334ca9758..00000000000 --- a/doc/user/project/merge_requests/img/squash_mr_widget.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/squash_squashed_commit.png b/doc/user/project/merge_requests/img/squash_squashed_commit.png Binary files differdeleted file mode 100644 index 7def5339d8a..00000000000 --- a/doc/user/project/merge_requests/img/squash_squashed_commit.png +++ /dev/null diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index 7b157aa94d8..40859c6b572 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -103,7 +103,7 @@ job. An example configuration workflow: 1. Set up GitLab Runner to run Docker containers, like the - [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). + [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-docker-in-docker). 1. Configure the default Load Performance Testing CI/CD job in your `.gitlab-ci.yml` file. You need to include the template and configure it with CI/CD variables: diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index e6fb619d365..6441ccb73fe 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -2,7 +2,6 @@ stage: Create group: Code Review info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, concepts --- # Revert changes **(FREE)** @@ -13,11 +12,6 @@ by clicking the **Revert** button in merge requests and commit details. ## Revert a merge request NOTE: -The **Revert** button is available only 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: The **Revert** button is shown only 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/reviews/img/suggestions_custom_commit_messages_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg Binary files differdeleted file mode 100644 index a4c9df0ebb9..00000000000 --- a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg +++ /dev/null diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png Binary files differnew file mode 100644 index 00000000000..2805ef19f2d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v14_7.png diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index c25b9e15974..1b2a35ba139 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -89,7 +89,7 @@ These commit messages can be customized to follow any guidelines you might have. To do so, expand the **Merge requests** tab within your project's **General** settings and change the **Merge suggestions** text: - + You can also use following variables besides static text: diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 3fe82fb8ef3..f90296e9626 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -2,131 +2,79 @@ 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/#assignments -type: reference, concepts --- # Squash and merge **(FREE)** -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from GitLab Premium to GitLab Free in 11.0. +As you work on a feature branch, you often create small, self-contained commits. These small commits +help describe the process of building a feature, but can clutter your Git history after the feature +is finished. As you finish features, you can combine these commits and ensure a cleaner merge history +in your Git repository by using the _squash and merge_ strategy. -With squash and merge you can combine all your merge request's commits into one -and retain a clean history. +- Small commits are joined together, making it simpler to [revert all parts of a change](revert_changes.md). +- When the single commit merges into the target branch, it retains the full commit history. +- Your base branch remains clean, and contains meaningful commit messages. -Squashing lets you tidy up the commit history of a branch when accepting a merge -request. It applies all of the changes in the merge request as a single commit, -and then merges that commit using the merge method set for the project. +Each time a branch merges into your base branch, up to two commits are added: -In other words, squashing a merge request turns a long list of commits: +- The single commit created by squashing the commits from the branch. +- A merge commit, unless you have [enabled fast-forward merges](fast_forward_merge.md#enabling-fast-forward-merges) + in your project. Fast-forward merges disable both merge commits and squashing. - +By default, squashed commits contain the following metadata: -Into a single commit on merge: +- Message: Description of the squash commit, or a customized message +- Author: User that created the merge request +- Committer: User who initiated the squash - +Project owners can [create new default messages](commit_templates.md) for all +squash commits and merge commits. -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**. +## Set default squash options for a merge request -The squashed commit's default commit message is taken from the merge request title. -You can [edit the default message for squash commits](commit_templates.md). +Users with permission to create or edit a merge request can set the default squash options +for a merge request. To do this: -It can also be customized before merging a merge request. +1. Go to the merge request and select **Edit**. +1. Select or clear the **Squash commits when merge request is accepted** checkbox. +1. Select **Save changes**. - +## Squash commits in a merge request -Squashing also works with the fast-forward merge strategy, see [squashing and fast-forward merge](#squash-and-fast-forward-merge) for more details. +If your project allows you to select squashing options for merge requests, to +squash the commits as part of the merge process: -## Use cases +1. Go to the merge request, and scroll to the merge request reports section that + contains the **Merge** button. +1. Ensure the **Squash commits** checkbox is selected. This checkbox doesn't display + if the project's squashing option is set to either **Do not allow** or **Require**. +1. Optional. To modify either the squash commit message or the merge commit message + (depending on your project configuration), select **Modify commit messages**. +1. When the merge request is ready to merge, select **Merge**. -When working on a feature branch, you sometimes want to commit your current -progress, but don't really care about the commit messages. Those 'work in -progress commits' don't necessarily contain important information and as such -you'd rather not include them in your target branch. +## Configure squash options for a project -With squash and merge, when the merge request is ready to be merged, -all you have to do is enable squashing before you press merge to join -the commits in the merge request into a single commit. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2 [with a flag](../../../administration/feature_flags.md) named `squash_options`, disabled by default. +> - [Enabled on GitLab.com and self-managed by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/232536) in GitLab 13.8. Feature flag `squash_options` removed. -This way, the history of your base branch remains clean with -meaningful commit messages and: +To configure the default squashing behavior for all merge requests in your project: -- It's simpler to [revert](revert_changes.md) if necessary. -- The merged branch retains the full commit history. - -## Enable squash for a merge request - -Anyone who can create or edit a merge request can choose for it to be squashed -on the merge request form. Users can select or clear the checkbox when they -create the merge request: - - - -After the merge request is submitted, Squash and Merge can still be enabled or disabled -by editing the merge request description: - -1. Scroll to the top of the merge request page and click **Edit**. -1. Scroll down to the end of the merge request form and select the checkbox -**Squash commits when merge request is accepted**. - -This setting can then be overridden at the time of accepting the merge request. -At the end of the merge request widget, next to the **Merge** button, the **Squash commits** checkbox -can be either selected or unselected: - - - -Note that Squash and Merge might not be available depending on the project's configuration -for [Squash Commit Options](#squash-commits-options). - -## Commit metadata for squashed commits - -The squashed commit has the following metadata: - -- Message: the message of the squash commit, or a customized message. -- Author: the author of the merge request. -- Committer: the user who initiated the squash. - -## Squash and fast-forward merge - -When a project has the [fast-forward merge setting enabled](fast_forward_merge.md#enabling-fast-forward-merges), the merge -request must be able to be fast-forwarded without squashing in order to squash -it. This is because squashing is only available when accepting a merge request, -so a merge request may need to be rebased before squashing, even though -squashing can itself be considered equivalent to rebasing. - -## Squash commits options - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2. -> - Deployed behind a feature flag, disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. -> - Enabled on GitLab.com. -> - Can be enabled per project. -> - Recommended for production use. - -With Squash Commits Options you can configure the behavior of Squash and Merge for your project. -To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. -You can choose from these options, which affect existing and new merge requests -submitted to your project: - -- **Do not allow**: users cannot use Squash and Merge to squash all the commits immediately before - merging. The checkbox to enable or disable it is unchecked and hidden from the users. -- **Allow**: users can enable Squash and Merge on a merge request basis. - The checkbox is unchecked (disabled) by default, but and the user is allowed to enable it. -- **Encourage**: users can enable Squash and Merge on a merge request basis. - The checkbox is checked (enabled) by default to encourage its use, but the user is allowed to - disable it. -- **Require**: Squash and Merge is enabled for all merge requests, so it is always performed. - The checkbox to enable or disable it is checked and hidden from the users. - -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: -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. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Squash commits when merging** section, select your desired behavior: + - **Do not allow**: Squashing is never performed, and the option is not displayed. + - **Allow**: Squashing is allowed, but deselected by default. + - **Encourage**: Squashing is allowed and selected by default, but can be disabled. + - **Require**: Squashing is always performed. While merge requests display the option + to squash, users cannot change it. +1. Select **Save changes**. ## Related topics -- [Commit message templates](commit_templates.md). +- [Commit message templates](commit_templates.md) +- [Fast-forward merges](fast_forward_merge.md) <!-- ## Troubleshooting diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 796ffc7866c..236ec64a4dc 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -39,8 +39,6 @@ changes appears as a system note. ## Find the merge request that introduced a change -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2383) in GitLab 10.5. - 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. 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 f52f64626ac..cee10675a62 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,5 +1,4 @@ --- -type: reference, howto 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 @@ -7,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Create a Pages website from a template **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8. - GitLab provides templates for the most popular Static Site Generators (SSGs). You can create a new project from a template and run the CI/CD pipeline to generate a Pages website. diff --git a/doc/user/project/pages/img/icons/lock.png b/doc/user/project/pages/img/icons/lock.png Binary files differdeleted file mode 100644 index f7f32fded45..00000000000 --- a/doc/user/project/pages/img/icons/lock.png +++ /dev/null diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 59a2f0c2eba..10fbc57fa0b 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -214,8 +214,6 @@ needing to compress files on-demand. ### Resolving ambiguous URLs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/95) in GitLab 11.8 - GitLab Pages makes assumptions about which files to serve when receiving a request for a URL that does not include an extension. diff --git a/doc/user/project/pages/pages_access_control.md b/doc/user/project/pages/pages_access_control.md index 4b4d479e3e9..002b234f561 100644 --- a/doc/user/project/pages/pages_access_control.md +++ b/doc/user/project/pages/pages_access_control.md @@ -1,5 +1,4 @@ --- -type: reference, howto 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 @@ -7,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Pages access control **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33422) in GitLab 11.5. -> - Available on GitLab.com in GitLab 12.4. +> Available on GitLab.com in GitLab 12.4. You can enable Pages access control on your project if your administrator has [enabled the access control feature](../../../administration/pages/index.md#access-control) diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index a4e94c03e86..6c18fc158f5 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -1,8 +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/#assignments" -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Protected branches **(FREE)** @@ -76,8 +75,6 @@ The protected branch displays in the list of protected branches. ## Create a protected branch -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) in GitLab 11.9. - Users with the Developer or higher [role](../permissions.md) can create a protected branch. Prerequisites: diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index b4e13aebdb2..e4743c82a3b 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Protected tags **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10356) in GitLab 9.1. - Protected tags: - Allow control over who has permission to create tags. diff --git a/doc/user/project/push_options.md b/doc/user/project/push_options.md index 15df69ee68c..846d4732533 100644 --- a/doc/user/project/push_options.md +++ b/doc/user/project/push_options.md @@ -1,14 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Push Options **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15643) in GitLab 11.7. - GitLab supports using client-side [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) to perform various actions at the same time as pushing changes. Additionally, [Push Rules](../../push_rules/push_rules.md) offer server-side control and enforcement options. diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 75a5a2a6a4f..21a080de404 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -47,76 +47,78 @@ threads. Some quick actions might not be available to all subscription tiers. <!-- Keep this table sorted alphabetically --> -| Command | Issue | Merge request | Epic | Action | -|:--------------------------------------|:-----------------------|:-----------------------|:-----------------------|:-------| -| `/add_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | -| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | -| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. | -| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | -| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | -| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | -| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | -| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | -| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | -| `/clone <path/to/project> [--with_notes]`| **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | -| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | -| `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Make confidential. | -| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | -| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | -| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | -| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | -| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | -| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | -| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. | -| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | -| `/estimate <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). | -| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | -| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | -| `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | -| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | -| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | -| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | -| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. | -| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | -| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | -| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced in GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/296787)). | -| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | -| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | -| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | -| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | -| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | -| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | -| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | -| `/remove_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | -| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | -| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | -| `/remove_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. | -| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | -| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | -| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | -| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | -| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | -| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | -| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/334045). | -| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | -| `/spend <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). | -| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). | -| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | -| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | -| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | -| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | -| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | -| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8103)| -| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | -| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | -| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | -| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | -| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | -| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | -| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | -| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | -| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | -| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| Command | Issue | Merge request | Epic | Action | +|:-------------------------------------------------------------------------------------------------|:-----------------------|:-----------------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/add_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | +| `/approve` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Approve the merge request. | +| `/assign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users. | +| `/assign me` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself. | +| `/assign_reviewer @user1 @user2` or `/reviewer @user1 @user2` or `/request_review @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign one or more users as reviewers. | +| `/assign_reviewer me` or `/reviewer me` or `/request_review me` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Assign yourself as a reviewer. | +| `/award :emoji:` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Toggle emoji award. | +| `/child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | +| `/clear_health_status` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear [health status](issues/managing_issues.md#health-status) ([introduced in GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/213814)). | +| `/clear_weight` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clear weight. | +| `/clone <path/to/project> [--with_notes]` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Clone the issue to given project, or the current one if no arguments are given ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9421) in GitLab 13.7). Copies as much data as possible as long as the target project contains equivalent labels, milestones, and so on. Does not copy comments or system notes unless `--with_notes` is provided as an argument. | +| `/close` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Close. | +| `/confidential` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Make confidential. | +| `/copy_metadata <!merge_request>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another merge request in the project. | +| `/copy_metadata <#issue>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Copy labels and milestone from another issue in the project. | +| `/create_merge_request <branch name>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Create a new merge request starting from the current issue. | +| `/done` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Mark to do as done. | +| `/draft` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Toggle the draft status. | +| `/due <date>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set due date. Examples of valid `<date>` include `in 2 days`, `this Friday` and `December 31st`. | +| `/duplicate <#issue>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Close this issue and mark as a duplicate of another issue. **(FREE)** Also, mark both as related. | +| `/epic <epic>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add to epic `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. | +| `/estimate <time>` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set time estimate. For example, `/estimate 1mo 2w 3d 4h 5m`. Learn more about [time tracking](time_tracking.md). | +| `/health_status <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set [health status](issues/managing_issues.md#health-status). Valid options for `<value>` are `on_track`, `needs_attention`, and `at_risk` ([introduced in GitLab 14.7](https://gitlab.com/gitlab-org/gitlab/-/issues/213814)). | +| `/invite_email email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add up to six email participants. This action is behind feature flag `issue_email_participants` and is not yet supported in issue templates. | +| `/iteration *iteration:"iteration name"` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set iteration. For example, to set the `Late in July` iteration: `/iteration *iteration:"Late in July"` ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add one or more labels. Label names can also start without a tilde (`~`), but mixed syntax is not supported. | +| `/lock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Lock the discussions. | +| `/merge` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Merge changes. Depending on the project setting, this may be [when the pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md), or adding to a [Merge Train](../../ci/pipelines/merge_trains.md). | +| `/milestone %milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Set milestone. | +| `/move <path/to/project>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Move this issue to another project. | +| `/parent_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Set parent epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | +| `/promote` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to epic. | +| `/promote_to_incident` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Promote issue to incident ([introduced in GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/issues/296787)). | +| `/publish` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Publish issue to an associated [Status Page](../../operations/incident_management/status_page.md) ([Introduced in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30906)) | +| `/reassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Replace current assignees with those specified. | +| `/reassign_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Replace current reviewers with those specified. | +| `/rebase` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Rebase source branch. This schedules a background task that attempts to rebase the changes in the source branch on the latest commit of the target branch. If `/rebase` is used, `/merge` is ignored to avoid a race condition where the source branch is merged or deleted before it is rebased. If there are merge conflicts, GitLab displays a message that a rebase cannot be scheduled. Rebase failures are displayed with the merge request status. | +| `/relabel ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Replace current labels with those specified. | +| `/relate #issue1 #issue2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Mark issues as related. | +| `/remove_child_epic <epic>` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/7330)). | +| `/remove_contacts email1 email2` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove one or more [CRM contacts](../crm/index.md) ([introduced in GitLab 14.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73413)). | +| `/remove_due_date` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove due date. | +| `/remove_epic` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove from epic. | +| `/remove_estimate` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time estimate. | +| `/remove_iteration` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove iteration ([introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/196795)). | +| `/remove_milestone` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove milestone. | +| `/remove_parent_epic` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | Remove parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab/-/issues/10556)). | +| `/remove_time_spent` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove time spent. | +| `/remove_zoom` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Remove Zoom meeting from this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | +| `/reopen` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Reopen. | +| `/severity <severity>` | **{check-circle}** Yes | **{check-circle}** No | **{check-circle}** No | Set the severity. Options for `<severity>` are `S1` ... `S4`, `critical`, `high`, `medium`, `low`, `unknown`. [Introduced in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/334045). | +| `/shrug <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `¯\＿(ツ)＿/¯`. | +| `/spend <time> [<date>]` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Add or subtract spent time. Optionally, specify the date that time was spent on. For example, `/spend 1mo 2w 3d 4h 5m 2018-08-26` or `/spend -1h 30m`. Learn more about [time tracking](time_tracking.md). | +| `/submit_review` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Submit a pending review ([introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/8041)). | +| `/subscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Subscribe to notifications. | +| `/tableflip <comment>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Append the comment with `(╯°□°)╯︵ ┻━┻`. | +| `/target_branch <local branch name>` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Set target branch. | +| `/title <new title>` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Change title. | +| `/todo` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Add a to-do item. | +| `/unapprove` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Unapprove the merge request. ([introduced in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/8103) | +| `/unassign @user1 @user2` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific assignees. | +| `/unassign` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all assignees. | +| `/unassign_reviewer @user1 @user2` or `/remove_reviewer @user1 @user2` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove specific reviewers. | +| `/unassign_reviewer` or `/remove_reviewer` | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | Remove all reviewers. | +| `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove specified labels. | +| `/unlabel` or `/remove_label` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Remove all labels. | +| `/unlock` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | Unlock the discussions. | +| `/unsubscribe` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | Unsubscribe from notifications. | +| `/weight <value>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Set weight. Valid options for `<value>` include `0`, `1`, `2`, and so on. | +| `/zoom <Zoom URL>` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | Add Zoom meeting to this issue ([introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16609)). | ## Commit messages diff --git a/doc/user/project/releases/img/feature_count_v14_6.png b/doc/user/project/releases/img/feature_count_v14_6.png Binary files differindex 0b1a0552631..f254ff4c78a 100644 --- a/doc/user/project/releases/img/feature_count_v14_6.png +++ b/doc/user/project/releases/img/feature_count_v14_6.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 239e6c9cea8..747b41d07f2 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Releases **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. - In GitLab, a release enables you to create a snapshot of your project for your users, including installation packages and release notes. You can create a GitLab release on any branch. Creating a release also creates a [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to mark the @@ -134,6 +132,10 @@ release creation, the release job fails. To create a release when you push a Git tag, or when you add a Git tag in the UI by going to **Repository > Tags**: +NOTE: +Do not provide **Release notes** when you create the Git tag in the UI. +Providing release notes creates a release, resulting in the pipeline failing. + ```yaml release_job: stage: release @@ -829,3 +831,7 @@ Make sure that the user or a service/bot account is allowed to [create the protected tag](../protected_tags.md#configuring-protected-tags) too. See [the release permissions](#release-permissions) for more information. + +### Note about storage + +Note that the feature is built on top of Git tags, so virtually no extra data is needed besides to create the release itself. Additional assets and the release evidence that is automatically generated consume storage. diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 27767f8d325..0c5c0d5fa7c 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -1,15 +1,11 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" -type: concepts, howto +info: To 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 commits with GPG **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9546) in GitLab 9.5. -> - Subkeys support was added in GitLab 10.1. - You can use a GPG key to sign Git commits made in a GitLab repository. Signed commits are labeled **Verified** if the identity of the committer can be verified. To verify the identity of a committer, GitLab requires their public diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 54e9470892c..6ece6e3e4e0 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -2,7 +2,6 @@ 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/#assignments -type: concepts, howto --- # Repository **(FREE)** @@ -66,8 +65,6 @@ Alternatively, you can clone directly into a code editor. ### Clone and open in Apple Xcode -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45820) in GitLab 11.0. - Projects that contain a `.xcodeproj` or `.xcworkspace` directory can be cloned into Xcode on macOS. @@ -98,8 +95,7 @@ Visual Studio Code: ## Download the code in a repository -> - Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/24704) in GitLab 11.11. -> - Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. +> Support for [including Git LFS blobs](../../../topics/git/lfs#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. You can download the source code that's stored in a repository. diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index d040cc93876..5646f478d9f 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,10 +25,10 @@ GitLab. ## Cleaner diffs -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/epics/6589) in GitLab 14.5 [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Disabled by default. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. On GitLab.com, this feature is available. When commits include changes to Jupyter Notebook files, GitLab: diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 361c0902ebf..c8950d39f28 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -213,7 +213,7 @@ used in commits. To fix this problem, either: ### Deadline Exceeded -When upgrading to GitLab 11.11.8 or later, a change in how usernames are represented means that you +When upgrading GitLab, a change in how usernames are represented means that you must update your mirroring username and password to ensure that `%40` characters are replaced with `@`. ### Connection blocked because server only allows public key authentication diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index 498b8d063a9..221616bd41c 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -79,7 +79,7 @@ To configure a mirror from GitLab to GitHub: 1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `public_repo` selected. 1. Enter a **Git repository URL** with this format: - `https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git`. + `https://<your_access_token>@github.com/<github_group>/<github_project>.git`. 1. For **Password**, enter your GitHub personal access token. 1. Select **Mirror repository**. 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 0094e0b1b15..23cead7e8a7 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 @@ -127,7 +127,8 @@ To purge files from a GitLab repository: Refer to the Git [`replace`](https://git-scm.com/book/en/v2/Git-Tools-Replace) documentation for information on how this works. -1. Run a [repository cleanup](#repository-cleanup). +1. Wait at least 30 minutes, because the repository cleanup process only processes object older than 30 minutes. +1. Run [repository cleanup](#repository-cleanup). ## Repository cleanup diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index ba105a970a7..4165c1828cc 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -2,7 +2,6 @@ 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 -type: howto --- # GitLab Web Editor **(FREE)** @@ -118,8 +117,6 @@ There are multiple ways to create a branch from the GitLab web interface. ### Create a new branch from an issue -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2808) in GitLab 8.6. - If your development workflow requires an issue for every merge request, you can create a branch directly from the issue to speed the process up. The new branch, and later its merge request, are marked as related to this issue. diff --git a/doc/user/project/requirements/index.md b/doc/user/project/requirements/index.md index 294e493dfe9..5fe0e0ef3a2 100644 --- a/doc/user/project/requirements/index.md +++ b/doc/user/project/requirements/index.md @@ -17,10 +17,6 @@ In 14.4, Requirements was moved under **Issues**. With requirements, you can set criteria to check your products against. They can be based on users, stakeholders, system, software, or anything else you find important to capture. -INFO: -Meet your compliance needs with requirements in GitLab. -[Try Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-project-requirements-docs). - A requirement is an artifact in GitLab which describes the specific behavior of your product. Requirements are long-lived and don't disappear unless manually cleared. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index 072d685bde4..1b30f14ac90 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -184,9 +184,10 @@ NOTE: On GitLab.com a custom mailbox is already configured with `contact-project+%{key}@incoming.gitlab.com` as the email address, you can still configure the [custom suffix](#configuring-a-custom-email-address-suffix) in project settings. -Using the `service_desk_email` configuration, you can customize the mailbox -used by Service Desk. This allows you to have a separate email address for -Service Desk by also configuring a [custom suffix](#configuring-a-custom-email-address-suffix) +Service Desk uses the [incoming email](../../administration/incoming_email.md) +configuration by default. However, by using the `service_desk_email` configuration, +you can customize the mailbox used by Service Desk. This allows you to have +a separate email address for Service Desk by also configuring a [custom suffix](#configuring-a-custom-email-address-suffix) in project settings. The `address` must include the `+%{key}` placeholder within the 'user' @@ -194,10 +195,10 @@ portion of the address, before the `@`. This is used to identify the project where the issue should be created. NOTE: -The `service_desk_email` and `incoming_email` configurations should -always use separate mailboxes. This is important, because emails picked from -`service_desk_email` mailbox are processed by a different worker and it would -not recognize `incoming_email` emails. +When configuring a custom mailbox, the `service_desk_email` and `incoming_email` +configurations must always use separate mailboxes. This is important, because +emails picked from `service_desk_email` mailbox are processed by a different +worker and it would not recognize `incoming_email` emails. To configure a custom mailbox for Service Desk with IMAP, add the following snippets to your configuration file in full: diff --git a/doc/user/project/settings/img/import_export_download_export.png b/doc/user/project/settings/img/import_export_download_export.png Binary files differdeleted file mode 100644 index 62292e99e8e..00000000000 --- a/doc/user/project/settings/img/import_export_download_export.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_export_button.png b/doc/user/project/settings/img/import_export_export_button.png Binary files differdeleted file mode 100644 index 6f3663d64e8..00000000000 --- a/doc/user/project/settings/img/import_export_export_button.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_mail_link.png b/doc/user/project/settings/img/import_export_mail_link.png Binary files differdeleted file mode 100644 index 1bd9a071178..00000000000 --- a/doc/user/project/settings/img/import_export_mail_link.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_new_project.png b/doc/user/project/settings/img/import_export_new_project.png Binary files differdeleted file mode 100644 index 0e2365ecb68..00000000000 --- a/doc/user/project/settings/img/import_export_new_project.png +++ /dev/null diff --git a/doc/user/project/settings/img/import_export_select_file.png b/doc/user/project/settings/img/import_export_select_file.png Binary files differdeleted file mode 100644 index 90a3e8d5c4e..00000000000 --- a/doc/user/project/settings/img/import_export_select_file.png +++ /dev/null diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index da0336d01ff..06bdf4ca14b 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -6,129 +6,69 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Project import/export **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. -> - From GitLab 10.0, administrators can disable the project export option on the GitLab instance. +Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and +then imported into a new GitLab instance. -Existing projects running on any GitLab instance or GitLab.com can be exported with all their related -data and be moved into a new GitLab instance. +## Set up project import/export -The **GitLab import/export** button is displayed if the project import option is enabled. +Before you can import or export a project and its data, you must set it up. -See also: +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility and access controls**. +1. Scroll to **Import sources**. +1. Enable the desired **Import sources**. -- [Project import/export API](../../../api/project_import_export.md) -- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** -- [Group import/export](../../group/settings/import_export.md) -- [Group import/export API](../../../api/group_import_export.md) - -To set up a project import/export: - - 1. On the top bar, go to **Menu > Admin > Settings > General > Visibility and access controls**. - 1. Scroll to **Import sources**. - 1. Enable the desired **Import sources**. - -## Important notes - -Note the following: - -- Before you can import a project, you must export the data first. - See [Export a project and its data](#export-a-project-and-its-data) - for how you can export a project through the UI. -- Imports from a newer version of GitLab are not supported. - The Importing GitLab version must be greater than or equal to the Exporting GitLab version. -- Imports fail unless the import and export GitLab instances are - compatible as described in the [Version history](#version-history). -- Exports are generated in your configured `shared_path`, a temporary shared directory, - and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files. -- Group members are exported as project members, as long as the user has - a maintainer or administrator role in the group where the exported project lives. -- Project members with the [Owner role](../../permissions.md) are imported as Maintainers. -- Imported users can be mapped by their public email on self-managed instances, if an administrative user (not an owner) does the import. - The public email is not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) - for mapping to work correctly. Additionally, the user must be an existing member of the namespace, - or the user can be added as a member of the project for contributions to be mapped. - Otherwise, a supplementary comment is left to mention that the original author and - the MRs, notes, or issues are owned by the importer. - - For project migration imports performed over GitLab.com Groups, preserving author information is - possible through a [professional services engagement](https://about.gitlab.com/services/migration/). -- If an imported project contains merge requests originating from forks, - then new branches associated with such merge requests are created - in 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 must recreate this association by first enabling these deploy keys in your - imported project and then updating your protected branches accordingly. - -## Version history - -### 14.0+ - -In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a -transitional period, you can still import any JSON exports. The new format for imports and exports -is NDJSON. +## Between CE and EE -### 13.0+ +You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) +and vice versa. This assumes [version history](#version-history) +requirements are met. -Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. -This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) -releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). +If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose +data that is retained only in the Enterprise Edition. For more information, see +[downgrading from EE to CE](../../../index.md). -For example: +## Export a project and its data -| Current version | Can import bundles exported from | -|-----------------|----------------------------------| -| 13.0 | 13.0, 12.10, 12.9 | -| 13.1 | 13.1, 13.0, 12.10 | +Before you can import a project, you must export it. -### 12.x +Prerequisites: -Prior to 13.0 this was a defined compatibility table: +- Review the list of [data that will be exported](#items-that-are-exported). + Not all data is exported. +- You must have at least the Maintainer role for the project. -| Exporting GitLab version | Importing GitLab version | -| -------------------------- | -------------------------- | -| 11.7 to 12.10 | 11.7 to 12.10 | -| 11.1 to 11.6 | 11.1 to 11.6 | -| 10.8 to 11.0 | 10.8 to 11.0 | -| 10.4 to 10.7 | 10.4 to 10.7 | -| 10.3 | 10.3 | -| 10.0 to 10.2 | 10.0 to 10.2 | -| 9.4 to 9.6 | 9.4 to 9.6 | -| 9.2 to 9.3 | 9.2 to 9.3 | -| 8.17 to 9.1 | 8.17 to 9.1 | -| 8.13 to 8.16 | 8.13 to 8.16 | -| 8.12 | 8.12 | -| 8.10.3 to 8.11 | 8.10.3 to 8.11 | -| 8.10.0 to 8.10.2 | 8.10.0 to 8.10.2 | -| 8.9.5 to 8.9.11 | 8.9.5 to 8.9.11 | -| 8.9.0 to 8.9.4 | 8.9.0 to 8.9.4 | - -Projects can be exported and imported only between versions of GitLab with matching Import/Export versions. - -For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) -and the exports between them are compatible. - -## Between CE and EE +To export a project and its data, follow these steps: -You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa. -This assumes [version history](#version-history) requirements are met. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings**. +1. Expand **Advanced**. +1. Select **Export project**. +1. After the export is generated, you should receive an email with a link to download the file. +1. Alternatively, you can come back to the project settings and download the file from there or + generate a new export. After the file is available, the page should show the **Download export** + button. -If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../index.md). +The export is generated in your configured `shared_path`, a temporary shared directory, and then +moved to your configured `uploads_directory`. Every 24 hours, a worker deletes these export files. -## Exported contents +### Items that are exported The following items are exported: - Project and wiki repositories - Project uploads - Project configuration, excluding integrations -- Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, time tracking, - and other project entities +- Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, time + tracking, and other project entities - Design Management files and data - LFS objects - Issue boards - Pipelines history - Push Rules - Awards +- Group members are exported as project members, as long as the user has the Maintainer role in the + exported project's group, or is an administrator The following items are **not** exported: @@ -140,6 +80,7 @@ The following items are **not** exported: - Any encrypted tokens - Merge Request Approvers - Repository size limits +- Deploy keys allowed to push to protected branches These content rules also apply to creating projects from templates on the [group](../../group/custom_project_templates.md) @@ -150,87 +91,146 @@ 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. -## Export a project and its data - -Full project export functionality is limited to project maintainers and owners. -You can configure such functionality through [project settings](index.md): - -To export a project and its data, follow these steps: +## Import a project and its data -1. Go to your project's homepage. +> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. -1. Select **Settings** in the sidebar. +WARNING: +Only import projects from sources you trust. If you import a project from an untrusted source, it +may be possible for an attacker to steal your sensitive data. -1. Scroll down and expand the **Advanced** section. +Prerequisites: -1. Scroll down to find the **Export project** button: +- You must have [exported the project and its data](#export-a-project-and-its-data). +- Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later + than the GitLab version you exported to. +- Review the [Version history](#version-history) + for compatibility issues. -  +To import a project: -1. After the export is generated, you should receive an email with a link to - download the file: +1. When [creating a new project](../working_with_projects.md#create-a-project), + select **Import project**. +1. In **Import project from**, select **GitLab export**. +1. Enter your project name and URL. Then select the file you exported previously. +1. Select **Import project** to begin importing. Your newly imported project page appears shortly. -  +To get the status of an import, you can query it through the [Project import/export API](../../../api/project_import_export.md#import-status). +As described in the API documentation, the query may return an import error or exceptions. -1. Alternatively, you can come back to the project settings and download the - file from there, or generate a new export. After the file is available, the page - should show the **Download export** button: +### Items that are imported -  +The following items are imported but changed slightly: -## Import the project +- Project members with the [Owner role](../../permissions.md) + are imported as Maintainers. +- If an imported project contains merge requests originating from forks, then new branches + associated with such merge requests are created in a project during the import/export. Thus, the + number of branches in the exported project might be bigger than in the original project. +- If use of the `Internal` visibility level + [is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), + all imported projects are given `Private` visibility. -> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. +Deploy keys aren't imported. To use deploy keys, you must enable them in your imported project and update protected branches. -WARNING: -Only import projects from sources you trust. If you import a project from an untrusted source, it -may be possible for an attacker to steal your sensitive data. +### Import large projects **(FREE SELF)** -1. The GitLab project import feature is the first import option when creating a - new project. Select **GitLab export**: +If you have a larger project, consider using a Rake task as described in the [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). -  +## Automate group and project import **(PREMIUM)** -1. Enter your project name and URL. Then select the file you exported previously: +For information on automating user, group, and project import API calls, see +[Automate group and project import](../import/index.md#automate-group-and-project-import). -  +## Maximum import file size -1. Select **Import project** to begin importing. Your newly imported project - page appears shortly. +Administrators can set the maximum import file size one of two ways: -NOTE: -If use of the `Internal` visibility level -[is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), -all imported projects are given the visibility of `Private`. +- With the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings). +- In the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md#max-import-size). -The maximum import file size can be set by the Administrator, and the default is `0` (unlimited). -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). +The default is `0` (unlimited). -### Project import status +## Map users for import -You can query an import through the [Project import/export API](../../../api/project_import_export.md#import-status). -As described in the API documentation, the query may return an import error or exceptions. +Imported users can be mapped by their public email addresses on self-managed instances, if an administrator (not an owner) does the import. -### Import large projects **(FREE SELF)** +- Public email addresses are not set by default. Users must +[set it in their profiles](../../profile/index.md#set-your-public-email) +for mapping to work correctly. +- For contributions to be mapped correctly, users must be an existing member of the namespace, + or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues that are owned by the importer. -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). +For project migration imports performed over GitLab.com groups, preserving author information is +possible through a [professional services engagement](https://about.gitlab.com/services/migration/). ## Rate Limits To help avoid abuse, by default, 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 | 6 projects per minute | +| Download export | 1 download per group per minute | +| Import | 6 projects per minute | -GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. +GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) +from the defaults. -## Automate group and project import **(PREMIUM)** +## Version history -For information on automating user, group, and project import API calls, see -[Automate group and project import](../import/index.md#automate-group-and-project-import). +### 14.0+ + +In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a +transitional period, you can still import any JSON exports. The new format for imports and exports +is NDJSON. + +### 13.0+ + +Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. +This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) +releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Current version | Can import bundles exported from | +|-----------------|----------------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + +### 12.x + +Prior to 13.0 this was a defined compatibility table: + +| Exporting GitLab version | Importing GitLab version | +| -------------------------- | -------------------------- | +| 11.7 to 12.10 | 11.7 to 12.10 | +| 11.1 to 11.6 | 11.1 to 11.6 | +| 10.8 to 11.0 | 10.8 to 11.0 | +| 10.4 to 10.7 | 10.4 to 10.7 | +| 10.3 | 10.3 | +| 10.0 to 10.2 | 10.0 to 10.2 | +| 9.4 to 9.6 | 9.4 to 9.6 | +| 9.2 to 9.3 | 9.2 to 9.3 | +| 8.17 to 9.1 | 8.17 to 9.1 | +| 8.13 to 8.16 | 8.13 to 8.16 | +| 8.12 | 8.12 | +| 8.10.3 to 8.11 | 8.10.3 to 8.11 | +| 8.10.0 to 8.10.2 | 8.10.0 to 8.10.2 | +| 8.9.5 to 8.9.11 | 8.9.5 to 8.9.11 | +| 8.9.0 to 8.9.4 | 8.9.0 to 8.9.4 | + +Projects can be exported and imported only between versions of GitLab with matching Import/Export versions. + +For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) +and the exports between them are compatible. + +## Related topics + +- [Project import/export API](../../../api/project_import_export.md) +- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** +- [Group import/export](../../group/settings/import_export.md) +- [Group import/export API](../../../api/group_import_export.md) ## Troubleshooting @@ -245,7 +245,7 @@ Review [issue 276930](https://gitlab.com/gitlab-org/gitlab/-/issues/276930), and ### Import workarounds for large repositories -[Maximum import size limitations](#import-the-project) +[Maximum import size limitations](#import-a-project-and-its-data) can prevent an import from being successful. If changing the import limits is not possible, you can try one of the workarounds listed here. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index c6cbd45a6ab..9df545b52ec 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -86,12 +86,17 @@ read-only view to discourage this behavior. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300324) in GitLab 13.11. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/331231) in GitLab 14.2. -Group owners can use compliance pipeline configuration to add additional pipeline configuration to -projects to define compliance requirements such as scans or tests. - -[Compliance frameworks](#compliance-frameworks) allow group owners to specify the location of -compliance pipeline configuration stored and managed in dedicated projects, separate from regular -projects. +Compliance framework pipelines allow group owners to define +a compliance pipeline in a separate repository that gets +executed in place of the local project's `gitlab-ci.yml` file. As part of this pipeline, an +`include` statement can reference the local project's `gitlab-ci.yml` file. This way, the two CI +files are merged together any time the pipeline runs. Jobs and variables defined in the compliance +pipeline can't be changed by variables in the local project's `gitlab-ci.yml` file. + +When used to enforce scan execution, this feature has some overlap with [scan execution policies](../../application_security/policies/#scan-execution-policies), +as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). +For details on the similarities and differences between these features, see +[Enforce scan execution](../../application_security/#enforce-scan-execution). When you set up the compliance framework, use the **Compliance pipeline configuration** box to link the compliance framework to specific CI/CD configuration. Use the @@ -178,8 +183,6 @@ include: # Execute individual project's configuration (if project contains .git project: '$CI_PROJECT_PATH' file: '$CI_CONFIG_PATH' ref: '$CI_COMMIT_REF_NAME' # Must be defined or MR pipelines always use the use default branch - rules: - - exists: '$CI_CONFIG_PATH' ``` ##### Ensure compliance jobs are always run @@ -265,7 +268,7 @@ Some features depend on others: - If you disable the **Issues** option, GitLab also removes the following features: - - **issue boards** + - **Issue Boards** - [**Service Desk**](#service-desk) NOTE: @@ -324,7 +327,7 @@ Enable [Service Desk](../service_desk.md) for your project to offer customer sup ### Export project -Learn how to [export a project](import_export.md#import-the-project) in GitLab. +Learn how to [export a project](import_export.md#import-a-project-and-its-data) in GitLab. ### Advanced settings diff --git a/doc/user/project/settings/project_access_tokens.md b/doc/user/project/settings/project_access_tokens.md index 44ece6cb172..3fcfe202d38 100644 --- a/doc/user/project/settings/project_access_tokens.md +++ b/doc/user/project/settings/project_access_tokens.md @@ -1,6 +1,6 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -14,18 +14,19 @@ type: reference, howto You can use a project access token to authenticate: -- With the [GitLab API](../../../api/index.md#personalproject-access-tokens). +- With the [GitLab API](../../../api/index.md#personalprojectgroup-access-tokens). - With Git, when using HTTP Basic Authentication. After you configure a project access token, you don't need a password when you authenticate. Instead, you can enter any non-blank value. -Project access tokens are similar to [personal access tokens](../../profile/personal_access_tokens.md), -except they are associated with a project rather than a user. +Project access tokens are similar to [group access tokens](../../group/settings/group_access_tokens.md) +and [personal access tokens](../../profile/personal_access_tokens.md), except they are +associated with a project rather than a group or user. You can use project access tokens: -- On GitLab SaaS if you have the Premium license tier or higher. Personal access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). +- On GitLab SaaS if you have the Premium license tier or higher. Project access tokens are not available with a [trial license](https://about.gitlab.com/free-trial/). - On self-managed instances of GitLab, with any license tier. If you have the Free tier: - Review your security and compliance policies around [user self-enrollment](../../admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups). @@ -78,83 +79,11 @@ To enable or disable project access token creation for all projects in a top-lev 1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **Settings > General**. -1. Expand **Permissions, LFS, 2FA**. -1. Under **Permissions**, turn on or off **Allow project access token creation**. +1. Expand **Permissions and group features**. +1. Under **Permissions**, turn on or off **Allow project and group access token creation**. Even when creation is disabled, you can still use and revoke existing project access tokens. -## Group access tokens **(FREE SELF)** - -With group access tokens, you can use a single token to: - -- Perform actions for groups. -- Manage the projects within the group. -- In [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/330718) and later, authenticate with Git over HTTPS. - -NOTE: -You cannot use the UI to create a group access token. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/214045) -to add this functionality. This section describes a workaround. - -If you are an administrator of a self-managed GitLab instance, you can create a group access token in the -[Rails console](../../../administration/operations/rails_console.md). - -<div class="video-fallback"> - For a demo of the group access token workaround, see <a href="https://www.youtube.com/watch?v=W2fg1P1xmU0">Demo: Group Level Access Tokens</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/W2fg1P1xmU0" frameborder="0" allowfullscreen="true"> </iframe> -</figure> - -### Create a group access token - -To create a group access token: - -1. Run the following commands in a [Rails console](../../../administration/operations/rails_console.md): - - ```ruby - # Set the GitLab administration user to use. If user ID 1 is not available or is not an adinistrator, use 'admin = User.admins.first' instead to select an admininistrator. - admin = User.find(1) - - # Set the group group you want to create a token for. For example, group with ID 109. - group = Group.find(109) - - # Create the group bot user. For further group access tokens, the username should be group_#{group.id}_bot#{bot_count}. For example, group_109_bot2 and email address group_109_bot2@example.com. - bot = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot", email: "group_#{group.id}_bot@example.com", user_type: :project_bot }).execute - - # Confirm the group bot. - bot.confirm - - # Add the bot to the group with the required role. - group.add_user(bot, :maintainer) - - # Give the bot a personal access token. - token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token') - - # Get the token value. - gtoken = token.token - ``` - -1. Test if the generated group access token works: - - 1. Use the group access token in the `PRIVATE-TOKEN` header with GitLab REST APIs. For example: - - - [Create an epic](../../../api/epics.md#new-epic) in the group. - - [Create a project pipeline](../../../api/pipelines.md#create-a-new-pipeline) in one of the group's projects. - - [Create an issue](../../../api/issues.md#new-issue) in one of the group's projects. - - 1. Use the group token to [clone a group's project](../../../gitlab-basics/start-using-git.md#clone-with-https) - using HTTPS. - -### Revoke a group access token - -To revoke a group access token, run the following command in a [Rails console](../../../administration/operations/rails_console.md): - -```ruby -bot = User.find_by(username: 'group_109_bot') # the owner of the token you want to revoke -token = bot.personal_access_tokens.last # the token you want to revoke -token.revoke! -``` - ## Project bot users > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/210181) in GitLab 13.0. @@ -169,11 +98,11 @@ selected role and [scope](#scopes-for-a-project-access-token) of the project acc - The name is set to the name of the token. - The username is set to `project_{project_id}_bot` for the first access token. For example, `project_123_bot`. -- The email is set to `project{project_id}_bot@example.com`. For example, `project123_bot@example.com`. +- The email is set to `project{project_id}_bot@noreply.{Gitlab.config.gitlab.host}`. For example, `project123_bot@noreply.example.com`. - For additional access tokens in the same project, the username is set to `project_{project_id}_bot{bot_count}`. For example, `project_123_bot1`. -- For additional access tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@example.com`. - For example, `project123_bot1@example.com`. +- For additional access tokens in the same project, the email is set to `project{project_id}_bot{bot_count}@noreply.{Gitlab.config.gitlab.host}`. + For example, `project123_bot1@noreply.example.com`. API calls made with a project access token are associated with the corresponding bot user. diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md index b41ea30bfef..6ceb8c94934 100644 --- a/doc/user/project/time_tracking.md +++ b/doc/user/project/time_tracking.md @@ -76,6 +76,15 @@ For example, if you want to log 1 hour of time spent on the 31 January 2021, you would type `/spend 1h 2021-01-31`. If you supply a date in the future, the command fails and no time is logged. +To add a timelog entry with a note, create a comment with a description and the quick action. +It then shows in the timelog "Summary/Notes" column. For example: + +```plaintext +Draft MR and respond to initial comments + +/spend 30m +``` + To remove all the time spent at once, use `/remove_time_spent`. ## View a time tracking report diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 40c9ae8bd59..4565b5f1c91 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -1,17 +1,14 @@ --- 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" -type: reference, how-to +info: To 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 IDE **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. - -The Web Integrated Development Environment (IDE) editor makes it faster and easier to contribute changes to your -projects by providing an advanced editor with commit staging. +The Web Integrated Development Environment (IDE) editor streamlines the process +to contribute changes to your projects, by providing an advanced editor with +commit staging. ## Open the Web IDE @@ -36,8 +33,6 @@ and from merge requests: ## File finder -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18323) in [GitLab Free](https://about.gitlab.com/pricing/) 10.8. - The file finder allows you to quickly open files in the current branch by searching for fragments of the file path. The file finder is launched using the keyboard shortcut <kbd>Command</kbd>+<kbd>p</kbd>, <kbd>Control</kbd>+<kbd>p</kbd>, or <kbd>t</kbd> @@ -150,7 +145,7 @@ Each schema entry supports two properties: ## Configure the Web IDE -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23352) in GitLab Free 13.1. The Web IDE supports configuration of certain editor settings by using [`.editorconfig` files](https://editorconfig.org/). When opening a file, the @@ -169,12 +164,10 @@ The Web IDE currently supports the following `.editorconfig` settings: ## Commit changes -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4539) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44157) to GitLab Free in 10.7. -> - From [GitLab 12.7 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files were automatically staged. -> - From [GitLab 12.9 onward](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All your current changes necessarily have to be committed or discarded. +> - Starting with [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/33441), files are automatically staged. +> - In [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/196609), support for staging files was removed to prevent loss of unstaged data. All of your current changes must be committed or discarded. -After making your changes, click the **Commit** button on the bottom-left to +After making your changes, select **Commit** on the bottom-left to review the list of changed files. After you have finalized your changes, you can add a commit message, commit the @@ -182,8 +175,8 @@ changes and directly create a merge request. In case you don't have write access to the selected branch, you see a warning, but can still create a new branch and start a merge request. -To discard a change in a particular file, click the **Discard changes** button on that -file in the changes tab. To discard all the changes, click the trash icon on the +To discard a change in a particular file, select **Discard changes** on that +file in the changes tab. To discard all the changes, select the trash icon on the top-right corner of the changes sidebar.  @@ -198,8 +191,6 @@ shows you a preview of the merge request diff if you commit your changes. ## View CI job logs -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19279) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. - You can use the Web IDE to quickly fix failing tests by opening the branch or merge request in the Web IDE and opening the logs of the failed job. You can access the status of all jobs for the most recent pipeline and job @@ -211,16 +202,12 @@ left. ## Switching merge requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19318) in [GitLab Free](https://about.gitlab.com/pricing/) 11.0. - To switch between your authored and assigned merge requests, click the dropdown in the top of the sidebar to open a list of merge requests. You must commit or discard all your changes before switching to a different merge request. ## Switching branches -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20850) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. - To switch between branches of the current project repository, click the dropdown in the top of the sidebar to open a list of branches. You must commit or discard all your changes before switching to a @@ -228,9 +215,8 @@ different branch. ## Markdown editing -> - Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18059) in [GitLab Free](https://about.gitlab.com/pricing/) 10.7. -> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in [GitLab Free](https://about.gitlab.com/pricing/) 13.1. -> - Side-by-side Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68274) in [GitLab Free](https://about.gitlab.com/pricing/) 14.3 +> - Support for pasting images [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22822) in GitLab Free 13.1. +> - Side-by-side Markdown preview [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68274) in GitLab Free 14.3. To edit Markdown files in the Web IDE: @@ -255,8 +241,7 @@ There are two ways to preview Markdown content in the Web IDE: ## Live Preview -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Free](https://about.gitlab.com/pricing/) 11.2. -> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. +> [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. You can use the Web IDE to preview JavaScript projects right in the browser. This feature uses CodeSandbox to compile and bundle the JavaScript used to @@ -301,8 +286,7 @@ An example `package.json`: ## Interactive Web Terminals for the Web IDE -> - [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 Free in 13.1. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211685) to GitLab Free in 13.1. WARNING: Interactive Web Terminals for the Web IDE is currently in **Beta**. @@ -407,8 +391,8 @@ click **Restart Terminal** to start a new terminal session. ### File syncing to web terminal -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) to GitLab Free in 13.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5276) in GitLab Ultimate 12.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/211686) from GitLab Ultimate to GitLab Free in 13.1. 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 diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 9f1670d3f4c..95ea1b4d0bc 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -1,8 +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/#assignments" -type: reference, how-to +info: To 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 **(FREE)** @@ -87,11 +86,7 @@ Users with the [Developer role](../../permissions.md) can create new wiki pages: [special characters](#special-characters-in-page-titles) for subdirectories and formatting, and have [length restrictions](#length-restrictions-for-file-and-directory-names). 1. Add content to your wiki page. -1. Optional. Attach a file, and GitLab stores it according to your installed version of GitLab: - - *Files added in [GitLab 11.3 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/33475):* - Files are stored in the wiki's Git repository. - - *Files added GitLab 11.2 and earlier:* Files are stored in GitLab itself. To add - the file to the wiki's Git repository, you must re-upload the file. +1. Optional. Attach a file, and GitLab stores it in the wiki's Git repository. 1. Add a **Commit message**. Git requires a commit message, so GitLab creates one if you don't enter one yourself. 1. Select **Create page**. @@ -227,9 +222,9 @@ You can see the changes made in a version of a wiki page, similar to versioned d ## Track wiki events -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in **GitLab 12.10.** -> - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in **GitLab 13.0.** -> - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in **GitLab 13.5** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14902) in GitLab 12.10. +> - Git events were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216014) in GitLab 13.0. +> - [Feature flag for Git events was removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258665) in GitLab 13.5. GitLab tracks wiki creation, deletion, and update events. These events are displayed on these pages: diff --git a/doc/user/project/working_with_projects.md b/doc/user/project/working_with_projects.md index b5b3f2d2085..61eca19a67b 100644 --- a/doc/user/project/working_with_projects.md +++ b/doc/user/project/working_with_projects.md @@ -16,7 +16,7 @@ To explore projects: 1. On the top bar, select **Menu > Projects**. 1. Select **Explore projects**. -The **Projects** page shows a list of projects, sorted by last updated date. +The **Projects** page shows a list of projects, sorted by last updated date. - To view projects with the most [stars](#star-a-project), select **Most stars**. - To view projects with the largest number of comments in the past month, select **Trending**. @@ -326,7 +326,7 @@ on the project dashboard when a project is part of a group under a Prerequisites: - Contact your administrator to enable the [GitLab Go Proxy](../packages/go_proxy/index.md). -- To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause +- To use a private project in a subgroup as a Go package, you must [authenticate Go requests](#authenticate-go-requests-to-private-projects). Go requests that are not authenticated cause `go get` to fail. You don't need to authenticate Go requests for projects that are not in subgroups. To use a project as a Go package, use the `go get` and `godoc.org` discovery requests. You can use the meta tags: diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md index b9c45bce43a..13fba126169 100644 --- a/doc/user/search/advanced_search.md +++ b/doc/user/search/advanced_search.md @@ -14,10 +14,6 @@ This is the user documentation. To configure the Advanced Search, visit the [administrator documentation](../../integration/elasticsearch.md). Advanced Search is enabled in GitLab.com. -INFO: -Get advanced search and more with a -[free 30-day trial of GitLab Ultimate](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=p-advanced-search-docs). - GitLab Advanced Search expands on the Basic Search with an additional set of features for faster, more advanced searches across the entire GitLab instance when searching in: diff --git a/doc/user/search/img/code_search.png b/doc/user/search/img/code_search.png Binary files differnew file mode 100644 index 00000000000..7c62bb6921b --- /dev/null +++ b/doc/user/search/img/code_search.png diff --git a/doc/user/search/img/project_code_search.png b/doc/user/search/img/project_code_search.png Binary files differdeleted file mode 100644 index 5412f614a74..00000000000 --- a/doc/user/search/img/project_code_search.png +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index aa4950cfa33..0e2be455a0c 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -1,8 +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/#assignments" -type: index, reference, howto +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Searching in GitLab **(FREE)** @@ -102,8 +101,7 @@ You can filter the **Issues** list to individual instances by their ID. For exam ### Filtering merge requests by approvers **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9468) in GitLab 11.9. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. To filter merge requests by an individual approver, you can type (or select from the dropdown) **Approver** and select the user. @@ -143,7 +141,7 @@ you can choose from:  -When filtering by `Deployed-before` or `Deployed-after`, the date refers to when +When filtering by `Deployed-before` or `Deployed-after`, the date refers to when the deployment to an environment (triggered by the merge commit) completed successfully. You must enter the deploy date manually. Deploy dates use the format `YYYY-MM-DD`, and must be quoted if you wish to specify @@ -272,8 +270,10 @@ search, or choose a specific group or project. To search through code or other documents in a single project, you can use the search field on the top-right of your screen while the project page is open. +Code search shows only the first result in the file. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327052) +in GitLab 14.7, you can access Git blame from any line that returned a result from the code search: - + ### SHA search |
