From a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Wed, 16 Jun 2021 18:25:58 +0000 Subject: Add latest changes from gitlab-org/gitlab@14-0-stable-ee --- doc/user/abuse_reports.md | 1 + doc/user/admin_area/abuse_reports.md | 1 + .../admin_area/activating_deactivating_users.md | 1 + doc/user/admin_area/analytics/dev_ops_report.md | 61 +- .../analytics/img/admin_devops_adoption_v14_0.png | Bin 0 -> 52947 bytes .../instance_activity_pipelines_chart_v13_6_a.png | Bin 92540 -> 30831 bytes doc/user/admin_area/analytics/index.md | 15 +- doc/user/admin_area/analytics/usage_trends.md | 2 +- doc/user/admin_area/analytics/user_cohorts.md | 1 + doc/user/admin_area/appearance.md | 6 +- doc/user/admin_area/approving_users.md | 8 +- doc/user/admin_area/blocking_unblocking_users.md | 1 + doc/user/admin_area/broadcast_messages.md | 79 +-- doc/user/admin_area/credentials_inventory.md | 9 +- doc/user/admin_area/custom_project_templates.md | 10 +- doc/user/admin_area/diff_limits.md | 32 +- doc/user/admin_area/geo_nodes.md | 2 +- doc/user/admin_area/img/cohorts_v13_9_a.png | Bin 122096 -> 35297 bytes doc/user/admin_area/index.md | 60 +- doc/user/admin_area/license.md | 14 +- doc/user/admin_area/merge_requests_approvals.md | 4 +- doc/user/admin_area/moderate_users.md | 59 +- doc/user/admin_area/monitoring/health_check.md | 8 +- doc/user/admin_area/review_abuse_reports.md | 8 +- .../settings/account_and_limit_settings.md | 82 ++- .../admin_area/settings/continuous_integration.md | 140 ++-- .../admin_area/settings/external_authorization.md | 7 +- doc/user/admin_area/settings/floc.md | 3 +- doc/user/admin_area/settings/gitaly_timeouts.md | 8 +- doc/user/admin_area/settings/help_page.md | 6 +- .../settings/img/admin_required_pipeline.png | Bin 22587 -> 0 bytes ...ous_integration_shared_runner_details_v14_0.png | Bin 0 -> 80106 bytes .../settings/img/custom_sign_in_page_v13_6.png | Bin 61203 -> 0 bytes doc/user/admin_area/settings/img/enforce_terms.png | Bin 54881 -> 156968 bytes .../settings/import_export_rate_limits.md | 4 +- doc/user/admin_area/settings/index.md | 22 +- .../settings/instance_template_repository.md | 13 +- .../settings/package_registry_rate_limits.md | 5 +- .../settings/project_integration_management.md | 6 +- .../settings/push_event_activities_limit.md | 13 +- .../settings/rate_limit_on_notes_creation.md | 2 +- .../settings/rate_limits_on_raw_endpoints.md | 7 +- .../admin_area/settings/sign_in_restrictions.md | 16 +- .../admin_area/settings/sign_up_restrictions.md | 18 +- doc/user/admin_area/settings/terms.md | 5 +- doc/user/admin_area/settings/third_party_offers.md | 6 +- doc/user/admin_area/settings/usage_statistics.md | 16 +- .../admin_area/settings/user_and_ip_rate_limits.md | 15 +- .../settings/visibility_and_access_controls.md | 12 +- doc/user/admin_area/user_cohorts.md | 6 +- doc/user/analytics/ci_cd_analytics.md | 25 +- doc/user/analytics/index.md | 2 +- doc/user/analytics/value_stream_analytics.md | 132 ++-- .../api_fuzzing/create_har_files.md | 8 +- doc/user/application_security/api_fuzzing/index.md | 69 +- .../container_scanning/index.md | 330 +++------ .../application_security/coverage_fuzzing/index.md | 4 +- doc/user/application_security/cve_id_request.md | 2 +- .../application_security/dast/browser_based.md | 75 +- .../dast/img/dast_auth_browser_scan_highlight.png | Bin 0 -> 203980 bytes .../img/dast_auth_browser_scan_search_elements.png | Bin 0 -> 155046 bytes .../dast/img/dast_auth_report.jpg | Bin 0 -> 121121 bytes doc/user/application_security/dast/index.md | 785 +++++++++++---------- doc/user/application_security/dast_api/index.md | 67 +- .../dependency_scanning/analyzers.md | 2 +- .../dependency_scanning/index.md | 12 +- ...urity_approval_rules_and_enabled_jobs_v13_4.png | Bin 35553 -> 0 bytes ...ured_security_approval_rules_and_jobs_v13_4.png | Bin 29773 -> 0 bytes doc/user/application_security/index.md | 165 ++--- .../offline_deployments/index.md | 19 +- doc/user/application_security/sast/analyzers.md | 23 +- doc/user/application_security/sast/index.md | 36 +- .../application_security/secret_detection/index.md | 16 +- .../img/security_center_settings_v13_4.png | Bin 69604 -> 23188 bytes .../security_dashboard/index.md | 3 +- doc/user/application_security/terminology/index.md | 6 +- .../threat_monitoring_policy_alert_list_v13_12.png | Bin 59862 -> 22929 bytes .../threat_monitoring/index.md | 58 +- ...ty_page_merge_request_button_dropdown_v13_1.png | Bin 53561 -> 0 bytes .../application_security/vulnerabilities/index.md | 146 ++-- .../vulnerabilities/severities.md | 7 +- .../vulnerability_report/index.md | 4 +- doc/user/clusters/agent/index.md | 4 +- doc/user/clusters/agent/repository.md | 115 ++- doc/user/clusters/agent/runner.md | 1 + doc/user/clusters/applications.md | 735 ++----------------- doc/user/clusters/cost_management.md | 8 +- doc/user/clusters/crossplane.md | 2 +- doc/user/clusters/img/fluentd_v13_0.png | Bin 32445 -> 0 bytes doc/user/clusters/integrations.md | 27 +- doc/user/clusters/management_project.md | 8 +- doc/user/clusters/management_project_template.md | 86 +++ .../migrating_from_gma_to_project_template.md | 95 +++ doc/user/compliance/license_compliance/index.md | 42 +- doc/user/discussions/index.md | 9 +- doc/user/gitlab_com/index.md | 302 +------- doc/user/group/bulk_editing/index.md | 1 + doc/user/group/clusters/index.md | 14 +- doc/user/group/custom_project_templates.md | 57 +- .../img/group_devops_adoption_v13_11.png | Bin 58389 -> 0 bytes .../img/group_devops_adoption_v14_0.png | Bin 0 -> 52890 bytes doc/user/group/devops_adoption/index.md | 26 +- doc/user/group/epics/epic_boards.md | 170 ++++- doc/user/group/epics/img/epic_board_v13_10.png | Bin 42037 -> 0 bytes doc/user/group/epics/img/epic_board_v14_0.png | Bin 0 -> 16512 bytes doc/user/group/epics/manage_epics.md | 27 +- doc/user/group/import/index.md | 7 +- doc/user/group/index.md | 68 +- doc/user/group/insights/index.md | 2 +- .../img/issues_created_per_month_v12_8_a.png | Bin 54332 -> 16244 bytes doc/user/group/repositories_analytics/index.md | 4 +- .../saml_sso/img/member_enterprise_badge_v14_0.png | Bin 0 -> 31502 bytes .../group/saml_sso/img/saml_group_links_v13_9.png | Bin 0 -> 162931 bytes doc/user/group/saml_sso/index.md | 21 +- doc/user/group/saml_sso/scim_setup.md | 4 + doc/user/group/settings/import_export.md | 10 +- doc/user/group/subgroups/index.md | 23 +- .../img/delete_value_stream_v13_12.png | Bin 57007 -> 20164 bytes .../img/new_value_stream_v13_12.png | Bin 55481 -> 19993 bytes .../img/vsa_filter_bar_v13_12.png | Bin 125695 -> 36706 bytes .../img/vsa_label_based_stage_v14_0.png | Bin 65149 -> 19873 bytes .../img/vsa_overview_stage_v13_11.png | Bin 60960 -> 21148 bytes .../img/vsa_time_metrics_v13_12.png | Bin 51065 -> 18354 bytes doc/user/group/value_stream_analytics/index.md | 4 +- doc/user/img/completed_tasks_v13_3.png | Bin 10844 -> 14835 bytes doc/user/infrastructure/index.md | 15 +- doc/user/infrastructure/terraform_state.md | 17 +- doc/user/instance/clusters/index.md | 5 +- doc/user/markdown.md | 454 ++++++------ doc/user/operations_dashboard/index.md | 2 +- doc/user/packages/composer_repository/index.md | 4 +- doc/user/packages/conan_repository/index.md | 2 +- doc/user/packages/container_registry/index.md | 15 +- doc/user/packages/index.md | 11 +- doc/user/packages/infrastructure_registry/index.md | 93 +++ doc/user/packages/maven_repository/index.md | 15 +- doc/user/packages/npm_registry/index.md | 9 +- doc/user/packages/nuget_repository/index.md | 2 +- doc/user/packages/package_registry/index.md | 39 +- doc/user/packages/pypi_repository/index.md | 39 +- doc/user/packages/rubygems_registry/index.md | 4 +- .../packages/terraform_module_registry/index.md | 124 ++++ doc/user/packages/workflows/project_registry.md | 4 +- .../packages/workflows/working_with_monorepos.md | 64 ++ doc/user/permissions.md | 104 +-- doc/user/profile/account/create_accounts.md | 23 +- doc/user/profile/account/delete_account.md | 5 +- .../profile/account/two_factor_authentication.md | 13 +- .../img/notification_global_settings_v13_12.png | Bin 20731 -> 9268 bytes .../profile/img/unknown_sign_in_email_v13_1.png | Bin 20230 -> 0 bytes .../profile/img/unknown_sign_in_email_v14_0.png | Bin 0 -> 68946 bytes doc/user/profile/index.md | 16 +- doc/user/profile/notifications.md | 1 + doc/user/profile/unknown_sign_in_notification.md | 2 +- doc/user/project/badges.md | 31 +- doc/user/project/bulk_editing.md | 1 + doc/user/project/canary_deployments.md | 4 +- doc/user/project/clusters/add_eks_clusters.md | 13 +- doc/user/project/clusters/add_gke_clusters.md | 12 +- doc/user/project/clusters/add_remove_clusters.md | 62 +- doc/user/project/clusters/index.md | 47 +- doc/user/project/clusters/kubernetes_pod_logs.md | 24 +- .../protect/container_host_security/index.md | 6 +- .../container_host_security/quick_start_guide.md | 24 +- .../protect/container_network_security/index.md | 6 +- .../quick_start_guide.md | 34 +- doc/user/project/clusters/protect/index.md | 5 +- .../guide_waf_ingress_disabled_settings_v12_10.png | Bin 51416 -> 0 bytes .../img/guide_waf_ingress_installation_v12_10.png | Bin 44243 -> 0 bytes .../img/guide_waf_ingress_save_changes_v12_10.png | Bin 54688 -> 0 bytes .../protect/web_application_firewall/index.md | 103 --- .../web_application_firewall/quick_start_guide.md | 265 ------- doc/user/project/clusters/runbooks/index.md | 99 ++- doc/user/project/clusters/serverless/index.md | 74 +- doc/user/project/deploy_boards.md | 2 +- doc/user/project/deploy_keys/index.md | 2 +- doc/user/project/deploy_tokens/index.md | 2 +- doc/user/project/description_templates.md | 39 +- doc/user/project/file_lock.md | 8 +- doc/user/project/highlighting.md | 2 +- ...owners_approval_new_protected_branch_v13_10.png | Bin 30238 -> 0 bytes ...ode_owners_approval_protected_branch_v13_10.png | Bin 17263 -> 0 bytes doc/user/project/import/bitbucket.md | 2 +- doc/user/project/import/bitbucket_server.md | 2 +- doc/user/project/import/clearcase.md | 2 +- doc/user/project/import/cvs.md | 2 +- doc/user/project/import/fogbugz.md | 2 +- doc/user/project/import/gemnasium.md | 1 + doc/user/project/import/gitea.md | 2 +- doc/user/project/import/github.md | 2 +- doc/user/project/import/gitlab_com.md | 2 +- doc/user/project/import/index.md | 2 +- doc/user/project/import/manifest.md | 2 +- doc/user/project/import/perforce.md | 2 +- doc/user/project/import/phabricator.md | 2 +- doc/user/project/import/repo_by_url.md | 2 +- doc/user/project/import/svn.md | 6 +- doc/user/project/import/tfvc.md | 6 +- doc/user/project/index.md | 4 +- .../integrations/gitlab_slack_application.md | 2 +- doc/user/project/integrations/hipchat.md | 7 - doc/user/project/integrations/index.md | 2 +- doc/user/project/integrations/jira.md | 1 + .../integrations/jira_cloud_configuration.md | 1 + doc/user/project/integrations/jira_integrations.md | 1 + .../integrations/jira_server_configuration.md | 1 + .../integrations/mattermost_slash_commands.md | 6 +- doc/user/project/integrations/overview.md | 15 +- doc/user/project/integrations/prometheus.md | 144 +--- .../integrations/prometheus_library/kubernetes.md | 2 +- .../prometheus_library/nginx_ingress.md | 22 - .../prometheus_library/nginx_ingress_vts.md | 22 - .../project/integrations/services_templates.md | 68 +- doc/user/project/integrations/webex_teams.md | 3 +- doc/user/project/integrations/webhooks.md | 14 +- doc/user/project/issue_board.md | 199 ++++-- doc/user/project/issues/confidential_issues.md | 8 +- doc/user/project/issues/csv_export.md | 105 +-- doc/user/project/issues/csv_import.md | 2 +- doc/user/project/issues/design_management.md | 7 +- doc/user/project/issues/due_dates.md | 24 +- .../issues/img/issue_type_change_v13_12.png | Bin 0 -> 52414 bytes doc/user/project/issues/issue_data_and_actions.md | 2 +- doc/user/project/issues/managing_issues.md | 24 +- doc/user/project/labels.md | 2 +- .../img/access_requests_management_v13_9.png | Bin 24246 -> 0 bytes .../members/img/add_user_email_accept_v13_9.png | Bin 21877 -> 0 bytes .../members/img/add_user_email_ready_v13_8.png | Bin 28850 -> 0 bytes .../members/img/add_user_email_search_v13_8.png | Bin 29293 -> 0 bytes .../members/img/withdraw_access_request_button.png | Bin 28154 -> 0 bytes doc/user/project/members/index.md | 203 +++--- .../project/members/share_project_with_groups.md | 2 +- .../merge_requests/accessibility_testing.md | 12 +- .../project/merge_requests/allow_collaboration.md | 50 +- doc/user/project/merge_requests/approvals/index.md | 32 +- doc/user/project/merge_requests/approvals/rules.md | 6 +- .../project/merge_requests/approvals/settings.md | 2 +- .../authorization_for_merge_requests.md | 16 +- .../merge_requests/browser_performance_testing.md | 31 +- doc/user/project/merge_requests/changes.md | 60 +- .../project/merge_requests/cherry_pick_changes.md | 25 +- doc/user/project/merge_requests/code_quality.md | 19 +- doc/user/project/merge_requests/commits.md | 28 + .../merge_requests/creating_merge_requests.md | 3 +- doc/user/project/merge_requests/getting_started.md | 58 +- .../merge_requests/img/allow_collaboration.png | Bin 10806 -> 0 bytes .../img/allow_collaboration_after_save.png | Bin 5410 -> 0 bytes .../img/code_quality_mr_diff_report_v14.png | Bin 0 -> 54803 bytes .../merge_requests/img/commit-button_v13_12.png | Bin 0 -> 8834 bytes .../merge_requests/img/conflict_ui_v14_0.png | Bin 0 -> 8371 bytes .../merge_requests/img/merge_request_pipeline.png | Bin 0 -> 31026 bytes .../img/project_merge_requests_list_view_v13_5.png | Bin 0 -> 87738 bytes .../img/reviewer_approval_rules_form_v13_8.png | Bin 42245 -> 0 bytes .../img/reviewer_approval_rules_sidebar_v13_8.png | Bin 38840 -> 0 bytes .../img/status_checks_branches_selector_v14_0.png | Bin 0 -> 5460 bytes .../img/status_checks_create_form_v14_0.png | Bin 0 -> 11913 bytes .../img/status_checks_delete_modal_v14_0.png | Bin 0 -> 5662 bytes .../img/status_checks_list_view_v14_0.png | Bin 0 -> 15958 bytes .../img/status_checks_update_form_v14_0.png | Bin 0 -> 13348 bytes doc/user/project/merge_requests/index.md | 85 ++- .../merge_requests/load_performance_testing.md | 10 +- .../merge_requests/merge_request_approvals.md | 1 + .../merge_requests/merge_request_dependencies.md | 2 +- .../merge_requests/merge_when_pipeline_succeeds.md | 2 +- .../project/merge_requests/resolve_conflicts.md | 4 +- .../reviewing_and_managing_merge_requests.md | 1 + .../reviews/img/merge_request_pipeline.png | Bin 31026 -> 0 bytes .../img/project_merge_requests_list_view_v13_5.png | Bin 87738 -> 0 bytes .../img/reviewer_approval_rules_form_v13_8.png | Bin 0 -> 42245 bytes .../img/reviewer_approval_rules_sidebar_v13_8.png | Bin 0 -> 38840 bytes doc/user/project/merge_requests/reviews/index.md | 143 ++-- .../project/merge_requests/reviews/suggestions.md | 4 + .../project/merge_requests/squash_and_merge.md | 2 +- doc/user/project/merge_requests/status_checks.md | 179 +++++ .../merge_requests/test_coverage_visualization.md | 84 ++- .../testing_and_reports_in_merge_requests.md | 2 +- doc/user/project/merge_requests/versions.md | 2 +- doc/user/project/merge_requests/widgets.md | 64 ++ .../work_in_progress_merge_requests.md | 1 + doc/user/project/milestones/index.md | 4 +- doc/user/project/new_ci_build_permissions_model.md | 1 + .../dns_concepts.md | 2 +- .../custom_domains_ssl_tls_certification/index.md | 4 +- .../lets_encrypt_integration.md | 4 +- .../ssl_tls_concepts.md | 2 +- .../pages/getting_started/pages_ci_cd_template.md | 4 +- .../getting_started/pages_forked_sample_project.md | 2 +- .../pages/getting_started/pages_from_scratch.md | 2 +- .../getting_started/pages_new_project_template.md | 3 +- doc/user/project/pages/getting_started_part_one.md | 2 +- doc/user/project/pages/index.md | 2 +- doc/user/project/pages/introduction.md | 4 +- .../project/pages/lets_encrypt_for_gitlab_pages.md | 2 +- doc/user/project/pages/pages_access_control.md | 2 +- doc/user/project/pages/redirects.md | 2 +- doc/user/project/protected_branches.md | 40 +- doc/user/project/protected_tags.md | 2 +- doc/user/project/quick_actions.md | 1 - doc/user/project/releases/index.md | 17 +- doc/user/project/repository/branches/default.md | 3 +- .../repository/img/download_source_code.png | Bin 19681 -> 0 bytes .../repository/img/file_ext_icons_repo_v12_10.png | Bin 73624 -> 0 bytes doc/user/project/repository/index.md | 418 +++++------ .../project/repository/jupyter_notebooks/index.md | 9 +- .../project/repository/repository_mirroring.md | 46 +- doc/user/project/repository/web_editor.md | 8 +- doc/user/project/settings/import_export.md | 12 +- doc/user/project/settings/index.md | 94 ++- doc/user/project/settings/project_access_tokens.md | 2 + doc/user/project/time_tracking.md | 6 +- doc/user/project/web_ide/index.md | 26 +- doc/user/project/wiki/img/content_editor_v14.0.png | Bin 0 -> 13771 bytes .../wiki/img/use_new_editor_button_v14.0.png | Bin 0 -> 16719 bytes doc/user/project/wiki/index.md | 82 ++- doc/user/project/working_with_projects.md | 25 +- doc/user/reserved_names.md | 6 +- doc/user/search/advanced_search.md | 42 +- doc/user/search/index.md | 4 +- doc/user/shortcuts.md | 8 +- doc/user/snippets.md | 8 +- doc/user/todos.md | 1 + 321 files changed, 4543 insertions(+), 4828 deletions(-) create mode 100644 doc/user/admin_area/analytics/img/admin_devops_adoption_v14_0.png delete mode 100644 doc/user/admin_area/settings/img/admin_required_pipeline.png create mode 100644 doc/user/admin_area/settings/img/continuous_integration_shared_runner_details_v14_0.png delete mode 100644 doc/user/admin_area/settings/img/custom_sign_in_page_v13_6.png create mode 100644 doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png create mode 100644 doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png create mode 100644 doc/user/application_security/dast/img/dast_auth_report.jpg delete mode 100644 doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png delete mode 100644 doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png delete mode 100644 doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png delete mode 100644 doc/user/clusters/img/fluentd_v13_0.png create mode 100644 doc/user/clusters/management_project_template.md create mode 100644 doc/user/clusters/migrating_from_gma_to_project_template.md delete mode 100644 doc/user/group/devops_adoption/img/group_devops_adoption_v13_11.png create mode 100644 doc/user/group/devops_adoption/img/group_devops_adoption_v14_0.png delete mode 100644 doc/user/group/epics/img/epic_board_v13_10.png create mode 100644 doc/user/group/epics/img/epic_board_v14_0.png create mode 100644 doc/user/group/saml_sso/img/member_enterprise_badge_v14_0.png create mode 100644 doc/user/group/saml_sso/img/saml_group_links_v13_9.png create mode 100644 doc/user/packages/infrastructure_registry/index.md create mode 100644 doc/user/packages/terraform_module_registry/index.md create mode 100644 doc/user/packages/workflows/working_with_monorepos.md delete mode 100644 doc/user/profile/img/unknown_sign_in_email_v13_1.png create mode 100644 doc/user/profile/img/unknown_sign_in_email_v14_0.png delete mode 100644 doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png delete mode 100644 doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_installation_v12_10.png delete mode 100644 doc/user/project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png delete mode 100644 doc/user/project/clusters/protect/web_application_firewall/index.md delete mode 100644 doc/user/project/clusters/protect/web_application_firewall/quick_start_guide.md delete mode 100644 doc/user/project/img/code_owners_approval_new_protected_branch_v13_10.png delete mode 100644 doc/user/project/img/code_owners_approval_protected_branch_v13_10.png delete mode 100644 doc/user/project/integrations/hipchat.md create mode 100644 doc/user/project/issues/img/issue_type_change_v13_12.png delete mode 100644 doc/user/project/members/img/access_requests_management_v13_9.png delete mode 100644 doc/user/project/members/img/add_user_email_accept_v13_9.png delete mode 100644 doc/user/project/members/img/add_user_email_ready_v13_8.png delete mode 100644 doc/user/project/members/img/add_user_email_search_v13_8.png delete mode 100644 doc/user/project/members/img/withdraw_access_request_button.png create mode 100644 doc/user/project/merge_requests/commits.md delete mode 100644 doc/user/project/merge_requests/img/allow_collaboration.png delete mode 100644 doc/user/project/merge_requests/img/allow_collaboration_after_save.png create mode 100644 doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png create mode 100644 doc/user/project/merge_requests/img/commit-button_v13_12.png create mode 100644 doc/user/project/merge_requests/img/conflict_ui_v14_0.png create mode 100644 doc/user/project/merge_requests/img/merge_request_pipeline.png create mode 100644 doc/user/project/merge_requests/img/project_merge_requests_list_view_v13_5.png delete mode 100644 doc/user/project/merge_requests/img/reviewer_approval_rules_form_v13_8.png delete mode 100644 doc/user/project/merge_requests/img/reviewer_approval_rules_sidebar_v13_8.png create mode 100644 doc/user/project/merge_requests/img/status_checks_branches_selector_v14_0.png create mode 100644 doc/user/project/merge_requests/img/status_checks_create_form_v14_0.png create mode 100644 doc/user/project/merge_requests/img/status_checks_delete_modal_v14_0.png create mode 100644 doc/user/project/merge_requests/img/status_checks_list_view_v14_0.png create mode 100644 doc/user/project/merge_requests/img/status_checks_update_form_v14_0.png delete mode 100644 doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png delete mode 100644 doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png create mode 100644 doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_form_v13_8.png create mode 100644 doc/user/project/merge_requests/reviews/img/reviewer_approval_rules_sidebar_v13_8.png create mode 100644 doc/user/project/merge_requests/status_checks.md create mode 100644 doc/user/project/merge_requests/widgets.md delete mode 100644 doc/user/project/repository/img/download_source_code.png delete mode 100644 doc/user/project/repository/img/file_ext_icons_repo_v12_10.png create mode 100644 doc/user/project/wiki/img/content_editor_v14.0.png create mode 100644 doc/user/project/wiki/img/use_new_editor_button_v14.0.png (limited to 'doc/user') diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index 66b7c3c6ac7..c84c3541366 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -1,5 +1,6 @@ --- redirect_to: 'report_abuse.md' +remove_date: '2021-07-21' --- This file was moved to [another location](report_abuse.md). diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md index 5424d4d2cb4..4bfa277fc9f 100644 --- a/doc/user/admin_area/abuse_reports.md +++ b/doc/user/admin_area/abuse_reports.md @@ -1,5 +1,6 @@ --- redirect_to: 'review_abuse_reports.md' +remove_date: '2021-07-21' --- This file was moved to [another location](review_abuse_reports.md). diff --git a/doc/user/admin_area/activating_deactivating_users.md b/doc/user/admin_area/activating_deactivating_users.md index cafc7caf981..e89c42b34ba 100644 --- a/doc/user/admin_area/activating_deactivating_users.md +++ b/doc/user/admin_area/activating_deactivating_users.md @@ -1,5 +1,6 @@ --- redirect_to: 'moderate_users.md' +remove_date: '2021-08-12' --- This document was moved to [another location](moderate_users.md). diff --git a/doc/user/admin_area/analytics/dev_ops_report.md b/doc/user/admin_area/analytics/dev_ops_report.md index b13faf2bb3e..6ca5e5034bf 100644 --- a/doc/user/admin_area/analytics/dev_ops_report.md +++ b/doc/user/admin_area/analytics/dev_ops_report.md @@ -1,21 +1,23 @@ --- -stage: none -group: unassigned +stage: Manage +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# DevOps Report +# DevOps Report **(FREE SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30469) in GitLab 9.3. -> - [Renamed from Conversational Development Index](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) in GitLab 12.6. +> [Renamed from Conversational Development Index](https://gitlab.com/gitlab-org/gitlab/-/issues/20976) in GitLab 12.6. The DevOps Report gives you an overview of your entire instance's adoption of [Concurrent DevOps](https://about.gitlab.com/topics/concurrent-devops/) from planning to monitoring. -To see DevOps Report, go to **Admin Area > Analytics > DevOps Report**. +To see DevOps Report: -## DevOps Score **(FREE)** +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Analytics > DevOps Report**. + +## DevOps Score NOTE: Your GitLab instance's [usage ping](../settings/usage_statistics.md#usage-ping) must be activated in order to use this feature. @@ -34,21 +36,30 @@ Usage ping data is aggregated on GitLab servers for analysis. Your usage information is **not sent** to any other GitLab instances. If you have just started using GitLab, it may take a few weeks for data to be collected before this feature is available. -## DevOps Adoption **(ULTIMATE)** +## DevOps Adoption **(ULTIMATE SELF)** -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/247112) in GitLab 13.7 as a [Beta feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +> - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59267) in GitLab 14.0. +> - Enabled on GitLab.com. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-or-enable-devops-adoption). **(ULTIMATE SELF)** The DevOps Adoption tab shows you which groups within your organization are using the most essential features of GitLab: -- Issues -- Merge Requests -- Approvals -- Runners -- Pipelines -- Deploys -- Scanning - -Buttons to manage your groups appear in the DevOps Adoption section of the page. +- Dev + - Issues + - Merge Requests + - Approvals + - Code owners +- Sec + - Scans +- Ops + - Runners + - Pipelines + - Deployments + +When managing groups in the UI, you can add your groups with the **Add group to table** +button, in the top right hand section the page. DevOps Adoption allows you to: @@ -56,20 +67,22 @@ DevOps Adoption allows you to: - Identify specific groups that are lagging in their adoption of GitLab so you can help them along in their DevOps journey. - Find the groups that have adopted certain features and can provide guidance to other groups on how to use those features. +![DevOps Report](img/admin_devops_adoption_v14_0.png) + ### Disable or enable DevOps Adoption -DevOps Adoption is deployed behind a feature flag that is **disabled by default**. +DevOps Adoption is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to enable it. +can opt to disable it. -To enable it: +To disable it: ```ruby -Feature.enable(:devops_adoption_feature) +Feature.disable(:devops_adoption_feature) ``` -To disable it: +To reenable it: ```ruby -Feature.disable(:devops_adoption_feature) +Feature.enable(:devops_adoption_feature) ``` diff --git a/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_0.png b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_0.png new file mode 100644 index 00000000000..f4170b2938c Binary files /dev/null and b/doc/user/admin_area/analytics/img/admin_devops_adoption_v14_0.png differ diff --git a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png index 210c5c2609a..bd02065556c 100644 Binary files a/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png and b/doc/user/admin_area/analytics/img/instance_activity_pipelines_chart_v13_6_a.png differ diff --git a/doc/user/admin_area/analytics/index.md b/doc/user/admin_area/analytics/index.md index bea22745e7b..465b26d516c 100644 --- a/doc/user/admin_area/analytics/index.md +++ b/doc/user/admin_area/analytics/index.md @@ -1,16 +1,19 @@ --- -stage: none -group: unassigned +stage: Manage +group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Instance-level analytics +# Instance-level analytics **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41416) in GitLab 11.2. -Administrators have access to instance-wide analytics, as shown in **Admin Area > Analytics**. +Administrators have access to instance-wide analytics: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Analytics**. There are several kinds of statistics: -- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. **(FREE)** -- [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. **(FREE)** +- [DevOps Report](dev_ops_report.md): Provides an overview of your entire instance's feature usage. +- [Usage Trends](usage_trends.md): Shows how much data your instance contains, and how that is changing. diff --git a/doc/user/admin_area/analytics/usage_trends.md b/doc/user/admin_area/analytics/usage_trends.md index 7fb23f702a4..49c81b1a965 100644 --- a/doc/user/admin_area/analytics/usage_trends.md +++ b/doc/user/admin_area/analytics/usage_trends.md @@ -4,7 +4,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Usage Trends **(FREE)** +# Usage Trends **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235754) in GitLab 13.5 behind a feature flag, disabled by default. > - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46962) in GitLab 13.6. diff --git a/doc/user/admin_area/analytics/user_cohorts.md b/doc/user/admin_area/analytics/user_cohorts.md index ca5dff85757..b906f9b8fa6 100644 --- a/doc/user/admin_area/analytics/user_cohorts.md +++ b/doc/user/admin_area/analytics/user_cohorts.md @@ -1,5 +1,6 @@ --- redirect_to: '../user_cohorts.md' +remove_date: '2021-06-01' --- This document was moved to [another location](../user_cohorts.md). diff --git a/doc/user/admin_area/appearance.md b/doc/user/admin_area/appearance.md index 0d72f09dfd9..d7f0b7e3854 100644 --- a/doc/user/admin_area/appearance.md +++ b/doc/user/admin_area/appearance.md @@ -9,8 +9,10 @@ disqus_identifier: 'https://docs.gitlab.com/ee/customization/branded_login_page. # GitLab Appearance **(FREE SELF)** There are several options for customizing the appearance of a self-managed instance -of GitLab. These settings are accessed from the **Admin Area** in the **Appearance** -section. +of GitLab. To access these settings: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left sidebar, select **Settings > Appearance**. ## Navigation bar diff --git a/doc/user/admin_area/approving_users.md b/doc/user/admin_area/approving_users.md index 2b3b90cb1a4..3d9722035d5 100644 --- a/doc/user/admin_area/approving_users.md +++ b/doc/user/admin_area/approving_users.md @@ -34,7 +34,8 @@ sign in. To view user sign ups pending approval: -1. Go to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. ## Approve or reject a user sign up @@ -43,9 +44,10 @@ A user sign up pending approval can be approved or rejected from the Admin Area. To approve or reject a user sign up: -1. Go to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select the **Pending approval** tab. -1. In the user's row select settings (**{settings}**). +1. In the user's row, select settings (**{settings}**). 1. Select **Approve** or **Reject**. Approving a user: diff --git a/doc/user/admin_area/blocking_unblocking_users.md b/doc/user/admin_area/blocking_unblocking_users.md index cafc7caf981..e89c42b34ba 100644 --- a/doc/user/admin_area/blocking_unblocking_users.md +++ b/doc/user/admin_area/blocking_unblocking_users.md @@ -1,5 +1,6 @@ --- redirect_to: 'moderate_users.md' +remove_date: '2021-08-12' --- This document was moved to [another location](moderate_users.md). diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 67a89f896ff..93e6aa9bb16 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -5,21 +5,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Broadcast Messages **(FREE SELF)** +# Broadcast messages **(FREE SELF)** GitLab can display broadcast messages to all users of a GitLab instance. There are two types of broadcast messages: -- banners -- notifications +- Banners +- Notifications -You can style a message's content using the `a` and `br` HTML tags. The `br` tag inserts a line break. The `a` HTML tag accepts `class` and `style` attributes with the following CSS properties: - -- `color` -- `border` -- `background` -- `padding` -- `margin` -- `text-decoration` +Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md). ## Banners @@ -36,6 +29,8 @@ remote: ... ``` +If more than one banner is active at one time, they are displayed in a stack in order of creation. + ## Notifications Notifications are shown on the bottom right of a page and can contain placeholders. A placeholder is replaced with an attribute of the active user. Placeholders must be surrounded by curly braces, for example `{{name}}`. @@ -51,65 +46,63 @@ If the user is not signed in, user related values are empty. ![Broadcast Message Notification](img/broadcast_messages_notification_v12_10.png) -Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md). - -NOTE: -If more than one banner message is active at one time, they are displayed in a stack in order of creation. -If more than one notification message is active at one time, only the newest is shown. +If more than one notification is active at one time, only the newest is shown. -## Adding a broadcast message +## Add a broadcast message -To display messages to users on your GitLab instance, add broadcast message. +To display messages to users on your GitLab instance, add a broadcast message. To add a broadcast message: -1. Navigate to the **Admin Area > Messages** page. -1. Add the text for the message to the **Message** field. Markdown and emoji are supported. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Messages**. +1. Add the text for the message to the **Message** field. You can style a message's content using Markdown, emoji, and the `a` and `br` HTML tags. + The `br` tag inserts a line break. The `a` HTML tag accepts `class` and `style` attributes with the following CSS properties: + - `color` + - `border` + - `background` + - `padding` + - `margin` + - `text-decoration` 1. Select one of the suggested background colors, or add the hex code of a different color. The default color is orange. +1. Select the **Dismissable** checkbox to enable users to dismiss the broadcast message. 1. If required, add a **Target Path** to only show the broadcast message on URLs matching that path. You can use the wildcard character `*` to match multiple URLs, for example `mygroup/myproject*`. 1. Select a date for the message to start and end. -1. Click the **Add broadcast message** button. - -NOTE: -When scoping messages, you can't use preceding or trailing slashes. For example, -instead of `/mygroup/myproject/`, you must use `mygroup/myproject`. A fix is -[planned for GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59482). +1. Select **Add broadcast message**. NOTE: The **Background color** field expects the value to be a hexadecimal code because the form uses the [color_field](https://api.rubyonrails.org/v6.0.3.4/classes/ActionView/Helpers/FormHelper.html#method-i-color_field) helper method, which generates the proper HTML to render. -NOTE: -Once a broadcast message has expired, it is no longer displayed in the UI but is still listed in the -list of broadcast messages. User can also dismiss a broadcast message if the option **Dismissable** is set. +When a broadcast message expires, it no longer displays in the user interface but is still listed in the +list of broadcast messages. -## Editing a broadcast message +## Edit a broadcast message -If changes are required to a broadcast message, they can be edited. +If you need to make changes to a broadcast message, you can edit it. To edit a broadcast message: -1. Navigate to the **Admin Area > Messages** page. -1. From the list of broadcast messages, click the appropriate button to edit the message. -1. After making the required changes, click the **Update broadcast message** button. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Messages**. +1. From the list of broadcast messages, select the edit button for the message. +1. After making the required changes, select **Update broadcast message**. -NOTE: Expired messages can be made active again by changing their end date. -## Deleting a broadcast message +## Delete a broadcast message -Broadcast messages that are no longer required can be deleted. +If you no longer require a broadcast message, you can delete it. +You can delete a broadcast message while it's active. To delete a broadcast message: -1. Navigate to the **Admin Area > Messages** page. -1. From the list of broadcast messages, click the appropriate button to delete the message. - -Once deleted, the broadcast message is removed from the list of broadcast messages. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Messages**. +1. From the list of broadcast messages, select the delete button for the message. -NOTE: -Broadcast messages can be deleted while active. +When a broadcast message is deleted, it's removed from the list of broadcast messages. - ## Requirements To enable container scanning in your pipeline, you need the following: @@ -53,46 +46,25 @@ To enable container scanning in your pipeline, you need the following: or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the shared runners on GitLab.com, then this is already the case. -- An image matching the following supported distributions (depending on the analyzer being used): - - | Scanning Engine | Supported distributions | - | --- | --- | - | [Clair](https://github.com/quay/claircore) | [Supported operating systems and languages](https://quay.github.io/claircore/) | - | [Trivy](https://github.com/aquasecurity/trivy) | Supported [operating systems](https://aquasecurity.github.io/trivy/latest/vuln-detection/os/) and [languages](https://aquasecurity.github.io/trivy/latest/vuln-detection/library/) | - +- An image matching the [supported distributions](#supported-distributions). - [Build and push](../../packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) - your Docker image to your project's container registry. The name of the Docker image should use - the following [predefined CI/CD variables](../../../ci/variables/predefined_variables.md): - - ```plaintext - $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA - ``` - - You can use these directly in your `.gitlab-ci.yml` file: - - ```yaml - build: - image: docker:19.03.12 - stage: build - services: - - docker:19.03.12-dind - variables: - IMAGE_TAG: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA - script: - - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - - docker build -t $IMAGE_TAG . - - docker push $IMAGE_TAG - ``` + the Docker image to your project's container registry. If using a third-party container + registry, you might need to provide authentication credentials using the `DOCKER_USER` and + `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). +- The name of the Docker image to scan, in the `DOCKER_IMAGE` [configuration variable](#available-cicd-variables). ## Configuration How you enable container scanning depends on your GitLab version: - GitLab 11.9 and later: [Include](../../../ci/yaml/README.md#includetemplate) the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) + [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) that comes with your GitLab installation. - GitLab versions earlier than 11.9: Copy and use the job from the - [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). + [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). + +Other changes: + - GitLab 13.6 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/263482) better support for [FIPS](https://csrc.nist.gov/publications/detail/fips/140/2/final) by upgrading the `CS_MAJOR_VERSION` from `2` to `3`. Version `3` of the `container_scanning` Docker image uses @@ -102,17 +74,20 @@ How you enable container scanning depends on your GitLab version: `container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script) and [`after_script`](../../../ci/yaml/README.md#after_script) blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based - Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-variables) + Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables) variable. - GitLab 13.9 [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322656) integration with [Trivy](https://github.com/aquasecurity/trivy) by upgrading `CS_MAJOR_VERSION` from `3` to `4`. +- GitLab 14.0 [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61850) + integration with [Trivy](https://github.com/aquasecurity/trivy) + as the default for container scanning. To include the `Container-Scanning.gitlab-ci.yml` template (GitLab 11.9 and later), add the following to your `.gitlab-ci.yml` file: ```yaml include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml ``` The included template: @@ -127,21 +102,14 @@ that you can download and analyze later. When downloading, you always receive th artifact. The following is a sample `.gitlab-ci.yml` that builds your Docker image, pushes it to the container -registry, and scans the containers: +registry, and scans the image: ```yaml -variables: - DOCKER_DRIVER: overlay2 - -stages: - - build - - test - build: - image: docker:stable + image: docker:latest stage: build services: - - docker:19.03.12-dind + - docker:dind variables: IMAGE: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA script: @@ -151,7 +119,7 @@ build: - docker push $IMAGE include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml ``` ### Customizing the container scanning settings @@ -159,76 +127,45 @@ include: There may be cases where you want to customize how GitLab scans your containers. For example, you may want to enable more verbose output, access a Docker registry that requires authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/README.md#variables) -parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-variables). +parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-cicd-variables). The variables you set in your `.gitlab-ci.yml` overwrite those in `Container-Scanning.gitlab-ci.yml`. This example [includes](../../../ci/yaml/README.md#include) the container scanning template and -enables verbose output for both analyzers: - -Clair: +enables verbose output for the analyzer: ```yaml include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml variables: - CLAIR_TRACE: true + SECURE_LOG_LEVEL: 'debug' ``` -Trivy: +#### Available CI/CD variables -```yaml -include: - - template: Container-Scanning.gitlab-ci.yml - -variables: - TRIVY_DEBUG: true -``` - -This example [includes](../../../ci/yaml/README.md#include) the container scanning template and -enables version `2` of the analyzer: - -```yaml -include: - - template: Container-Scanning.gitlab-ci.yml - -variables: - CS_MAJOR_VERSION: '2' -``` +You can [configure](#customizing-the-container-scanning-settings) analyzers by using the following CI/CD variables: - +| CI/CD Variable | Default | Description | Scanner | +| ------------------------------ | ------------- | ----------- | ------------ | +| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | All | +| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | All | +| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | All | +| `CS_ANALYZER_IMAGE` | `$SECURE_ANALYZERS_PREFIX/$CS_PROJECT:$CS_MAJOR_VERSION` | Docker image of the analyzer. | All | +| `CS_DOCKER_INSECURE` | `"false"` | Allow access to secure Docker registries using HTTPS without validating the certificates. | All | +| `CS_REGISTRY_INSECURE` | `"false"` | Allow access to insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | Trivy. The registry must listen on port `80/tcp`. | +| `CS_SEVERITY_THRESHOLD` | `UNKNOWN` | Severity level threshold. The scanner outputs vulnerabilities with severity level higher than or equal to this threshold. Supported levels are Unknown, Low, Medium, High, and Critical. | Trivy | +| `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | All | +| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | All | +| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | All | +| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | All | +| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | All | -#### Available variables +### Supported distributions -You can [configure](#customizing-the-container-scanning-settings) both analyzers by using the following CI/CD variables: +Support depends on the scanner: -| CI/CD Variable | Default | Description | Supported by| -| ------------------------------ | ------------- | ----------- | ------------ | -| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. See [Using a custom SSL CA certificate authority](#using-a-custom-ssl-ca-certificate-authority) for more details. | Both | -| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db) database. **Do not change this** unless you're running the image locally as described in [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool). The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | Clair | -| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version (for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerability database for an on-premise offline installation). | Clair | -| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version (for example, to provide a consistent set of vulnerabilities for integration testing purposes). | Clair | -| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are output. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical`, and `Defcon1`. | Clair | -| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the Clair server process. | Clair | -| `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerability definitions](https://hub.docker.com/r/arminc/clair-db) is running on. **Do not change this** unless you're running the image locally as described in [Running the standalone container scanning tool](#running-the-standalone-container-scanning-tool). | Clair | -| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | Both | -| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | Both | -| `CS_ANALYZER_IMAGE` | `$SECURE_ANALYZERS_PREFIX/$CS_PROJECT:$CS_MAJOR_VERSION` | Docker image of the analyzer. | Both | -| `CS_MAJOR_VERSION` | `3` | The major version of the Docker image tag. | Both | -| `CS_PROJECT` | Depends on `$CS_MAJOR_VERSION`. `klar` if `$CS_MAJOR_VERSION` is set to `1`, `2` or `3`, and `container-scanning` otherwise. | Analyzer project to be used. | Both | -| `DOCKER_IMAGE` | `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG` | The Docker image to be scanned. If set, this variable overrides the `$CI_APPLICATION_REPOSITORY` and `$CI_APPLICATION_TAG` variables. | Both | -| `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | Clair | -| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | Clair | -| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | Clair | -| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to use for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project. You should configure this variable only if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | Both | -| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from Klar. | Clair | -| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | Clair | -| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | Both | -| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | Both | -| `TRIVY_DEBUG` | `"false"` | Set to true to enable more verbose output from the Trivy process. | Trivy | +- [Trivy](https://aquasecurity.github.io/trivy/latest/vuln-detection/os/) (Default). ### Overriding the container scanning template @@ -236,37 +173,15 @@ If you want to override the job definition (for example, to change properties li must declare and override a job after the template inclusion, and then specify any additional keys. -This example sets `GIT_STRATEGY` to `fetch` to be considered by both Clair and Trivy: - -```yaml -include: - - template: Container-Scanning.gitlab-ci.yml - -.cs_common: - variables: - GIT_STRATEGY: fetch -``` - -This example sets `KLAR_TRACE` to `true`, which is specific to Clair: +This example sets `GIT_STRATEGY` to `fetch`: ```yaml include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml container_scanning: variables: - CLAIR_TRACE: true -``` - -This example sets `TRIVY_DEBUG` to `true`, which is specific to Trivy: - -```yaml -include: - - template: Container-Scanning.gitlab-ci.yml - -container_scanning_new: - variables: - TRIVY_DEBUG: true + GIT_STRATEGY: fetch ``` WARNING: @@ -276,36 +191,47 @@ instead. ### Migrating from Clair to Trivy -If you are currently using Clair and want to migrate to Trivy before GitLab 14.0, you can do so by -taking the following steps: +If you're migrating from a GitLab 13.x release to a GitLab 14.x release and have customized the +`container_scanning` job or its CI variables, you might need to perform these migration steps in +your CI file: + +1. Remove these variables: + + - `CS_MAJOR_VERSION` + - `CS_PROJECT` + - `SECURE_ANALYZERS_PREFIX` -1. Take the following actions in your CI file: +1. Review the `CS_ANALYZER_IMAGE` variable. It no longer depends on the variables above and its new + default value is `registry.gitlab.com/security-products/container-scanning:4`. If you have an + offline environment, see + [Running container scanning in an offline environment](#running-container-scanning-in-an-offline-environment). - - Set the variable `CS_MAJOR_VERSION` to `4`. The job scope is global variables, or under `.cs_common`. - - Remove the variable `CS_PROJECT` from your CI file. The job scope is `container_scanning_new`. - Setting this variable to `container-scanning` under the correct scope has the same effect as - removing it from your CI file. - - Remove the `CS_ANALYZER_IMAGE` variable from your CI file. The job scope is `.cs_common`. Note - that instead of overriding this variable, you can use `CS_MAJOR_VERSION`. +1. If present, remove the `.cs_common` and `container_scanning_new` configuration sections. -1. Remove any variables that are only applicable to Clair. For a complete list of these variables, - see the [available variables](#available-variables). -1. Make any [necessary customizations](#customizing-the-container-scanning-settings) to the - `Trivy` scanner. We strongly recommended that you minimize customizations, as they - might require changes in future GitLab major releases. +1. If the `container_scanning` section is present, it's safer to create one from scratch based on + the new version of the [`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). + Once finished, it should not have any variables that are only applicable to Klar or Clair. For a + complete list of supported variables, see [available variables](#available-cicd-variables). + +1. Make any [necessary customizations](#customizing-the-container-scanning-settings) + to the `Trivy` scanner. We recommend that you minimize such customizations, as they might require + changes in future GitLab major releases. + +1. Trigger a new run of a pipeline that includes the `container_scanning` job. Inspect the job + output and ensure that the log messages do not mention Clair. **Troubleshooting** Prior to the GitLab 14.0 release, any variable defined under the scope `container_scanning` is not considered for the Trivy scanner. Verify that all variables for Trivy are -either defined as a global variable, or under `.cs_common` and `container_scanning_new`. +either defined as a global variable, or under `container_scanning`. ### Using a custom SSL CA certificate authority You can use the `ADDITIONAL_CA_CERT_BUNDLE` CI/CD variable to configure a custom SSL CA certificate authority, which is used to verify the peer when fetching Docker images from a registry which uses HTTPS. The `ADDITIONAL_CA_CERT_BUNDLE` value should contain the [text representation of the X.509 PEM public-key certificate](https://tools.ietf.org/html/rfc7468#section-5.1). For example, to configure this value in the `.gitlab-ci.yml` file, use the following: ```yaml -.cs_common: +container_scanning: variables: ADDITIONAL_CA_CERT_BUNDLE: | -----BEGIN CERTIFICATE----- @@ -379,7 +305,7 @@ at the logs that are produced by the container scanning analyzer in `container_s The log contains a list of found vulnerabilities as a table, for example: -```plainttext +```plaintext +------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ | STATUS | CVE SEVERITY | PACKAGE NAME | PACKAGE VERSION | CVE DESCRIPTION | +------------+-------------------------+------------------------+-----------------------+------------------------------------------------------------------------+ @@ -420,8 +346,7 @@ To use container scanning in an offline environment, you need: | GitLab Analyzer | Container Registry | | --- | --- | -| [Klar](https://gitlab.com/gitlab-org/security-products/analyzers/klar/) (used to run Clair) | [Klar container registry](https://gitlab.com/gitlab-org/security-products/analyzers/klar/container_registry) | -| [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) (used to run Trivy) | [Container-Scanning container registry](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/container_registry/1741162) | +| [Container-Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) | [Container-Scanning container registry](https://gitlab.com/security-products/container-scanning/container_registry/) | Note that GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), meaning the runner tries to pull Docker images from the GitLab container registry even if a local @@ -436,7 +361,6 @@ Support for custom certificate authorities was introduced in the following versi | Scanner | Version | | -------- | ------- | -| `Clair` | [v2.3.0](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/releases/v2.3.0) | | `Trivy` | [4.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning/-/releases/4.0.0) | #### Make GitLab container scanning analyzer images available inside your Docker registry @@ -444,17 +368,8 @@ Support for custom certificate authorities was introduced in the following versi For container scanning, import the following default images from `registry.gitlab.com` into your [local Docker container registry](../../packages/container_registry/index.md): -Clair: - ```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/klar -https://hub.docker.com/r/arminc/clair-db -``` - -Trivy: - -```plaintext -registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning +registry.gitlab.com/security-products/container-scanning ``` The process for importing Docker images into a local offline Docker registry depends on @@ -473,54 +388,33 @@ For details on saving and transporting Docker images as a file, see Docker's doc 1. [Override the container scanning template](#overriding-the-container-scanning-template) in your `.gitlab-ci.yml` file to refer to the Docker images hosted on your local Docker container registry: - Clair: - ```yaml include: - - template: Container-Scanning.gitlab-ci.yml + - template: Security/Container-Scanning.gitlab-ci.yml - .cs_common: - image: $CI_REGISTRY/namespace/gitlab-klar-analyzer - variables: - CLAIR_DB_IMAGE: $CI_REGISTRY/namespace/clair-vulnerabilities-db - ``` - - Trivy: - - ```yaml - include: - - template: Container-Scanning.gitlab-ci.yml - - .cs_common: + container_scanning: image: $CI_REGISTRY/namespace/gitlab-container-scanning ``` 1. If your local Docker container registry is running securely over `HTTPS`, but you're using a - self-signed certificate, then you must set `DOCKER_INSECURE: "true"` in the above - `container_scanning` section of your `.gitlab-ci.yml`. This only applies to Clair. + self-signed certificate, then you must set `CS_DOCKER_INSECURE: "true"` in the above + `container_scanning` section of your `.gitlab-ci.yml`. #### Automating container scanning vulnerability database updates with a pipeline We recommend that you set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) -to fetch the latest vulnerabilities database on a preset schedule. Because the Clair scanner is -deprecated, the latest vulnerabilities are currently only available for the Trivy scanner. +to fetch the latest vulnerabilities database on a preset schedule. Automating this with a pipeline means you do not have to do it manually each time. You can use the following `.gitlab-yml.ci` example as a template. ```yaml variables: - # If using Clair, uncomment the following 2 lines and comment the Trivy lines below - # SOURCE_IMAGE: arminc/clair-db:latest - # TARGET_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH/clair-vulnerabilities-db - - # If using Trivy, uncomment the following 3 lines and comment the Clair lines above - CS_MAJOR_VERSION: 4 # ensure that this value matches the one you use in your scanning jobs - SOURCE_IMAGE: registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning:$CS_MAJOR_VERSION + SOURCE_IMAGE: registry.gitlab.com/security-products/container-scanning:4 TARGET_IMAGE: $CI_REGISTRY/$CI_PROJECT_PATH/gitlab-container-scanning image: docker:stable -update-vulnerabilities-db: +update-scanner-image: services: - docker:19-dind script: @@ -536,42 +430,6 @@ you're using a non-GitLab Docker registry, you must change the `$CI_REGISTRY` va ## Running the standalone container scanning tool -### Clair - -It's possible to run [Klar](https://gitlab.com/gitlab-org/security-products/analyzers/klar) -against a Docker container without needing to run it within the context of a CI job. To scan an -image directly, follow these steps: - -1. Run [Docker Desktop](https://www.docker.com/products/docker-desktop) or [Docker Machine](https://github.com/docker/machine). -1. Run the latest [prefilled vulnerabilities database](https://hub.docker.com/repository/docker/arminc/clair-db) Docker image: - - ```shell - docker run -p 5432:5432 -d --name clair-db arminc/clair-db:latest - ``` - -1. Configure a CI/CD variable to point to your local machine's IP address (or insert your IP address instead of the `LOCAL_MACHINE_IP_ADDRESS` variable in the `CLAIR_DB_CONNECTION_STRING` in the next step): - - ```shell - export LOCAL_MACHINE_IP_ADDRESS=your.local.ip.address - ``` - -1. Run the analyzer's Docker image, passing the image and tag you want to analyze in the `CI_APPLICATION_REPOSITORY` and `CI_APPLICATION_TAG` variables: - - ```shell - docker run \ - --interactive --rm \ - --volume "$PWD":/tmp/app \ - -e CI_PROJECT_DIR=/tmp/app \ - -e CLAIR_DB_CONNECTION_STRING="postgresql://postgres:password@${LOCAL_MACHINE_IP_ADDRESS}:5432/postgres?sslmode=disable&statement_timeout=60000" \ - -e CI_APPLICATION_REPOSITORY=registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256 \ - -e CI_APPLICATION_TAG=bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e \ - registry.gitlab.com/gitlab-org/security-products/analyzers/klar - ``` - -The results are stored in `gl-container-scanning-report.json`. - -### Trivy - It's possible to run the [GitLab container scanning tool](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning) against a Docker container without needing to run it within the context of a CI job. To scan an image directly, follow these steps: @@ -589,7 +447,7 @@ image directly, follow these steps: -e CI_PROJECT_DIR=/tmp/app \ -e CI_APPLICATION_REPOSITORY=registry.gitlab.com/gitlab-org/security-products/dast/webgoat-8.0@sha256 \ -e CI_APPLICATION_TAG=bc09fe2e0721dfaeee79364115aeedf2174cce0947b9ae5fe7c33312ee019a4e \ - registry.gitlab.com/gitlab-org/security-products/analyzers/container-scanning + registry.gitlab.com/security-products/container-scanning ``` The results are stored in `gl-container-scanning-report.json`. @@ -698,8 +556,8 @@ the security vulnerabilities in your groups, projects and pipelines. ## Vulnerabilities database update -If you're using Klar and want more information about the vulnerabilities database update, see the -[maintenance table](../vulnerabilities/index.md#vulnerability-scanner-maintenance). +If you use container scanning and want more information about the vulnerabilities database update, +see the [maintenance table](../vulnerabilities/index.md#vulnerability-scanner-maintenance). ## Interacting with the vulnerabilities @@ -711,13 +569,13 @@ Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. To enable remediation support, the scanning tool _must_ have access to the `Dockerfile` specified by -the [`DOCKERFILE_PATH`](#available-variables) CI/CD variable. To ensure that the scanning tool +the [`DOCKERFILE_PATH`](#available-cicd-variables) CI/CD variable. To ensure that the scanning tool has access to this -file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/README.md#git-strategy) in +file, it's necessary to set [`GIT_STRATEGY: fetch`](../../../ci/runners/configure_runners.md#git-strategy) in your `.gitlab-ci.yml` file by following the instructions described in this document's [overriding the container scanning template](#overriding-the-container-scanning-template) section. -Read more about the [solutions for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically). +Read more about the [solutions for vulnerabilities](../vulnerabilities/index.md#resolve-a-vulnerability). ## Troubleshooting diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 8b0a84eae4b..b46547b6828 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -1,6 +1,6 @@ --- stage: Secure -group: Fuzz Testing +group: Dynamic Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference, howto --- @@ -39,7 +39,7 @@ Docker image with the fuzz engine to run your app. To enable fuzzing, you must [include](../../../ci/yaml/README.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) +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: diff --git a/doc/user/application_security/cve_id_request.md b/doc/user/application_security/cve_id_request.md index bc0c1e52626..aaf701c91dc 100644 --- a/doc/user/application_security/cve_id_request.md +++ b/doc/user/application_security/cve_id_request.md @@ -5,7 +5,7 @@ group: Vulnerability Research info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# CVE ID Requests +# CVE ID Requests **(ULTIMATE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41203) in GitLab 13.4, only for public projects on GitLab.com. diff --git a/doc/user/application_security/dast/browser_based.md b/doc/user/application_security/dast/browser_based.md index b8c3529225c..072f6fba4ba 100644 --- a/doc/user/application_security/dast/browser_based.md +++ b/doc/user/application_security/dast/browser_based.md @@ -27,62 +27,44 @@ Scanning a web application with both the browser-based crawler and GitLab DAST s The browser-based crawler is an extension to the GitLab DAST product. DAST should be included in the CI/CD configuration and the browser-based crawler enabled using CI/CD variables: -1. Install the DAST [prerequisites](index.md#prerequisite). +1. Ensure the DAST [prerequisites](index.md#prerequisites) are met. 1. Include the [DAST CI template](index.md#include-the-dast-template). 1. Set the target website using the `DAST_WEBSITE` CI/CD variable. 1. Set the CI/CD variable `DAST_BROWSER_SCAN` to `true`. - + An example configuration might look like the following: ```yaml include: - template: DAST.gitlab-ci.yml -variables: - DAST_WEBSITE: "https://example.com" - DAST_BROWSER_SCAN: "true" +dast: + variables: + DAST_WEBSITE: "https://example.com" + DAST_BROWSER_SCAN: "true" ``` -### Available variables +### Available CI/CD variables The browser-based crawler can be configured using CI/CD variables. -| CI/CD variable | Type | Example | Description | +| CI/CD variable | Type | Example | Description | |--------------------------------------| ----------------| --------------------------------- | ------------| | `DAST_WEBSITE` | URL | `http://www.site.com` | The URL of the website to scan. | -| `DAST_BROWSER_SCAN` | boolean | `true` | Configures DAST to use the browser-based crawler engine. | -| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | -| `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | -| `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | -| `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | -| `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | -| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but will likely produce little benefit after five to seven instances. | -| `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | -| `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | -| `DAST_AUTH_URL` | string | `https://example.com/sign-in` | The URL of page that hosts the sign-in form. | -| `DAST_USERNAME` | string | `user123` | The username to enter into the username field on the sign-in HTML form. | -| `DAST_PASSWORD` | string | `p@55w0rd` | The password to enter into the password field on the sign-in HTML form. | -| `DAST_USERNAME_FIELD` | selector | `id:user` | A selector describing the username field on the sign-in HTML form. | -| `DAST_PASSWORD_FIELD` | selector | `css:.password-field` | A selector describing the password field on the sign-in HTML form. | -| `DAST_SUBMIT_FIELD` | selector | `xpath://input[@value='Login']` | A selector describing the element that when clicked submits the login form or the password form of a multi-page login process. | -| `DAST_FIRST_SUBMIT_FIELD` | selector | `.submit` | A selector describing the element that when clicked submits the username form of a multi-page login process. | - -The [DAST variables](index.md#available-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`, +| `DAST_BROWSER_SCAN` | boolean | `true` | Configures DAST to use the browser-based crawler engine. | +| `DAST_BROWSER_ALLOWED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered in scope when crawled. By default the `DAST_WEBSITE` hostname is included in the allowed hosts list. | +| `DAST_BROWSER_EXCLUDED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are considered excluded and connections are forcibly dropped. | +| `DAST_BROWSER_IGNORED_HOSTS` | List of strings | `site.com,another.com` | Hostnames included in this variable are accessed but not reported against. | +| `DAST_BROWSER_MAX_ACTIONS` | number | `10000` | The maximum number of actions that the crawler performs. For example, clicking a link, or filling a form. | +| `DAST_BROWSER_MAX_DEPTH` | number | `10` | The maximum number of chained actions that the crawler takes. For example, `Click -> Form Fill -> Click` is a depth of three. | +| `DAST_BROWSER_NUMBER_OF_BROWSERS` | number | `3` | The maximum number of concurrent browser instances to use. For shared runners on GitLab.com we recommended a maximum of three. Private runners with more resources may benefit from a higher number, but will likely produce little benefit after five to seven instances. | +| `DAST_BROWSER_COOKIES` | dictionary | `abtesting_group:3,region:locked` | A cookie name and value to be added to every request. | +| `DAST_BROWSER_LOG` | List of strings | `brows:debug,auth:debug` | A list of modules and their intended log level. | + +The [DAST variables](index.md#available-cicd-variables) `SECURE_ANALYZERS_PREFIX`, `DAST_FULL_SCAN_ENABLED`, `DAST_AUTO_UPDATE_ADDONS`, `DAST_EXCLUDE_RULES`, `DAST_REQUEST_HEADERS`, `DAST_HTML_REPORT`, `DAST_MARKDOWN_REPORT`, `DAST_XML_REPORT`, +`DAST_AUTH_URL`, `DAST_USERNAME`, `DAST_PASSWORD`, `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, `DAST_FIRST_SUBMIT_FIELD`, `DAST_SUBMIT_FIELD`, `DAST_EXCLUDE_URLS`, `DAST_AUTH_VERIFICATION_URL`, `DAST_BROWSER_AUTH_VERIFICATION_SELECTOR`, `DAST_BROWSER_AUTH_VERIFICATION_LOGIN_FORM`, `DAST_BROWSER_AUTH_REPORT`, `DAST_INCLUDE_ALPHA_VULNERABILITIES`, `DAST_PATHS_FILE`, `DAST_PATHS`, `DAST_ZAP_CLI_OPTIONS`, and `DAST_ZAP_LOG_CONFIGURATION` are also compatible with browser-based crawler scans. - -#### Selectors - -Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. -Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. - -| Selector type | Example | Description | -| ------------- | ------------------------------ | ----------- | -| `css` | `css:.password-field` | Searches for a HTML element having the supplied CSS selector. Selectors should be as specific as possible for performance reasons. | -| `id` | `id:element` | Searches for an HTML element with the provided element ID. | -| `name` | `name:element` | Searches for an HTML element with the provided element name. | -| `xpath` | `xpath://*[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | -| None provided | `a.click-me` | Defaults to searching using a CSS selector. | - + ## Vulnerability detection While the browser-based crawler crawls modern web applications efficiently, vulnerability detection is still managed by the standard DAST/Zed Attack Proxy (ZAP) solution. @@ -100,9 +82,9 @@ This can come at a cost of increased scan time. You can manage the trade-off between coverage and scan time with the following measures: -- Limit the number of actions executed by the browser with the [variable](#available-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. -- Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. -- Vertically scaling the runner and using a higher number of browsers with [variable](#available-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. +- Limit the number of actions executed by the browser with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_ACTIONS`. The default is `10,000`. +- Limit the page depth that the browser-based crawler will check coverage on with the [variable](#available-cicd-variables) `DAST_BROWSER_MAX_DEPTH`. The crawler uses a breadth-first search strategy, so pages with smaller depth are crawled first. The default is `10`. +- Vertically scaling the runner and using a higher number of browsers with [variable](#available-cicd-variables) `DAST_BROWSER_NUMBER_OF_BROWSERS`. The default is `3`. ## Debugging scans using logging @@ -116,10 +98,11 @@ For example, the following job definition enables the browsing module and the au include: - template: DAST.gitlab-ci.yml -variables: - DAST_WEBSITE: "https://my.site.com" - DAST_BROWSER_SCAN: "true" - DAST_BROWSER_LOG: "brows:debug,auth:debug" +dast: + variables: + DAST_WEBSITE: "https://my.site.com" + DAST_BROWSER_SCAN: "true" + DAST_BROWSER_LOG: "brows:debug,auth:debug" ``` ### Log message format diff --git a/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png b/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png new file mode 100644 index 00000000000..132c9f9c991 Binary files /dev/null and b/doc/user/application_security/dast/img/dast_auth_browser_scan_highlight.png differ diff --git a/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png b/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png new file mode 100644 index 00000000000..4e1dca626bc Binary files /dev/null and b/doc/user/application_security/dast/img/dast_auth_browser_scan_search_elements.png differ diff --git a/doc/user/application_security/dast/img/dast_auth_report.jpg b/doc/user/application_security/dast/img/dast_auth_report.jpg new file mode 100644 index 00000000000..5d9d98045ef Binary files /dev/null and b/doc/user/application_security/dast/img/dast_auth_report.jpg differ diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 1093e7cfabd..675d01373d4 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -16,40 +16,161 @@ 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. +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. + +The comparison logic uses only the latest pipeline executed for the target +branch's base commit. Running the pipeline on other commits has no effect on +the merge request. + NOTE: To learn how four of the top six attacks were application-based and how to protect your organization, download our ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) whitepaper. -You can use DAST to examine your web applications: +## DAST application analysis -- When initiated by a merge request, running as CI/CD pipeline job. -- On demand, outside the CI/CD pipeline. +DAST can analyze applications in two ways: -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. +- Passive scan only (DAST default). DAST executes + [ZAP's Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) and doesn't + actively attack your application. +- Passive and active scan. DAST can be [configured](#full-scan) to also perform an active scan + to attack your application and produce a more extensive security report. It can be very + useful when combined with [Review Apps](../../../ci/review_apps/index.md). -The comparison logic uses only the latest pipeline executed for the target -branch's base commit. Running the pipeline on other commits has no effect on -the merge request. +NOTE: +A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job +fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For +example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST +results. On failure, the analyzer outputs an +[exit code](../../../development/integrations/secure.md#exit-code). -## Prerequisite +## Prerequisites -To use DAST, ensure you're using GitLab Runner with the +- [GitLab Runner](../../../ci/runners/README.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). + +### Deployment options + +Depending on the complexity of the target application, there are a few options as to how to deploy and configure +the DAST template. We provided a set of example applications with their configurations in our +[DAST demonstrations](https://gitlab.com/gitlab-org/security-products/demos/dast/) project. + +#### Review Apps + +Review Apps are the most involved method of deploying your DAST target application. To assist in the process, +we created a Review App deployment using Google Kubernetes Engine (GKE). This example can be found in our +[Review Apps - GKE](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke) project, along with detailed +instructions in the [README.md](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke/-/blob/master/README.md) +on how to configure Review Apps for DAST. + +#### Docker Services + +If your application utilizes Docker containers you have another option for deploying and scanning with DAST. +After your Docker build job completes and your image is added to your container registry, you can use the image as a +[service](../../../ci/services/index.md). + +By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. + +```yaml +stages: + - build + - dast + +include: + - template: DAST.gitlab-ci.yml + +# Deploys the container to the GitLab container registry +deploy: + services: + - name: docker:dind + alias: dind + image: docker:19.03.5 + stage: build + script: + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker pull $CI_REGISTRY_IMAGE:latest || true + - docker build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest . + - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + - docker push $CI_REGISTRY_IMAGE:latest + +services: # use services to link your app container to the dast job + - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + alias: yourapp + +variables: + DAST_FULL_SCAN_ENABLED: "true" # do a full scan + DAST_ZAP_USE_AJAX_SPIDER: "true" # use the ajax spider +``` + +Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate +with each another. To allow communication between services, enable the `FF_NETWORK_PER_BUILD` [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags). + +```yaml +variables: + FF_NETWORK_PER_BUILD: "true" # enable network per build so all services can communicate on the same network + +services: # use services to link the container to the dast job + - name: mongo:latest + alias: mongo + - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + alias: yourapp +``` + +## DAST run options + +You can use DAST to examine your web application: + +- Automatically, initiated by a merge request. +- Manually, initiated on demand. + +Some of the differences between these run options: -## Enable DAST +| Automatic scan | On-demand scan | +|:-----------------------------------------------------------------|:------------------------------| +| DAST scan is initiated by a merge request. | DAST scan is initiated manually, outside the DevOps life cycle. | +| CI/CD variables are sourced from `.gitlab-ci.yml`. | CI/CD variables are provided in the UI. | +| All [DAST CI/CD variables](#available-cicd-variables) available. | Subset of [DAST CI/CD variables](#available-cicd-variables) available. | +| `DAST.gitlab-ci.yml` template. | `DAST-On-Demand-Scan.gitlab-ci.yml` template. | -To enable DAST, either: +### Enable automatic DAST run + +To enable DAST to run automatically, either: - Enable [Auto DAST](../../../topics/autodevops/stages.md#auto-dast) (provided by [Auto DevOps](../../../topics/autodevops/index.md)). -- Manually [include the DAST template](#include-the-dast-template) in your existing +- [Include the DAST template](#include-the-dast-template) in your existing `.gitlab-ci.yml` file. -### Include the DAST template +### DAST job order + +When using the `DAST.gitlab-ci.yml` template, the `dast` stage is run last as shown in +the example below. To ensure DAST scans the latest code, deploy your application +in a stage before the `dast` stage. + +```yaml + stages: + - build + - test + - deploy + - dast +``` + +Be aware that if your pipeline is configured to deploy to the same webserver in +each run, running a pipeline while another is still running could cause a race condition +where one pipeline overwrites the code from another pipeline. The site to be scanned +should be excluded from changes for the duration of a DAST scan. +The only changes to the site should be from the DAST scanner. Be aware that any +changes that users, scheduled tasks, database changes, code changes, other pipelines, or other scanners make to +the site during a scan could lead to inaccurate results. + +#### Include the DAST template + +> This template was [updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62597) to DAST_VERSION: 2 in GitLab 14.0. If you want to manually add DAST to your application, the DAST job is defined in a CI/CD template file. Updates to the template are provided with GitLab @@ -59,7 +180,7 @@ To include the DAST template: 1. Select the CI/CD template you want to use: - - [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): + - [`DAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml): Stable version of the DAST CI/CD template. - [`DAST.latest.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST.latest.gitlab-ci.yml): Latest version of the DAST template. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254325) @@ -119,7 +240,7 @@ To include the DAST template: ``` You can see an example of this in our - [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) + [Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml) file. The included template creates a `dast` job in your CI/CD pipeline and scans @@ -146,182 +267,12 @@ page. #### Crawling web applications dependent on JavaScript -GitLab has released a new browser-based crawler, an add-on to DAST that uses a browser to crawl web applications for content. This crawler replaces the standard DAST Spider and Ajax Crawler. +GitLab has released a new browser-based crawler, an add-on to DAST that uses a browser to crawl web applications for content. This crawler replaces the standard DAST Spider and Ajax Crawler, and uses the same authentication mechanisms as a normal DAST scan. The browser-based crawler crawls websites by browsing web pages as a user would. This approach works well with web applications that make heavy use of JavaScript, such as Single Page Applications. For more details, including setup instructions, see [DAST browser-based crawler](browser_based.md). -## Deployment options - -Depending on the complexity of the target application, there are a few options as to how to deploy and configure -the DAST template. A set of example applications with their configurations have been made available in our -[DAST demonstrations](https://gitlab.com/gitlab-org/security-products/demos/dast/) project. - -### Review Apps - -Review Apps are the most involved method of deploying your DAST target application. To assist in the process, -we created a Review App deployment using Google Kubernetes Engine (GKE). This example can be found in our -[Review Apps - GKE](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke) project along with detailed -instructions in the [README.md](https://gitlab.com/gitlab-org/security-products/demos/dast/review-app-gke/-/blob/master/README.md) -on how to configure Review Apps for DAST. - -### Docker Services - -If your application utilizes Docker containers you have another option for deploying and scanning with DAST. -After your Docker build job completes and your image is added to your container registry, you can utilize the image as a -[service](../../../ci/services/index.md). - -By using service definitions in your `gitlab-ci.yml`, you can scan services with the DAST analyzer. - -```yaml -stages: - - build - - dast - -include: - - template: DAST.gitlab-ci.yml - -# Deploys the container to the GitLab container registry -deploy: - services: - - name: docker:dind - alias: dind - image: docker:19.03.5 - stage: build - script: - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY - - docker pull $CI_REGISTRY_IMAGE:latest || true - - docker build --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest . - - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA - - docker push $CI_REGISTRY_IMAGE:latest - -services: # use services to link your app container to the dast job - - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA - alias: yourapp - -variables: - DAST_FULL_SCAN_ENABLED: "true" # do a full scan - DAST_ZAP_USE_AJAX_SPIDER: "true" # use the ajax spider -``` - -Most applications depend on multiple services such as databases or caching services. By default, services defined in the services fields cannot communicate -with each another. To allow communication between services, enable the `FF_NETWORK_PER_BUILD` [feature flag](https://docs.gitlab.com/runner/configuration/feature-flags.html#available-feature-flags). - -```yaml -variables: - FF_NETWORK_PER_BUILD: "true" # enable network per build so all services can communicate on the same network - -services: # use services to link the container to the dast job - - name: mongo:latest - alias: mongo - - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA - alias: yourapp -``` - -### DAST application analysis - -DAST can analyze applications in two ways: - -- Passive scan only (DAST default). DAST executes - [ZAP's Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) and doesn't - actively attack your application. -- Passive and active scan. DAST can be [configured](#full-scan) to also perform an active scan - to attack your application and produce a more extensive security report. It can be very - useful when combined with [Review Apps](../../../ci/review_apps/index.md). - -Note that a pipeline may consist of multiple jobs, including SAST and DAST scanning. If any job -fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For -example, if the DAST job finishes but the SAST job fails, the security dashboard doesn't show DAST -results. On failure, the analyzer outputs an -[exit code](../../../development/integrations/secure.md#exit-code). - -#### DAST job order - -When using the `DAST.gitlab-ci.yml` template, the `dast` job is run last as shown in -the example below. To ensure DAST is scanning the latest code, your CI pipeline -should deploy changes to the web server in one of the jobs preceding the `dast` job. - -```yaml -stages: - - build - - test - - deploy - - dast -``` - -Be aware that if your pipeline is configured to deploy to the same webserver in -each run, running a pipeline while another is still running could cause a race condition -where one pipeline overwrites the code from another pipeline. The site to be scanned -should be excluded from changes for the duration of a DAST scan. -The only changes to the site should be from the DAST scanner. Be aware that any -changes that users, scheduled tasks, database changes, code changes, other pipelines, or other scanners make to -the site during a scan could lead to inaccurate results. - -### Hide sensitive information - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. - -HTTP request and response headers may contain sensitive information, including cookies and -authorization credentials. By default, the following headers are masked: - -- `Authorization`. -- `Proxy-Authorization`. -- `Set-Cookie` (values only). -- `Cookie` (values only). - -Using the [`DAST_MASK_HTTP_HEADERS` CI/CD variable](#available-variables), you can list the -headers whose values you want masked. For details on how to mask headers, see -[Customizing the DAST settings](#customizing-the-dast-settings). - -### Authentication - -It's also possible to authenticate the user before performing the DAST checks. - -NOTE: -We highly recommended that you configure the scanner to authenticate to the application, -otherwise it cannot check most of the application for security risks, as most -of your application is likely not accessible without authentication. It is also recommended -that you periodically confirm the scanner's authentication is still working as this tends to break over -time due to authentication changes to the application. - -Create masked CI/CD variables to pass the credentials that DAST uses. -To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables). -Note that the key of the username variable must be `DAST_USERNAME` -and the key of the password variable must be `DAST_PASSWORD`. - -After DAST has authenticated with the application, all cookies are collected from the web browser. -For each cookie a matching session token is created for use by ZAP. This ensures ZAP is recognized -by the application as correctly authenticated. - -Other variables that are related to authenticated scans are: - -```yaml -include: - - template: DAST.gitlab-ci.yml - -variables: - DAST_WEBSITE: https://example.com - DAST_AUTH_URL: https://example.com/sign-in - DAST_USERNAME_FIELD: session[user] # the name of username field at the sign-in HTML form - DAST_PASSWORD_FIELD: session[password] # the name of password field at the sign-in HTML form - DAST_SUBMIT_FIELD: login # the `id` or `name` of the element that when clicked will submit the login form or the password form of a multi-page login process - DAST_FIRST_SUBMIT_FIELD: next # the `id` or `name` of the element that when clicked will submit the username form of a multi-page login process - DAST_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between - DAST_AUTH_VERIFICATION_URL: http://example.com/loggedin_page # optional, a URL only accessible to logged in users that DAST can use to confirm successful authentication -``` - -The results are saved as a -[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast) -that you can later download and analyze. -Due to implementation limitations, we always take the latest DAST artifact available. - -WARNING: -**NEVER** run an authenticated scan against a production server. When an authenticated -scan is run, it may perform *any* function that the authenticated user can. This -includes actions like modifying and deleting data, submitting forms, and following links. -Only run an authenticated scan against a test server. - ### Full scan DAST can be configured to perform [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan), which @@ -338,126 +289,6 @@ variables: If your DAST job exceeds the job timeout and you need to reduce the scan duration, we shared some tips for optimizing DAST scans in a [blog post](https://about.gitlab.com/blog/2020/08/31/how-to-configure-dast-full-scans-for-complex-web-applications/). -#### Domain validation - -WARNING: -In GitLab 13.8, domain validation, outside of the new on-demand scan site profile validation, was deprecated. In GitLab 14.0, domain validation in CI/CD jobs will be permanently removed. - -The DAST job can be run anywhere, which means you can accidentally hit live web servers -and potentially damage them. You could even take down your production environment. -For that reason, you should use domain validation. - -Domain validation is not required by default. It can be required by setting the -[CI/CD variable](#available-variables) `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` to `"true"`. - -```yaml -include: - - template: DAST.gitlab-ci.yml - -variables: - DAST_FULL_SCAN_ENABLED: "true" - DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED: "true" -``` - -Since ZAP full scan actively attacks the target application, DAST sends a ping -to the target (normally defined in `DAST_WEBSITE` or `environment_url.txt`) beforehand. - -- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `false` or unset, the scan - proceeds unless the response to the ping includes a `Gitlab-DAST-Permission` - header with a value of `deny`. -- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `true`, the scan exits - unless the response to the ping includes a `Gitlab-DAST-Permission` header with - a value of `allow`. - -Here are some examples of adding the `Gitlab-DAST-Permission` header to a response -in Rails, Django, and Node (with Express). - -##### Ruby on Rails - -Here's how you would add a -[custom header in Ruby on Rails](https://guides.rubyonrails.org/action_controller_overview.html#setting-custom-headers): - -```ruby -class DastWebsiteTargetController < ActionController::Base - def dast_website_target - response.headers['Gitlab-DAST-Permission'] = 'allow' - - head :ok - end -end -``` - -##### Django - -Here's how you would add a -[custom header in Django](https://docs.djangoproject.com/en/2.2/ref/request-response/#setting-header-fields): - -```python -class DastWebsiteTargetView(View): - def head(self, *args, **kwargs): - response = HttpResponse() - response['Gitlab-Dast-Permission'] = 'allow' - - return response -``` - -##### Node (with Express) - -Here's how you would add a -[custom header in Node (with Express)](http://expressjs.com/en/5x/api.html#res.append): - -```javascript -app.get('/dast-website-target', function(req, res) { - res.append('Gitlab-DAST-Permission', 'allow') - res.send('Respond to DAST ping') -}) -``` - -##### Domain validation header via a proxy - -It's also possible to add the `Gitlab-DAST-Permission` header via a proxy. - -###### NGINX - -The following configuration allows NGINX to act as a reverse proxy and add the -`Gitlab-DAST-Permission` [header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header): - -```nginx -# default.conf -server { - listen 80; - server_name localhost; - - location / { - proxy_pass http://test-application; - add_header Gitlab-DAST-Permission allow; - } -} -``` - -###### Apache - -Apache can also be used as a [reverse proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) -to add the `Gitlab-DAST-Permission` [header](https://httpd.apache.org/docs/current/mod/mod_headers.html). - -To do so, add the following lines to `httpd.conf`: - -```plaintext -# httpd.conf -LoadModule proxy_module modules/mod_proxy.so -LoadModule proxy_connect_module modules/mod_proxy_connect.so -LoadModule proxy_http_module modules/mod_proxy_http.so - - - ProxyPass "/" "http://test-application.com/" - ProxyPassReverse "/" "http://test-application.com/" - Header set Gitlab-DAST-Permission "allow" - -``` - -[This snippet](https://gitlab.com/gitlab-org/security-products/dast/snippets/1894732) contains a complete `httpd.conf` file -configured to act as a remote proxy and add the `Gitlab-DAST-Permission` header. - ### API scan > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. @@ -661,7 +492,7 @@ is no longer supported. When overriding the template, you must use [`rules`](../ The DAST settings can be changed through CI/CD variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. -These variables are documented in [available variables](#available-variables). +These variables are documented in [available variables](#available-cicd-variables). For example: @@ -677,47 +508,296 @@ variables: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -### Available variables +#### Enabling and disabling rules + +A complete list of the rules that DAST uses to scan for vulnerabilities can be +found in the [ZAP docs](https://www.zaproxy.org/docs/alerts/). + +`DAST_EXCLUDE_RULES` disables the rules with the given IDs. + +`DAST_ONLY_INCLUDE_RULES` restricts the set of rules used in the scan to +those with the given IDs. + +`DAST_EXCLUDE_RULES` and `DAST_ONLY_INCLUDE_RULES` are mutually exclusive and a +DAST scan with both configured exits with an error. + +By default, several rules are disabled because they either take a long time to +run or frequently generate false positives. The complete list of disabled rules +can be found in [exclude_rules.yml](https://gitlab.com/gitlab-org/security-products/dast/-/blob/master/src/config/exclude_rules.yml). + +### Hide sensitive information + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in GitLab 13.1. + +HTTP request and response headers may contain sensitive information, including cookies and +authorization credentials. By default, the following headers are masked: + +- `Authorization`. +- `Proxy-Authorization`. +- `Set-Cookie` (values only). +- `Cookie` (values only). + +Using the [`DAST_MASK_HTTP_HEADERS` CI/CD variable](#available-cicd-variables), you can list the +headers whose values you want masked. For details on how to mask headers, see +[Customizing the DAST settings](#customizing-the-dast-settings). + +## Authentication + +NOTE: +We highly recommend you configure the scanner to authenticate to the application. If you don't, it cannot check most of the application for security risks, as most +of your application is likely not accessible without authentication. We also recommend +you periodically confirm the scanner's authentication is still working, as this tends to break over +time due to authentication changes to the application. + +Create masked CI/CD variables to pass the credentials that DAST uses. +To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#custom-cicd-variables). +The key of the username variable must be `DAST_USERNAME`, +and the key of the password variable must be `DAST_PASSWORD`. + +After DAST has authenticated with the application, all cookies are collected from the web browser. +For each cookie a matching session token is created for use by ZAP. This ensures ZAP is recognized +by the application as correctly authenticated. + +Authentication supports single form logins, multi-step login forms, and authenticating to URLs outside of the configured target URL. + +Variables that are related to authenticated scans are: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + DAST_AUTH_URL: "https://login.example.com/" + DAST_USERNAME: "admin" + DAST_PASSWORD: "P@55w0rd!" + DAST_USERNAME_FIELD: "name:username" # a selector describing the element containing the username field at the sign-in HTML form + DAST_PASSWORD_FIELD: "id:password" # a selector describing the element containing the password field at the sign-in HTML form + DAST_FIRST_SUBMIT_FIELD: "css:button[type='user-submit']" # optional, the selector of the element that when clicked will submit the username form of a multi-page login process + DAST_SUBMIT_FIELD: "css:button[type='submit']" # the selector of the element that when clicked will submit the login form or the password form of a multi-page login process + DAST_EXCLUDE_URLS: "http://example.com/sign-out" # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between + DAST_AUTH_VERIFICATION_URL: "http://example.com/loggedin_page" # optional, used to verify authentication is successful by expecting this URL once the login form has been submitted + DAST_AUTH_VERIFICATION_SELECTOR: "css:.user-profile" # optional, used to verify authentication is successful by expecting a selector to be present on the page once the login form has been submitted + DAST_AUTH_VERIFICATION_LOGIN_FORM: "true" # optional, used to verify authentication is successful by ensuring there are no login forms on the page once the login form has been submitted + DAST_AUTH_REPORT: "true" # optionally output an authentication debug report +``` + +WARNING: +**NEVER** run an authenticated scan against a production server. When an authenticated +scan is run, it may perform *any* function that the authenticated user can. This +includes actions like modifying and deleting data, submitting forms, and following links. +Only run an authenticated scan against a test server. + +### Log in using automatic detection of the login form + +By providing a `DAST_USERNAME`, `DAST_PASSWORD`, and `DAST_AUTH_URL`, DAST will attempt to authenticate to the +target application by locating the login form based on a determination about whether or not the form contains username or password fields. + +Automatic detection is "best-effort", and depending on the application being scanned may provide either a resilient login experience or one that fails to authenticate the user. + +Login process: + +1. The `DAST_AUTH_URL` is loaded into the browser, and any forms on the page are located. + 1. If a form contains a username and password field, `DAST_USERNAME` and `DAST_PASSWORD` is inputted into the respective fields, the form submit button is clicked and the user is logged in. + 1. If a form contains only a username field, it is assumed that the login form is multi-step. + 1. The `DAST_USERNAME` is inputted into the username field and the form submit button is clicked. + 1. The subsequent pages loads where it is expected that a form exists and contains a password field. If found, `DAST_PASSWORD` is inputted, form submit button is clicked and the user is logged in. + +### Log in using explicit selection of the login form + +By providing a `DAST_USERNAME_FIELD`, `DAST_PASSWORD_FIELD`, and `DAST_SUBMIT_FIELD`, in addition to the fields required for automatic login, +DAST will attempt to authenticate to the target application by locating the login form based on the selectors provided. +Most applications will benefit from this approach to authentication. + +Login process: + +1. The `DAST_AUTH_URL` is loaded into the browser, and any forms on the page are located. + 1. If the `DAST_FIRST_SUBMIT_FIELD` is not defined, then `DAST_USERNAME` is inputted into `DAST_USERNAME_FIELD`, `DAST_PASSWORD` is inputted into `DAST_PASSWORD_FIELD`, `DAST_SUBMIT_FIELD` is clicked and the user is logged in. + 1. If the `DAST_FIRST_SUBMIT_FIELD` is defined, then it is assumed that the login form is multi-step. + 1. The `DAST_USERNAME` is inputted into the `DAST_USERNAME_FIELD` field and the `DAST_FIRST_SUBMIT_FIELD` is clicked. + 1. The subsequent pages loads where the `DAST_PASSWORD` is inputted into the `DAST_PASSWORD_FIELD` field, the `DAST_SUBMIT_FIELD` is clicked and the user is logged in. + +### Verifying successful login + +Once the login form has been submitted, DAST determines if the login was successful. Unsuccessful attempts at authentication cause the scan to halt. + +Following the submission of the login form, authentication is determined to be unsuccessful when: + +- A `400` or `500` series HTTP response status code is returned. +- A new cookie/browser storage value determined to be sufficiently random has not been set. + +In addition to these checks, the user can configure their own verification checks. +Each of the following checks can be used in conjunction with one another, if none are configured by default the presence of a login form is checked. + +#### Verifying based on the URL + +When `DAST_AUTH_VERIFICATION_URL` is configured, the URL displayed in the browser tab post login form submission is directly compared to the URL in the CI/CD variable. +If these are not exactly the same, authentication is deemed to be unsuccessful. + +For example: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + ... + DAST_AUTH_VERIFICATION_URL: "https://example.com/user/welcome" +``` + +#### Verify based on presence of an element + +When `DAST_AUTH_VERIFICATION_SELECTOR` is configured, the page displayed in the browser tab is searched for an element described by the selector in the CI/CD variable. +If no element is found, authentication is deemed to be unsuccessful. + +For example: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + ... + DAST_AUTH_VERIFICATION_SELECTOR: "css:.welcome-user" +``` + +#### Verify based on presence of a login form + +When `DAST_AUTH_VERIFICATION_LOGIN_FORM` is configured, the page displayed in the browser tab is searched for a form that is detected to be a login form. +If any such form is found, authentication is deemed to be unsuccessful. + +For example: + +```yaml +include: + - template: DAST.gitlab-ci.yml + +dast: + variables: + DAST_WEBSITE: "https://example.com" + ... + DAST_AUTH_VERIFICATION_LOGIN_FORM: "true" +``` + +### Configure the authentication debug output + +It is often difficult to understand the cause of an authentication failure when running DAST in a CI/CD pipeline. +To assist users in debugging authentication issues, a debug report can be generated and saved as a job artifact. +This HTML report contains all steps made during the login process, along with HTTP requests and responses, the Document Object Model (DOM) and screenshots. + +![dast-auth-report](img/dast_auth_report.jpg) + +An example configuration where the authentication debug report is exported may look like the following: + +```yaml +dast: + variables: + DAST_WEBSITE: "https://example.com" + ... + DAST_AUTH_REPORT: "true" + artifacts: + paths: [gl-dast-debug-auth-report.html] +``` + +### Available CI/CD variables DAST can be [configured](#customizing-the-dast-settings) using CI/CD variables. -| CI/CD variable | Type | Description | -|------------------------------| --------|-------------| -| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | -| `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_OPENAPI` must be specified if this is omitted. | -| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_API_SPECIFICATION` | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | -| `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | -| `DAST_AUTH_VERIFICATION_URL` | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST will exit if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. -| `DAST_USERNAME` | string | The username to authenticate to in the website. | -| `DAST_PASSWORD` | string | The password to authenticate to in the website. | -| `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | -| `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | -| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | -| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | -| `DAST_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | -| `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | -| `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/293595) in GitLab 13.8, to be removed in 14.0. Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | -| `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | -| `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | -| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | -| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | -| `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | -| `DAST_DEBUG` | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1.| -| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | -| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | -| `DAST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the login form or the password form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_FIRST_SUBMIT_FIELD` | string | The `id` or `name` of the element that when clicked submits the username form of a multi-page login process. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | -| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | -| `DAST_AUTH_EXCLUDE_URLS` | URLs | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/289959) in GitLab 13.8, to be removed in 14.0, and replaced by `DAST_EXCLUDE_URLS`. The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | +| CI/CD variable | Type | Description | +|:--------------------------------------------|:--------------|:-----------------------------------| +| `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | +| `DAST_WEBSITE` (**1**) | URL | The URL of the website to scan. `DAST_API_OPENAPI` must be specified if this is omitted. | +| `DAST_API_OPENAPI` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_API_SPECIFICATION` (**1**) | URL or string | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/290241) in GitLab 13.12 and replaced by `DAST_API_OPENAPI`. To be removed in GitLab 15.0. The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | +| `DAST_SPIDER_START_AT_HOST` | boolean | Set to `false` to prevent DAST from resetting the target to its host before scanning. When `true`, non-host targets `http://test.site/some_path` is reset to `http://test.site` before scan. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258805) in GitLab 13.6. | +| `DAST_AUTH_URL` (**1**) | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | +| `DAST_AUTH_VERIFICATION_URL` (**1**) | URL | A URL only accessible to logged in users that DAST can use to confirm successful authentication. If provided, DAST exits if it cannot access the URL. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207335) in GitLab 13.8. | +| `DAST_USERNAME` (**1**) | string | The username to enter into the username field on the sign-in HTML form. | +| `DAST_PASSWORD` (**1**) | string | The password to enter into the password field on the sign-in HTML form. | +| `DAST_USERNAME_FIELD` (**1**) | selector | A selector describing the username field on the sign-in HTML form. Example: `id:user` | +| `DAST_PASSWORD_FIELD` (**1**) | selector | A selector describing the password field on the sign-in HTML form. Example: `css:.password-field` | +| `DAST_SKIP_TARGET_CHECK` | boolean | Set to `true` to prevent DAST from checking that the target is available before scanning. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229067) in GitLab 13.8. | +| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | +| `DAST_EXCLUDE_URLS` (**1**) | URLs | The URLs to skip during the authenticated scan; comma-separated. Regular expression syntax can be used to match multiple URLs. For example, `.*` matches an arbitrary character sequence. Not supported for API scans. | +| `DAST_FULL_SCAN_ENABLED` (**1**) | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | +| `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | +| `DAST_API_HOST_OVERRIDE` (**1**) | string | Used to override domains defined in API specification files. Only supported when importing the API specification from a URL. Example: `example.com:8080` | +| `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). For example, `HTTP Parameter Override` has a rule ID of `10026`. Cannot be used when `DAST_ONLY_INCLUDE_RULES` is set. **Note:** In earlier versions of GitLab the excluded rules were executed but vulnerabilities they generated were suppressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | +| `DAST_ONLY_INCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to configure the scan to run only them. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://www.zaproxy.org/docs/alerts/). Cannot be used when `DAST_EXCLUDE_RULES` is set. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/250651) in GitLab 13.12. | +| `DAST_REQUEST_HEADERS` (**1**) | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | +| `DAST_DEBUG` (**1**) | boolean | Enable debug message output. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_TARGET_AVAILABILITY_TIMEOUT` (**1**) | number | Time limit in seconds to wait for target availability. +| `DAST_SPIDER_MINS` (**1**) | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_USE_AJAX_SPIDER` (**1**) | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_PATHS` | string | Set to a comma-separated list of URLs for DAST to scan. For example, `/page1.html,/category1/page3.html,/page2.html`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214120) in GitLab 13.4. | +| `DAST_PATHS_FILE` | string | The file path containing the paths within `DAST_WEBSITE` to scan. The file must be plain text with one path per line. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/258825) in GitLab 13.6. | +| `DAST_SUBMIT_FIELD` | selector | A selector describing the element that when clicked submits the login form, or the password form of a multi-page login process. Example: `xpath://input[@value='Login']`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_FIRST_SUBMIT_FIELD` | selector | A selector describing the element that when clicked submits the username form of a multi-page login process. Example: `.submit`. [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9894) in GitLab 12.4. | +| `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | +| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. For example, `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | +| `DAST_AGGREGATE_VULNERABILITIES` | boolean | Vulnerability aggregation is set to `true` by default. To disable this feature and see each vulnerability individually set to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/254043) in GitLab 14.0. | +| `DAST_MAX_URLS_PER_VULNERABILITY` | number | The maximum number of URLs reported for a single vulnerability. `DAST_MAX_URLS_PER_VULNERABILITY` is set to `50` by default. To list all the URLs set to `0`. [Introduced](https://gitlab.com/gitlab-org/security-products/dast/-/merge_requests/433) in GitLab 13.12. | +| `DAST_AUTH_REPORT` | boolean | Used in combination with exporting the `gl-dast-debug-auth-report.html` artifact to aid in debugging authentication issues. | +| `DAST_AUTH_VERIFICATION_SELECTOR` | selector | Verifies successful authentication by checking for presence of a selector once the login form has been submitted. Example: `css:.user-photo` | +| `DAST_AUTH_VERIFICATION_LOGIN_FORM` | boolean | Verifies successful authentication by checking for the lack of a login form once the login form has been submitted. | + +1. DAST CI/CD variable available to an on-demand scan. + +#### Selectors + +Selectors are used by CI/CD variables to specify the location of an element displayed on a page in a browser. +Selectors have the format `type`:`search string`. The crawler will search for the selector using the search string based on the type. + +| Selector type | Example | Description | +| ------------- | ---------------------------------- | ----------- | +| `css` | `css:.password-field` | Searches for a HTML element having the supplied CSS selector. Selectors should be as specific as possible for performance reasons. | +| `id` | `id:element` | Searches for an HTML element with the provided element ID. | +| `name` | `name:element` | Searches for an HTML element with the provided element name. | +| `xpath` | `xpath://input[@id="my-button"]/a` | Searches for a HTML element with the provided XPath. Note that XPath searches are expected to be less performant than other searches. | +| None provided | `a.click-me` | Defaults to searching using a CSS selector. | + +##### Find selectors with Google Chrome + +Chrome DevTools element selector tool is an effective way to find a selector. + +1. Open Chrome and navigate to the page where you would like to find a selector, for example, the login page for your site. +1. Open the `Elements` tab in Chrome DevTools with the keyboard shortcut `Command + Shift + c` in macOS or `Ctrl + Shift + c` in Windows. +1. Select the `Select an element in the page to select it` tool. + ![search-elements](img/dast_auth_browser_scan_search_elements.png) +1. Select the field on your page that you would like to know the selector for. +1. Once the tool is active, highlight a field you wish to view the details of. + ![highlight](img/dast_auth_browser_scan_highlight.png) +1. Once highlighted, you can see the element's details, including attributes that would make a good candidate for a selector. + +In this example, the `id="user_login"` appears to be a good candidate. You can use this as a selector as the DAST username field by setting `DAST_USERNAME_FIELD: "css:[id=user_login]"`, or more simply, `DAST_USERNAME_FIELD: "id:user_login"`. + +##### Choose the right selector + +Judicious choice of selector leads to a scan that is resilient to the application changing. + +In order of preference, it is recommended to choose as selectors: + +- `id` fields. These are generally unique on a page, and rarely change. +- `name` fields. These are generally unique on a page, and rarely change. +- `class` values specific to the field, such as the selector `"css:.username"` for the `username` class on the username field. +- Presence of field specific data attributes, such as the selector, `"css:[data-username]"` when the `data-username` field has any value on the username field. +- Multiple `class` hierarchy values, such as the selector `"css:.login-form .username"` when there are multiple elements with class `username` but only one nested inside the element with the class `login-form`. + +When using selectors to locate specific fields we recommend you avoid searching on: + +- Any `id`, `name`, `attribute`, `class` or `value` that is dynamically generated. +- Generic class names, such as `column-10` and `dark-grey`. +- XPath searches as they are less performant than other selector searches. +- Unscoped searches, such as those beginning with `css:*` and `xpath://*`. ### DAST command-line options @@ -783,7 +863,7 @@ variables: ### Cloning the project's repository The DAST job does not require the project's repository to be present when running, so by default -[`GIT_STRATEGY`](../../../ci/runners/README.md#git-strategy) is set to `none`. +[`GIT_STRATEGY`](../../../ci/runners/configure_runners.md#git-strategy) is set to `none`. ### Debugging DAST jobs @@ -819,7 +899,7 @@ successfully run. For more information, see [Offline environments](../offline_de To use DAST in an offline environment, you need: -- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisite). +- GitLab Runner with the [`docker` or `kubernetes` executor](#prerequisites). - Docker Container Registry with a locally available copy of the DAST [container image](https://gitlab.com/gitlab-org/security-products/dast), found in the [DAST container registry](https://gitlab.com/gitlab-org/security-products/dast/container_registry). @@ -993,7 +1073,7 @@ A site profile contains the following: - **Target URL**: The URL that DAST runs against. - **Excluded URLs**: A comma-separated list of URLs to exclude from the scan. - **Request headers**: A comma-separated list of HTTP request headers, including names and values. These headers are added to every request made by DAST. -- **Authentication**: +- **Authentication**: - **Authenticated URL**: The URL of the page containing the sign-in HTML form on the target website. The username and password are submitted with the login form to create an authenticated scan. - **Username**: The username used to authenticate to the website. - **Password**: The password used to authenticate to the website. @@ -1217,11 +1297,6 @@ The DAST tool always emits a JSON report file called `gl-dast-report.json` and sample reports can be found in the [DAST repository](https://gitlab.com/gitlab-org/security-products/dast/-/tree/master/test/end-to-end/expect). -There are two formats of data in the JSON report that are used side by side: - -- The proprietary ZAP format, which is planned to be deprecated. -- A common format that is planned to the default in the future. - ### Other formats Reports can also be generated in Markdown, HTML, and XML. These can be published as artifacts using the following configuration: diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 5e47f545ef9..9a6e1e73330 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -59,6 +59,7 @@ Examples of various configurations can be found here: - [Example HTTP Archive (HAR) project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/har-example) - [Example Postman Collection project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/postman-example) - [Example GraphQL project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/graphql-example) +- [Example SOAP project](https://gitlab.com/gitlab-org/security-products/demos/api-dast/soap-example) WARNING: GitLab 14.0 will require that you place DAST API configuration files (for example, @@ -71,8 +72,8 @@ starting in GitLab 14.0, GitLab will not check your repository's root for config > Support for OpenAPI Specification using YAML format was > [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330583) in GitLab 14.0. -The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. -This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. +The [OpenAPI Specification](https://www.openapis.org/) (formerly the Swagger Specification) is an API description format for REST APIs. +This section shows you how to configure API fuzzing using an OpenAPI Specification to provide information about the target API to test. OpenAPI Specifications are provided as a file system resource or URL. Both JSON and YAML OpenAPI formats are supported. DAST API uses an OpenAPI document to generate the request body. When a request body is required, @@ -85,7 +86,7 @@ the body generation is limited to these body types: Follow these steps to configure DAST API in GitLab with an OpenAPI specification: 1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) that's provided as part of your GitLab installation. Add the following to your `.gitlab-ci.yml` file: @@ -136,7 +137,7 @@ Follow these steps to configure DAST API in GitLab with an OpenAPI specification dynamic environments. To run DAST API against an app dynamically created during a GitLab CI/CD pipeline, have the app persist its URL in an `environment_url.txt` file. DAST API automatically parses that file to find its scan target. You can see an - [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). Here's an example of using `DAST_API_TARGET_URL`: @@ -184,7 +185,7 @@ Follow these steps to configure DAST API to use a HAR file that provides informa target API to test: 1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) that's provided as part of your GitLab installation. To do so, add the following to your `.gitlab-ci.yml` file: @@ -235,7 +236,7 @@ target API to test: dynamic environments. To run DAST API against an app dynamically created during a GitLab CI/CD pipeline, have the app persist its URL in an `environment_url.txt` file. DAST API automatically parses that file to find its scan target. You can see an - [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). Here's an example of using `DAST_API_TARGET_URL`: @@ -284,7 +285,7 @@ Follow these steps to configure DAST API to use a Postman Collection file that p information about the target API to test: 1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate) - the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) + the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml) that's provided as part of your GitLab installation. To do so, add the following to your `.gitlab-ci.yml` file: @@ -334,7 +335,7 @@ information about the target API to test: dynamic environments. To run DAST API against an app dynamically created during a GitLab CI/CD pipeline, have the app persist its URL in an `environment_url.txt` file. DAST API automatically parses that file to find its scan target. You can see an - [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). + [example of this in our Auto DevOps CI YAML](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml). Here's an example of using `DAST_API_TARGET_URL`: @@ -634,6 +635,7 @@ can be added, removed, and modified by creating a custom configuration. | `DAST_API_TARGET_URL` | Base URL of API testing target. | |[`DAST_API_CONFIG`](#configuration-files) | DAST API configuration file. Defaults to `.gitlab-dast-api.yml`. | |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | +|[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | @@ -847,7 +849,7 @@ variables: ``` In this example `.gitlab-ci.yml`, the `SECRET_OVERRIDES` variable provides the JSON. This is a -[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#instance-cicd-variables): +[group or instance level CI/CD variable defined in the UI](../../../ci/variables/README.md#add-a-cicd-variable-to-an-instance): ```yaml stages: @@ -893,6 +895,47 @@ variables: DAST_API_OVERRIDES_INTERVAL: 300 ``` +### Exclude Paths + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211892) in GitLab 14.0. + +When testing an API it can be useful to exclude certain paths. For example, you might exclude testing of an authentication service or an older version of the API. To exclude paths, use the `FUZZAPI_EXCLUDE_PATHS` CI/CD variable . This variable is specified in your `.gitlab-ci.yml` file. To exclude multiple paths, separate entries using the `;` character. In the provided paths you can use a single character wildcard `?` and `*` for a multiple character wildcard. + +To verify the paths are excluded, review the `Tested Operations` and `Excluded Operations` portion of the job output. You should not see any excluded paths listed under `Tested Operations`. + +```plaintext +2021-05-27 21:51:08 [INF] API Security: --[ Tested Operations ]------------------------- +2021-05-27 21:51:08 [INF] API Security: 201 POST http://target:7777/api/users CREATED +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +2021-05-27 21:51:08 [INF] API Security: --[ Excluded Operations ]----------------------- +2021-05-27 21:51:08 [INF] API Security: GET http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: POST http://target:7777/api/messages +2021-05-27 21:51:08 [INF] API Security: ------------------------------------------------ +``` + +#### Examples + +This example excludes the `/auth` resource. This does not exclude child resources (`/auth/child`). + +```yaml +variables: + DAST_API_EXCLUDE_PATHS=/auth +``` + +To exclude `/auth`, and child resources (`/auth/child`), we use a wildcard. + +```yaml +variables: + DAST_API_EXCLUDE_PATHS=/auth* +``` + +To exclude multiple paths we use the `;` character. In this example we exclude `/auth*` and `/v1/*`. + +```yaml +variables: + DAST_API_EXCLUDE_PATHS=/auth*;/v1/* +``` + ## Running your first scan When configured correctly, a CI/CD pipeline contains a `dast` stage and an `dast_api` job. The job only fails when an invalid configuration is provided. During normal operation, the job always succeeds even if vulnerabilities are identified during testing. @@ -1076,7 +1119,7 @@ The DAST API engine outputs an error message when it cannot establish a connecti **Solution** - Remove the `DAST_API_API` variable from the `.gitlab-ci.yml` file. The value will be inherited from the DAST API CI/CD template. We recommend this method instead of manually setting a value. -- If removing the variable is not possible, check to see if this value has changed in the latest version of the [DAST API CI/CD template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. +- If removing the variable is not possible, check to see if this value has changed in the latest version of the [DAST API CI/CD template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml). If so, update the value in the `.gitlab-ci.yml` file. ### Application cannot determine the base URL for the target API @@ -1088,7 +1131,7 @@ The best-suited solution will depend on whether or not your target API changes f #### Static environment solution -This solution is for pipelines in which the target API URL doesn't change (is static). +This solution is for pipelines in which the target API URL doesn't change (is static). **Add environmental variable** @@ -1105,7 +1148,7 @@ include: #### Dynamic environment solutions -In a dynamic environment your target API changes for each different deployment. In this case, there is more than one possible solution, we recommend you use the `environment_url.txt` file when dealing with dynamic environments. +In a dynamic environment your target API changes for each different deployment. In this case, there is more than one possible solution, we recommend you use the `environment_url.txt` file when dealing with dynamic environments. **Use environment_url.txt** diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index 0faa33e0123..fae0f457a20 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -80,7 +80,7 @@ include: template: Dependency-Scanning.gitlab-ci.yml variables: - DS_EXCLUDED_ANALYZERS: "gemnasium, gemansium-maven, gemnasium-python, bundler-audit, retire.js" + DS_EXCLUDED_ANALYZERS: "gemnasium, gemnasium-maven, gemnasium-python, bundler-audit, retire.js" ``` This is used when one totally relies on [custom analyzers](#custom-analyzers). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 8e23db89dfd..96fc085e7c6 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -91,7 +91,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) To enable dependency scanning for GitLab 11.9 and later, you must [include](../../../ci/yaml/README.md#includetemplate) the -[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) +[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) that is 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. @@ -112,7 +112,7 @@ always take the latest dependency scanning artifact available. ### Customizing the dependency scanning settings -The dependency scanning settings can be changed through [CI/CD variables](#available-variables) by using the +The dependency scanning settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. For example: @@ -157,7 +157,7 @@ gemnasium-dependency_scanning: dependencies: ["build"] ``` -### Available variables +### Available CI/CD variables Dependency scanning can be [configured](#customizing-the-dependency-scanning-settings) using environment variables. @@ -189,7 +189,7 @@ The following variables are used for configuring specific analyzers (used for a | `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the Gemnasium database. | | `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. | | `DS_REMEDIATE` | `gemnasium` | `"true"` | Enable automatic remediation of vulnerable dependencies. | -| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`. Maven and Gradle use the Java version specified by this value. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`, `15`, `16`. Maven and Gradle use the Java version specified by this value (Dependency Scanning for Gradle does not currently support Java `16`). | | `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repositories). | | `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | | `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | @@ -231,11 +231,11 @@ Read more on [how to use private Maven repositories](../index.md#using-private-m Once a vulnerability is found, you can interact with it. Read more on how to [address the vulnerabilities](../vulnerabilities/index.md). -## Solutions for vulnerabilities (auto-remediation) +## Solutions for vulnerabilities Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. Read more about the -[solutions for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically). +[solutions for vulnerabilities](../vulnerabilities/index.md#resolve-a-vulnerability). ## Security Dashboard diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png deleted file mode 100644 index 7b04988afdb..00000000000 Binary files a/doc/user/application_security/img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png and /dev/null differ diff --git a/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png b/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png deleted file mode 100644 index b9b6dd13294..00000000000 Binary files a/doc/user/application_security/img/unconfigured_security_approval_rules_and_jobs_v13_4.png and /dev/null differ diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 82a018c0ae9..bf812b25b5f 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -1,11 +1,11 @@ --- -stage: secure -group: secure +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 --- -# Application security **(ULTIMATE)** +# Secure your application **(ULTIMATE)** GitLab can check your application for security vulnerabilities including: @@ -92,7 +92,9 @@ For more details about each of the security scanning tools, see their respective By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the base address for Docker images. You can override this globally by setting the CI/CD variable -`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once. +`SECURE_ANALYZERS_PREFIX` to another location. Note that this affects all scanners at once, except +the container-scanning analyzer which uses +`registry.gitlab.com/security-products/container-scanning` as its registry. ### Use security scanning tools with Pipelines for Merge Requests @@ -182,84 +184,51 @@ By default, the vulnerability report does not show vulnerabilities of `dismissed > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2. -Merge Request Approvals can be configured to require approval from a member of your -security team when a merge request would introduce one of the following security issues: +You can implement merge request approvals to require approval by selected users or a group when a +merge request would introduce one of the following security issues: - A security vulnerability - A software license compliance violation -The security vulnerability threshold is defined as `high`, `critical`, or `unknown` severity. The -`Vulnerability-Check` approver group must approve merge requests that contain vulnerabilities. +When the Vulnerability-Check merge request rule is enabled, additional merge request approval +is required when the latest security report in a merge request: -When GitLab can assess vulnerability severity, the rating can be one of the following: - -- `unknown` -- `low` -- `medium` -- `high` -- `critical` +- Contains a vulnerability of `high`, `critical`, or `unknown` severity that is not present in the + target branch. Note that approval is still required for dismissed vulnerabilities. +- Is not generated during pipeline execution. -The rating `unknown` indicates that the underlying scanner doesn't contain or provide a severity -rating. +An approval is optional when the security report: -### Enabling Security Approvals within a project +- Contains no new vulnerabilities when compared to the target branch. +- Contains only new vulnerabilities of `low` or `medium` severity. -To enable the `Vulnerability-Check` or `License-Check` Security Approvals, a [project approval rule](../project/merge_requests/approvals/rules.md#add-an-approval-rule) -must be created. A [security scanner job](#security-scanning-tools) must be enabled for -`Vulnerability-Check`, and a [license scanning](../compliance/license_compliance/index.md#configuration) -job must be enabled for `License-Check`. When the proper jobs aren't configured, the following -appears: +When the License-Check merge request rule is enabled, additional approval is required if a merge +request contains a denied license. For more details, see [Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). -![Un-configured Approval Rules](img/unconfigured_security_approval_rules_and_jobs_v13_4.png) +### Enable the Vulnerability-Check rule -If at least one security scanner is enabled, you can enable the `Vulnerability-Check` approval rule. If a license scanning job is enabled, you can enable the `License-Check` rule. +Prerequisites: -![Un-configured Approval Rules with valid pipeline jobs](img/unconfigured_security_approval_rules_and_enabled_jobs_v13_4.png) +- At least one [security scanner job](#security-scanning-tools) must be enabled. +- Maintainer or Owner [role](../permissions.md#project-members-permissions). -For this approval group, you must set the number of approvals required to greater than zero. You -must have Maintainer or Owner [permissions](../permissions.md#project-members-permissions) -to manage approval rules. +For this approval group, you must set the number of approvals required to greater than zero. Follow these steps to enable `Vulnerability-Check`: -1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. -1. Click **Enable**, or **Edit**. +1. Go to your project and select **Settings > General**. +1. Expand **Merge request approvals**. +1. Select **Enable** or **Edit**. 1. Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). - -![Vulnerability Check Approver Rule](img/vulnerability-check_v13_4.png) +1. Set the **No. of approvals required** to greater than zero. +1. Select the **Target branch**. +1. Select the users or groups to provide approval. +1. Select **Add approval rule**. Once this group is added to your project, the approval rule is enabled for all merge requests. - Any code changes cause the approvals required to reset. -An approval is required when the latest security report in a merge request: - -- Contains a vulnerability of `high`, `critical`, or `unknown` severity that is not present in the - target branch. Note that approval is still required for dismissed vulnerabilities. -- Is not generated during pipeline execution. - -An approval is optional when the security report: - -- Contains no new vulnerabilities when compared to the target branch. -- Contains only new vulnerabilities of `low` or `medium` severity. - -### Enabling License Approvals within a project - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. - -`License-Check` is a [security approval rule](#enabling-security-approvals-within-a-project) -you can enable to allow an individual or group to approve a merge request that contains a `denied` -license. For instructions on enabling this rule, see -[Enabling license approvals within a project](../compliance/license_compliance/index.md#enabling-license-approvals-within-a-project). - -## Working in an offline environment - -It is possible to run most of the GitLab security scanners when not -connected to the internet, in what is sometimes known as an offline, -limited connectivity, Local Area Network (LAN), Intranet, or "air-gap" -environment. - -Read how to [operate the Secure scanners in an offline environment](offline_deployments/index.md). +![Vulnerability Check Approver Rule](img/vulnerability-check_v13_4.png) ## Using private Maven repositories @@ -290,47 +259,22 @@ under your project's settings: ``` -## Outdated security reports - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4913) in GitLab 12.7. - -When a security report generated for a merge request becomes outdated, the merge request shows a warning -message in the security widget and prompts you to take an appropriate action. - -This can happen in two scenarios: - -1. Your [source branch is behind the target branch](#source-branch-is-behind-the-target-branch). -1. The [target branch security report is out of date](#target-branch-security-report-is-out-of-date). - -### Source branch is behind the target branch - -This means the most recent common ancestor commit between the target branch and the source branch is -not the most recent commit on the target branch. This is by far the most common situation. - -In this case you must rebase or merge to incorporate the changes from the target branch. - -![Incorporate target branch changes](img/outdated_report_branch_v12_9.png) - -### Target branch security report is out of date - -This can happen for many reasons, including failed jobs or new advisories. When the merge request shows that a -security report is out of date, you must run a new pipeline on the target branch. -You can do it quickly by following the hyperlink given to run a new pipeline. - -![Run a new pipeline](img/outdated_report_pipeline_v12_9.png) - ## DAST On-Demand Scans If you don’t want scans running in your normal DevOps process you can use on-demand scans instead. For more details, see [on-demand scans](dast/index.md#on-demand-scans). This feature is only available for DAST. If you run an on-demand scan against the default branch, it is reported as a "successful pipeline" and these results are included in the security dashboard and vulnerability report. ## Security report validation -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321918) in GitLab 13.11. +> - Schema validation message [added](https://gitlab.com/gitlab-org/gitlab/-/issues/321730) in GitLab 14.0. -As of GitLab 13.11, we've introduced the **optional** validation of the security report artifacts based on the +You can optionally enable validation of the security report artifacts based on the [report schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/tree/master/dist). If you enable validation, GitLab validates the report artifacts before ingesting the vulnerabilities. -This prevents ingesting broken vulnerability data into the database. +This prevents ingestion of broken vulnerability data into the database. + +In GitLab 14.0 and later, the pipeline's **Security** tab lists any report artifacts +that failed validation. Security report validation must first be enabled. ### Enable security report validation @@ -381,14 +325,41 @@ For more details about which findings or vulnerabilities you can view in each of - Change the status. - Create an issue. - Link it to an existing issue. -- In some cases, [apply an automatic remediation for a vulnerability](vulnerabilities/index.md#remediate-a-vulnerability-automatically). +- [Resolve the vulnerability](vulnerabilities/index.md#resolve-a-vulnerability), if a solution is known. ## Troubleshooting +### Outdated security reports + +When a security report generated for a merge request becomes outdated, the merge request shows a warning +message in the security widget and prompts you to take an appropriate action. + +This can happen in two scenarios: + +- Your [source branch is behind the target branch](#source-branch-is-behind-the-target-branch). +- The [target branch security report is out of date](#target-branch-security-report-is-out-of-date). + +#### Source branch is behind the target branch + +This means the most recent common ancestor commit between the target branch and the source branch is +not the most recent commit on the target branch. This is by far the most common situation. + +In this case you must rebase or merge to incorporate the changes from the target branch. + +![Incorporate target branch changes](img/outdated_report_branch_v12_9.png) + +#### Target branch security report is out of date + +This can happen for many reasons, including failed jobs or new advisories. When the merge request shows that a +security report is out of date, you must run a new pipeline on the target branch. +You can do it quickly by following the hyperlink given to run a new pipeline. + +![Run a new pipeline](img/outdated_report_pipeline_v12_9.png) + ### Getting error message `sast job: stage parameter should be [some stage name here]` When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template -like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), +like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), the following error may occur, depending on your GitLab CI/CD configuration: ```plaintext @@ -441,7 +412,7 @@ This provides useful information to investigate further. ### Getting error message `sast job: config key may not be used with 'rules': only/except` When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template -like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), +like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml), the following error may occur, depending on your GitLab CI/CD configuration: ```plaintext diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index c9c65e94b32..77a15a37c55 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -5,7 +5,7 @@ group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Offline environments +# Offline environments **(ULTIMATE SELF)** It's possible to run most of the GitLab security scanners when not connected to the internet. @@ -64,9 +64,9 @@ Once a vulnerability is found, you can interact with it. Read more on how to Please note that in some cases the reported vulnerabilities provide metadata that can contain external links exposed in the UI. These links might not be accessible within an offline environment. -### Automatic remediation for vulnerabilities +### Resolving vulnerabilities -The [automatic remediation for vulnerabilities](../vulnerabilities/index.md#remediate-a-vulnerability-automatically) feature is available for offline Dependency Scanning and Container Scanning, but may not work +The [resolving vulnerabilities](../vulnerabilities/index.md#resolve-a-vulnerability) feature is available for offline Dependency Scanning and Container Scanning, but may not work depending on your instance's configuration. We can only suggest solutions, which are generally more current versions that have been patched, when we are able to access up-to-date registry services hosting the latest versions of that dependency or image. @@ -93,8 +93,7 @@ above. You can find more information at each of the pages below: ## Loading Docker images onto your offline host -To use many GitLab features, including -[security scans](../index.md#working-in-an-offline-environment) +To use many GitLab features, including security scans and [Auto DevOps](../../../topics/autodevops/index.md), the runner must be able to fetch the relevant Docker images. @@ -129,6 +128,10 @@ This method requires a runner with access to both `gitlab.com` (including to be able to use the `docker` command inside the jobs. This runner can be installed in a DMZ or on a bastion, and used only for this specific project. +WARNING: +This template does not include updates for the container scanning analyzer. Please see +[Container scanning offline directions](../container_scanning/index.md#running-container-scanning-in-an-offline-environment). + #### Scheduling the updates By default, this project's pipeline runs only once, when the `.gitlab-ci.yml` is added to the @@ -136,12 +139,6 @@ repository. To update the GitLab security scanners and signatures, it's necessar regularly. GitLab provides a way to [schedule pipelines](../../../ci/pipelines/schedules.md). For example, you can set this up to download and store the Docker images every week. -Some images can be updated more frequently than others. For example, the [vulnerability database](https://hub.docker.com/r/arminc/clair-db/tags) -for Container Scanning is updated daily. To update this single image, create a new Scheduled -Pipeline that runs daily and set `SECURE_BINARIES_ANALYZERS` to `clair-vulnerabilities-db`. Only -this job is triggered, and the image is updated daily and made available in the project -registry. - #### Using the secure bundle created The project using the `Secure-Binaries.gitlab-ci.yml` template should now host all the required diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 0e69f3b68eb..661a4ee8e82 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -48,7 +48,7 @@ GitLab, but users can also integrate their own **custom images**. For an analyzer to be considered Generally Available, it is expected to minimally support the following features: -- [Customizable configuration](index.md#available-variables) +- [Customizable configuration](index.md#available-cicd-variables) - [Customizable rulesets](index.md#customize-rulesets) - [Scan projects](index.md#supported-languages-and-frameworks) - [Multi-project support](index.md#multi-project-support) @@ -80,27 +80,6 @@ variables: This configuration requires that your custom registry provides images for all the official analyzers. -### Selecting specific analyzers - -WARNING: -`SAST_DEFAULT_ANALYZERS` is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50872) in GitLab 13.8, -and is scheduled for [removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/290777). - -You can select the official analyzers you want to run. Here's how to enable -`bandit` and `flawfinder` while disabling all the other default ones. -In `.gitlab-ci.yml` define: - -```yaml -include: - - template: Security/SAST.gitlab-ci.yml - -variables: - SAST_DEFAULT_ANALYZERS: "bandit,flawfinder" -``` - -`bandit` runs first. When merging the reports, SAST -removes the duplicates and keeps the `bandit` entries. - ### Disabling all default analyzers Setting `SAST_DISABLED` to `true` disables all the official diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 886726d5d67..c11e367a688 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -161,7 +161,7 @@ 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/README.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) +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. @@ -202,7 +202,7 @@ page: ### Customizing the SAST settings -The SAST settings can be changed through [CI/CD variables](#available-variables) +The SAST settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. In the following example, we include the SAST template and at the same time we @@ -239,6 +239,24 @@ spotbugs-sast: FAIL_NEVER: 1 ``` +#### Pinning to minor image version + +While our templates use `MAJOR` version pinning to always ensure the latest analyzer +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 are pinning to a specific patch version of the `spotbugs` analyzer: + +```yaml +include: + - template: Security/SAST.gitlab-ci.yml + +spotbugs-sast: + variables: + SAST_ANALYZER_IMAGE_TAG: "2.28.1" +``` + ### Customize rulesets **(ULTIMATE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235382) in GitLab 13.5. @@ -411,7 +429,7 @@ the vendored directory. This configuration can vary per analyzer but in the case can use `MAVEN_REPO_PATH`. See [Analyzer settings](#analyzer-settings) for the complete list of available options. -### Available variables +### Available CI/CD variables SAST can be [configured](#customizing-the-sast-settings) using CI/CD variables. @@ -454,9 +472,8 @@ The following are Docker image-related CI/CD variables. | CI/CD variable | Description | |---------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DEFAULT_ANALYZERS` | **DEPRECATED:** Override the names of default images. Scheduled for [removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/290777). | | `SAST_EXCLUDED_ANALYZERS` | Names of default images that should never run. Read more about [customizing analyzers](analyzers.md). | +| `SAST_ANALYZER_IMAGE_TAG` | Override the default version of analyzer image. Read more about [pinning the analyzer image version](#pinning-to-minor-image-version). | #### Vulnerability filters @@ -492,9 +509,10 @@ Some analyzers can be customized with CI/CD variables. | `MAVEN_REPO_PATH` | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | | `SBT_PATH` | SpotBugs | Path to the `sbt` executable. | | `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | -| `SAST_GOSEC_CONFIG` | Gosec | Path to configuration for Gosec (optional). | +| `SAST_GOSEC_CONFIG` | Gosec | **{warning}** **[Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328301)** in GitLab 14.0 - use custom rulesets instead. Path to configuration for Gosec (optional). | | `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | -| `SAST_DISABLE_BABEL` | NodeJsScan | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. | +| `SAST_DISABLE_BABEL` | NodeJsScan | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. +| `SAST_SEMGREP_METRICS` | Semgrep | Set to `"false"` to disable sending anonymized scan metrics to [r2c](https://r2c.dev/). Default: `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330565) in GitLab 14.0. | #### Custom CI/CD variables @@ -772,3 +790,7 @@ For Maven builds, add the following to your `pom.xml` file: ### 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/README.md#before_script) feature. + +### Semgrep slowness, unexpected results, or other errors + +If Semgrep is slow, reports too many false positives or false negatives, crashes, fails, or is otherwise broken, see the Semgrep docs for [troubleshooting GitLab SAST](https://semgrep.dev/docs/troubleshooting/gitlab-sast/). diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 02d117b1c0a..f4aa9dc2787 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -62,6 +62,9 @@ The [default ruleset provided by Gitleaks](https://gitlab.com/gitlab-org/securit - Password in URL - U.S. Social Security Number +WARNING: +Gitleaks does not support scanning binary files. + ## Requirements To run Secret Detection jobs, by default, you need GitLab Runner with the @@ -97,7 +100,8 @@ as shown in the following table: ## Configuration -> GitLab 13.1 splits Secret Detection from the [SAST configuration](../sast#configuration) into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then Secret Detection is already enabled. +> - In GitLab 13.1, Secret Detection was split from the [SAST configuration](../sast#configuration) into its own CI/CD template. If you're using GitLab 13.0 or earlier and SAST is enabled, then Secret Detection is already enabled. +> - [In GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/297269), Secret Detection jobs `secret_detection_default_branch` and `secret_detection` were consolidated into one job, `secret_detection`. Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Secret-Detection.gitlab-ci.yml) during the `secret-detection` job. It runs regardless of your app's programming language. @@ -160,7 +164,7 @@ that you can review and merge to complete the configuration. ### Customizing settings -The Secret Detection scan settings can be changed through [CI/CD variables](#available-variables) +The Secret Detection scan settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -174,7 +178,7 @@ is no longer supported. When overriding the template, you must use [`rules`](../ #### GIT_DEPTH -The [`GIT_DEPTH` CI/CD variable](../../../ci/runners/README.md#shallow-cloning) affects Secret Detection. +The [`GIT_DEPTH` CI/CD variable](../../../ci/runners/configure_runners.md#shallow-cloning) affects Secret Detection. The Secret Detection analyzer relies on generating patches between commits to scan content for secrets. If you override the default, ensure the value is greater than 1. If the number of commits in an MR is greater than the GIT_DEPTH value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). @@ -196,7 +200,7 @@ secret_detection: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -#### Available variables +#### Available CI/CD variables Secret Detection can be customized by defining available CI/CD variables: @@ -298,7 +302,7 @@ want to perform a full secret scan. Running a secret scan on the full history ca especially for larger repositories with lengthy Git histories. We recommend not setting this CI/CD variable as part of your normal job definition. -A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-variables)) +A new configuration variable ([`SECRET_DETECTION_HISTORIC_SCAN`](#available-cicd-variables)) can be set to change the behavior of the GitLab Secret Detection scan to run on the entire Git history of a repository. We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showcasing how you can perform a full history secret scan. @@ -396,7 +400,7 @@ ERRO[2020-11-18T18:05:52Z] object not found [ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2 ``` -To resolve the issue, set the [`GIT_DEPTH` CI/CD variable](../../../ci/runners/README.md#shallow-cloning) +To resolve the issue, set the [`GIT_DEPTH` CI/CD variable](../../../ci/runners/configure_runners.md#shallow-cloning) to a higher value. To apply this only to the Secret Detection job, the following can be added to your `.gitlab-ci.yml` file: 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 index 74592e2cea5..6578c0bf4cf 100644 Binary files a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png and b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png differ diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index f0b3d895df5..01de066367c 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -150,8 +150,7 @@ the following: ![Security Center Dashboard with projects](img/security_center_dashboard_v13_4.png) -To view the Security Center, from the navigation bar at the top of the page, select -**More > Security**. +To view the Security Center, on the top bar, select **Menu > Security**. ### Adding projects to the Security Center diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index 1316f1b9644..ce30accfb4d 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Secure and Protect terminology +# Secure and Protect terminology **(FREE)** This terminology list for GitLab Secure and Protect aims to: @@ -101,7 +101,7 @@ of the finding's [first identifier](https://gitlab.com/gitlab-org/security-produ combine to create the value. Examples of primary identifiers include `PluginID` for OWASP Zed Attack Proxy (ZAP), or `CVE` for -Klar. Note that the identifier must be stable. Subsequent scans must return the same value for the +Trivy. Note that the identifier must be stable. Subsequent scans must return the same value for the same finding, even if the location has slightly changed. ### Report finding @@ -122,7 +122,7 @@ The type of scan. This must be one of the following: ### Scanner Software that can scan for vulnerabilities. The resulting scan report is typically not in the -[Secure report format](#secure-report-format). Examples include ESLint, Klar, and ZAP. +[Secure report format](#secure-report-format). Examples include ESLint, Trivy, and ZAP. ### Secure product diff --git a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png index 1f02fd30f8e..e165c7e6ceb 100644 Binary files a/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png and b/doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png differ diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 825bc64d52b..e1200c60419 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -16,34 +16,8 @@ Monitoring** page. GitLab supports statistics for the following security features: -- [Web Application Firewall](../../clusters/applications.md#web-application-firewall-modsecurity) - [Container Network Policies](../../../topics/autodevops/stages.md#network-policy) -## Web Application Firewall - -The Web Application Firewall section provides metrics for the NGINX -Ingress controller and ModSecurity firewall. This section has the -following prerequisites: - -- Project has to have at least one [environment](../../../ci/environments/index.md). -- [Web Application Firewall](../../clusters/applications.md#web-application-firewall-modsecurity) has to be enabled. -- [Elastic Stack](../../clusters/applications.md#web-application-firewall-modsecurity) has to be installed. - -If you are using custom Helm values for the Elastic Stack you have to -configure Filebeat similarly to the [vendored values](https://gitlab.com/gitlab-org/gitlab/-/blob/f610a080b1ccc106270f588a50cb3c07c08bdd5a/vendor/elastic_stack/values.yaml). - -The **Web Application Firewall** section displays the following information -about your Ingress traffic: - -- The total amount of requests to your application -- The proportion of traffic that is considered anomalous according to - the configured rules -- The request breakdown graph for the selected time interval - -If a significant percentage of traffic is anomalous, you should -investigate it for potential threats by -[examining the Web Application Firewall logs](../../clusters/applications.md#web-application-firewall-modsecurity). - ## Container Network Policy > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32365) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. @@ -88,7 +62,7 @@ investigate it for potential threats by The **Threat Monitoring** page's **Policy** tab displays deployed network policies for all available environments. You can check a -network policy's `yaml` manifest, toggle the policy's enforcement +network policy's `yaml` manifest, its enforcement status, and create and edit deployed policies. This section has the following prerequisites: @@ -97,8 +71,7 @@ following prerequisites: Network policies are fetched directly from the selected environment's deployment platform. Changes performed outside of this tab are -reflected upon refresh. Enforcement status changes are deployed -directly to a deployment namespace of the selected environment. +reflected upon refresh. By default, the network policy list contains predefined policies in a disabled state. Once enabled, a predefined policy deploys to the @@ -115,8 +88,9 @@ users must make changes by following the To change a network policy's enforcement status: - Click the network policy you want to update. -- Click the **Enforcement status** toggle to update the selected policy. -- Click the **Apply changes** button to deploy network policy changes. +- Click the **Edit policy** button. +- Click the **Policy status** toggle to update the selected policy. +- Click the **Save changes** button to deploy network policy changes. Disabled network policies have the `network-policy.gitlab.com/disabled_by: gitlab` selector inside the `podSelector` block. This narrows the scope of such a policy and as a result it doesn't affect @@ -165,7 +139,8 @@ button at the bottom of the editor. ### Configuring Network Policy Alerts -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) and [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. +> - The feature flag was removed and the Threat Monitoring Alerts Project was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/287676) in GitLab 14.0. You can use policy alerts to track your policy's impact. Alerts are only available if you've [installed](../../clusters/agent/repository.md) @@ -186,25 +161,6 @@ There are two ways to create policy alerts: Once added, the UI updates and displays a warning about the dangers of too many alerts. -#### Enable or disable Policy Alerts **(ULTIMATE)** - -Policy Alerts is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:threat_monitoring_alerts) -``` - -To disable it: - -```ruby -Feature.disable(:threat_monitoring_alerts) -``` - ### Container Network Policy Alert list > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3438) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.9. diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png deleted file mode 100644 index 05ca74c3d5c..00000000000 Binary files a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png and /dev/null differ diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 965b856504d..9866709bacc 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -9,44 +9,47 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. -Each security vulnerability in a project's [Vulnerability Report](../vulnerability_report/index.md) has an individual page which includes: +Each vulnerability in a project has a Vulnerability Page. This page contains details of the +vulnerability. The details included vary according to the type of vulnerability. Details of each +vulnerability include: -- Details of the vulnerability. -- The status of the vulnerability in the project. -- Available actions for the vulnerability. -- Any issues related to the vulnerability. +- Description +- When it was detected +- Current status +- Available actions +- Linked issues +- Actions log On the vulnerability's page, you can: - [Change the vulnerability's status](#change-vulnerability-status). - [Create an issue](#create-an-issue-for-a-vulnerability). -- [Link issues to the vulnerability](#link-gitlab-issues-to-the-vulnerability). -- [Remediate a vulnerability automatically](#remediate-a-vulnerability-automatically), if an - automatic solution is available. -- [Remediate a vulnerability manually](#remediate-a-vulnerability-manually), if a solution is +- [Link issues to the vulnerability](#linked-issues). +- [Resolve a vulnerability](#resolve-a-vulnerability), if a solution is available. -## Change vulnerability status +## Vulnerability status values + +A vulnerability's status can be one of the following: -You can change the status of a vulnerability using the **Status** dropdown to one of -the following values: +| Status | Description | +|:----------|:------------| +| Detected | The default state for a newly discovered vulnerability. | +| Confirmed | A user has seen this vulnerability and confirmed it to be 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 and is no longer valid. | -| Status | Description | -|-----------|----------------------------------------------------------------------------------------------------------------| -| Detected | The default state for a newly discovered vulnerability | -| Confirmed | A user has seen this vulnerability and confirmed it to be accurate | -| Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved | -| Resolved | The vulnerability has been fixed and is no longer valid | +## Change vulnerability status -A timeline shows you when the vulnerability status has changed -and allows you to comment on a change. +To change a vulnerability's status, select a new value from the **Status** dropdown then select +**Change status**. Optionally, add a comment to the log entry at the bottom of the page. ## Create an issue for a vulnerability From a vulnerability's page you can create an issue to track all action taken to resolve or mitigate it. -From a vulnerability you can create either: +You can create either: - [A GitLab issue](#create-a-gitlab-issue-for-a-vulnerability) (default). - [A Jira issue](#create-a-jira-issue-for-a-vulnerability). @@ -68,14 +71,7 @@ The issue is then opened so you can take further action. ### Create a Jira issue for a vulnerability > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4677) in GitLab 13.9. -> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to -> [disable it](#enable-or-disable-jira-integration-for-vulnerabilities). - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/283850) in GitLab 13.12. Prerequisites: @@ -92,54 +88,47 @@ To create a Jira issue for a vulnerability: The Jira issue is created and opened in a new browser tab. The **Summary** and **Description** fields are pre-populated from the vulnerability's details. -### Enable or disable Jira integration for vulnerabilities **(ULTIMATE SELF)** - -The option to create a Jira issue for a vulnerability is under development but ready for production -use. It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:jira_for_vulnerabilities) -``` +Unlike GitLab issues, the status of whether a Jira issue is open or closed does not display in the GitLab user interface. -To disable it: - -```ruby -Feature.disable(:jira_for_vulnerabilities) -``` - -## Link GitLab issues to the vulnerability +## Linked issues NOTE: If Jira issue support is enabled, GitLab issues are disabled so this feature is not available. -You can link one or more existing GitLab issues to the vulnerability. This allows you to -indicate that this vulnerability affects multiple issues. It also allows you to indicate -that the resolution of one issue would resolve multiple vulnerabilities. - -Linked issues are shown in the Vulnerability Report and the vulnerability's page. +You can link one or more existing GitLab issues to a vulnerability. Adding a link helps track +the issue that resolves or mitigates a vulnerability. -## Link to an existing issue +Issues linked to a vulnerability are shown in the Vulnerability Report and the vulnerability's page. -If you already have an open issue, you can link to it from the vulnerability. +Be aware of the following conditions between a vulnerability and a linked issue: - The vulnerability page shows related issues, but the issue page doesn't show the vulnerability it's related to. - An issue can only be related to one vulnerability at a time. - Issues can be linked across groups and projects. -To link to an existing issue: +## Link to existing issues + +To link a vulnerability to existing issues: + +1. Go to the vulnerability's page. +1. In the **Linked issues** section, select the plus icon (**{plus}**). +1. For each issue to be linked, either: + - Paste a link to the issue. + - Enter the issue's ID (prefixed with a hash `#`). +1. Select **Add**. + +The selected issues are added to the **Linked issues** section, and the linked issues counter is updated. + +## Resolve a vulnerability -1. Open the vulnerability. -1. [Add a linked issue](../../project/issues/related_issues.md). +For some vulnerabilities a solution is already known. In those instances, a vulnerability's page +includes a **Resolve with merge request** option. -## Remediate a vulnerability automatically +To resolve a vulnerability, you can either: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5656) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.7. +- [Resolve a vulnerability with a merge request](#resolve-a-vulnerability-with-a-merge-request). +- [Resolve a vulnerability manually](#resolve-a-vulnerability-manually). -Some vulnerabilities can be fixed by applying the solution that GitLab automatically generates. The following scanners are supported: - [Dependency Scanning](../dependency_scanning/index.md). @@ -147,42 +136,33 @@ The following scanners are supported: `yarn`. - [Container Scanning](../container_scanning/index.md). -### Remediate a vulnerability manually +![Create merge request from vulnerability](img/create_mr_from_vulnerability_v13_4.png) -To manually apply the patch that GitLab generated for a vulnerability: +### Resolve a vulnerability with a merge request + +To resolve the vulnerability with a merge request, go to the vulnerability's page and from the +**Resolve with merge request** dropdown select **Resolve with merge request**. -1. Select the **Resolve with merge request** dropdown, then select **Download patch to resolve**: +A merge request is created which applies the patch required to resolve the vulnerability. +Process the merge request according to your standard workflow. - ![Resolve with Merge Request button dropdown](img/vulnerability_page_merge_request_button_dropdown_v13_1.png) +### Resolve a vulnerability manually +To manually apply the patch that GitLab generated for a vulnerability: + +1. Go to the vulnerability's page and from the **Resolve with merge request** dropdown select + **Download patch to resolve**. 1. Ensure your local project has the same commit checked out that was used to generate the patch. 1. Run `git apply remediation.patch`. 1. Verify and commit the changes to your branch. -### Create a merge request with the suggested patch - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9224) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9. - -In some cases, you can create a merge request that automatically remediates the -vulnerability. Any vulnerability that has a -[solution](#remediate-a-vulnerability-automatically) can have a merge -request created to automatically solve the issue. - -If this action is available: - -1. Select the **Resolve with merge request** dropdown, then select **Resolve with merge request**. - - ![Create merge request from vulnerability](img/create_mr_from_vulnerability_v13_4.png) - -A merge request is created. It applies the solution to the source branch. - ## Vulnerability scanner maintenance The following vulnerability scanners and their databases are regularly updated: | Secure scanning tool | Vulnerabilities database updates | |:----------------------------------------------------------------|----------------------------------| -| [Container Scanning](../container_scanning/index.md) | Uses either `trivy` or `clair`. For the `trivy` scanner, a job runs on a daily basis to build a new image with the latest vulnerability database updates from the [upstream `trivy-db`](https://github.com/aquasecurity/trivy-db). For the `clair` scanner, the latest `clair-db` version is used; `clair-db` database [is updated daily according to the author](https://github.com/arminc/clair-local-scan#clair-server-or-local). | +| [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). | | [Dynamic Application Security Testing (DAST)](../dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/master/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](../sast/index.md) | Relies exclusively on [the tools GitLab wraps](../sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | diff --git a/doc/user/application_security/vulnerabilities/severities.md b/doc/user/application_security/vulnerabilities/severities.md index 75366a49a55..f3e8e98bce3 100644 --- a/doc/user/application_security/vulnerabilities/severities.md +++ b/doc/user/application_security/vulnerabilities/severities.md @@ -5,7 +5,7 @@ group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Vulnerability severity levels +# Vulnerability severity levels **(ULTIMATE)** GitLab vulnerability analyzers attempt to return vulnerability severity level values whenever possible. The following is a list of available GitLab vulnerability severity levels, ranked from @@ -62,10 +62,9 @@ the following tables: ## Container Scanning -| GitLab scanner | Outputs severity levels? | Native severity level type | Native severity level example | +| GitLab analyzer | Outputs severity levels? | Native severity level type | Native severity level example | |------------------------------------------------------------------------|--------------------------|----------------------------|--------------------------------------------------------------| -| [`clair`](https://gitlab.com/gitlab-org/security-products/analyzers/klar) | **{check-circle}** Yes | String | `Negligible`, `Low`, `Medium`, `High`, `Critical`, `Defcon1` | -| [`trivy`](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning)| **{check-circle}** Yes | String | `Unknown`, `Low`, `Medium`, `High`, `Critical` | +| [`container-scanning`](https://gitlab.com/gitlab-org/security-products/analyzers/container-scanning)| **{check-circle}** Yes | String | `Unknown`, `Low`, `Medium`, `High`, `Critical` | ## Fuzz Testing diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index f68fb0c5cbb..07025d193af 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -128,10 +128,12 @@ To view the relevant file, select the filename in the vulnerability's details. ## View issues raised for a vulnerability The **Activity** column indicates the number of issues that have been created for the vulnerability. -Hover over an **Activity** entry and select a link go to that issue. +Hover over an **Activity** entry and select a link go to that issue. The status of whether the issue is open or closed also displays in the hover menu. ![Display attached issues](img/vulnerability_list_table_v13_9.png) +If Jira issue support is enabled, the issue link found in the Activity entry links out to the issue in Jira. Unlike GitLab issues, the status of whether a Jira issue is Open or Closed does not display in the GitLab UI. + ## Change status of vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292636) in GitLab 13.10, all statuses became selectable. diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 5e272f2a816..414ed8377db 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -462,7 +462,7 @@ The setup process follows the same steps as [GitOps](#get-started-with-gitops-an with the following differences: - When you define a configuration repository, you must do so with [Cilium settings](#define-a-configuration-repository-with-cilium-settings). -- You do not need to create a `manifest.yaml`. +- You do not need to specify the `gitops` configuration section. ### Define a configuration repository with Cilium settings @@ -486,7 +486,7 @@ cilium: ## Management interfaces Users with at least the [Developer](../../permissions.md) can access the user interface -for the GitLab Kubernetes agent at **Operations > Kubernetes** under the +for the GitLab Kubernetes agent at **Infrastructure > Kubernetes clusters**, under the **GitLab Agent managed clusters** tab. This page lists all registered agents for the current project, and the configuration directory for each agent: diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index 49e5e8c58df..cd40cc6810e 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -8,6 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -38,16 +39,7 @@ with Kubernetes resource definitions in YAML or JSON format. The Agent monitors each project you declare, and when the project changes, GitLab deploys the changes using the Agent. -To use multiple YAML files, specify a `paths` attribute in the `gitops` section. - -By default, the Agent monitors all -[Kubernetes object types](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields). -You can exclude some types of resources from monitoring. This enables you to reduce -the permissions needed by the GitOps feature, through `resource_exclusions`. - -To enable a specific named resource, first use `resource_inclusions` to enable desired resources. -The following file excerpt includes specific `api_groups` and `kinds`. The `resource_exclusions` -which follow excludes all other `api_groups` and `kinds`: +To use multiple YAML files, specify a `paths` attribute in the `gitops.manifest_projects` section. ```yaml gitops: @@ -58,28 +50,6 @@ gitops: # The `id` is a path to a Git repository with Kubernetes resource definitions # in YAML or JSON format. - id: gitlab-org/cluster-integration/gitlab-agent - # Holds the only API groups and kinds of resources that gitops will monitor. - # Inclusion rules are evaluated first, then exclusion rules. - # If there is still no match, resource is monitored. - # Resources: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields - # Groups: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups-and-versioning - resource_inclusions: - - api_groups: - - apps - kinds: - - '*' - - api_groups: - - '' - kinds: - - 'ConfigMap' - # Holds the API groups and kinds of resources to exclude from gitops watch. - # Inclusion rules are evaluated first, then exclusion rules. - # If there is still no match, resource is monitored. - resource_exclusions: - - api_groups: - - '*' - kinds: - - '*' # Namespace to use if not set explicitly in object manifest. default_namespace: my-ns # Paths inside of the repository to scan for manifest files. @@ -93,6 +63,87 @@ gitops: - glob: '/team2/apps/**/*.yaml' # If 'paths' is not specified or is an empty list, the configuration below is used - glob: '/**/*.{yaml,yml,json}' + # Reconcile timeout defines whether the applier should wait + # until all applied resources have been reconciled, and if so, + # how long to wait. + reconcile_timeout: 3600s # 1 hour by default + # Dry run strategy defines whether changes should actually be performed, + # or if it is just talk and no action. + # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/common/common.go#L68-L89 + # Can be: none, client, server + dry_run_strategy: none # 'none' by default + # Prune defines whether pruning of previously applied + # objects should happen after apply. + prune: true # enabled by default + # Prune timeout defines whether we should wait for all resources + # to be fully deleted after pruning, and if so, how long we should + # wait. + prune_timeout: 3600s # 1 hour by default + # Prune propagation policy defines the deletion propagation policy + # that should be used for pruning. + # https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470 + # Can be: orphan, background, foreground + prune_propagation_policy: foreground # 'foreground' by default + # InventoryPolicy defines if an inventory object can take over + # objects that belong to another inventory object or don't + # belong to any inventory object. + # This is done by determining if the apply/prune operation + # can go through for a resource based on the comparison + # the inventory-id value in the package and the owning-inventory + # annotation in the live object. + # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66 + # Can be: must_match, adopt_if_no_inventory, adopt_all + inventory_policy: must_match # 'must_match' by default +``` + +### Using multiple manifest projects + +Storing Kubernetes manifests in more than one repository can be handy, for example: + +- You may store manifests for different applications in separate repositories. +- Different teams can work on manifests of independent projects in separate repositories. + +To use multiple repositories as the source of Kubernetes manifests, specify them in the list of +`manifest_projects` in your `config.yaml`: + +```yaml +gitops: + manifest_projects: + - id: group1/project1 + - id: group2/project2 +``` + +Note that repositories are synchronized **concurrently** and **independently** from each other, +which means that, ideally, there should **not** be any dependencies shared by these repositories. +Storing a logical group of manifests in a single repository may work better than distributing it across several +repositories. + +You cannot use a single repository as a source for multiple concurrent synchronization +operations. If such functionality is needed, you may use multiple agents reading +manifests from the same repository. + +Ensure not to specify "overlapping" globs to avoid synchronizing the same files more than once. +This is detected by the GitLab Kubernetes Agent and leads to an error. + +INCORRECT - both globs match `*.yaml` files in the root directory: + +```yaml +gitops: + manifest_projects: + - id: project1 + paths: + - glob: '/**/*.yaml' + - glob: '/*.yaml' +``` + +CORRECT - single globs matches all `*.yaml` files recursively: + +```yaml +gitops: + manifest_projects: + - id: project1 + paths: + - glob: '/**/*.yaml' ``` ## Surface network security alerts from cluster to GitLab diff --git a/doc/user/clusters/agent/runner.md b/doc/user/clusters/agent/runner.md index bbf07d4ea84..c40733bd7a5 100644 --- a/doc/user/clusters/agent/runner.md +++ b/doc/user/clusters/agent/runner.md @@ -1,5 +1,6 @@ --- redirect_to: 'https://docs.gitlab.com/runner/install/kubernetes-agent.html' +remove_date: '2022-02-01' --- This document was moved to [another location](https://docs.gitlab.com/runner/install/kubernetes-agent.html). diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 212823853e4..a6aa4e00005 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -6,12 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Managed Apps (DEPRECATED) **(FREE)** +NOTE: +The new recommended way to manage cluster applications is to use the [cluster management project template](management_project_template.md). +If you want to migrate your GitLab managed apps management to this template, reference to [migrating from GitLab managed apps to project template](migrating_from_gma_to_project_template.md). + **GitLab Managed Apps** was created to help you configure applications in your cluster directly from GitLab. You could use this feature through two different methods: "one-click install" and "CI/CD template". Both methods are **deprecated**: -- The **one-click install** method was deprecated in GitLab 13.9 and **will be - removed** in GitLab 14.0. +- The **one-click install** method was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63348) in GitLab 14.0. - The **CI/CD template method** was deprecated in GitLab 13.12 and is scheduled to be removed in GitLab 15.0. @@ -19,23 +22,17 @@ Both methods were limiting as you couldn't fully customize your third-party apps through GitLab Managed Apps. Therefore, we decided to deprecate this feature and provide better [GitOps-driven alternatives](https://about.gitlab.com/direction/configure/kubernetes_management/#gitlab-managed-applications) to our users, such as [cluster integrations](integrations.md#cluster-integrations) and [cluster management project](management_project.md). -Read the sections below according to the installation method you chose to -learn how to proceed to keep your apps up and running: - -- [One-click install method](#install-with-one-click-deprecated) -- [CI/CD template method](#install-using-gitlab-cicd-deprecated) - ## Install using GitLab CI/CD (DEPRECATED) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/327908) in GitLab 13.12. WARNING: -The GitLab Managed Apps CI/CD installation method was [deprecated in 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/327908). +The GitLab Managed Apps CI/CD installation method was [deprecated in 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/327908). Your applications continue to work. However, we no longer support and maintain the GitLab CI/CD template for Managed Apps (`Managed-Cluster-Applications.gitlab-ci.yml`). -As a replacement, we are working on a [cluster management project template](https://gitlab.com/gitlab-org/gitlab/-/issues/327908), -still to be released. +The new recommended way to manage cluster applications is to use the [cluster management project template](management_project_template.md). +If you want to migrate your GitLab managed apps management to this template, reference to [migrating from GitLab managed apps to project template](migrating_from_gma_to_project_template.md). The CI/CD template was the primary method for installing applications to clusters via GitLab Managed Apps and customize them through Helm. @@ -401,6 +398,10 @@ These values can be specified using [CI/CD variables](../../ci/variables/README. - `GITLAB_RUNNER_GITLAB_URL` is used for `gitlabUrl`. - `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` +The methods of specifying these values are mutually exclusive. Either specify variables `GITLAB_RUNNER_REGISTRATION_TOKEN` and `GITLAB_RUNNER_TOKEN` as CI variables (recommended) or provide values for `runnerRegistrationToken:` and `runnerToken:` in `.gitlab/managed-apps/gitlab-runner/values.yaml`. If you choose to use CI variables, comment out or remove `runnerRegistrationToken:` and `runnerToken:` from `.gitlab/managed-apps/gitlab-runner/values`. + +The runner registration token allows connection to a project by a runner and therefore should be treated as a secret to prevent malicious use and code exfiltration through a runner. For this reason, we recommend that you specify the runner registration token as a [protected variable](../../ci/variables/README.md#protect-a-cicd-variable) and [masked variable](../../ci/variables/README.md#mask-a-cicd-variable) and do not commit them to the Git repository in the `values.yaml` file. + You can customize the installation of GitLab Runner by defining `.gitlab/managed-apps/gitlab-runner/values.yaml` file in your cluster management project. Refer to the @@ -453,7 +454,7 @@ for the available configuration options. You can check Cilium's installation status on the cluster management page: - [Project-level cluster](../project/clusters/index.md): Navigate to your project's - **Operations > Kubernetes** page. + **Infrastructure > Kubernetes clusters** page. - [Group-level cluster](../group/clusters/index.md): Navigate to your group's **Kubernetes** page. @@ -462,7 +463,10 @@ Installation and removal of the Cilium requires a **manual** [restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#restart-unmanaged-pods) of all affected pods in all namespaces to ensure that they are [managed](https://docs.cilium.io/en/v1.8/operations/troubleshooting/#ensure-managed-pod) -by the correct networking plugin. +by the correct networking plugin. Whenever Hubble is enabled, its related pod might require a +restart depending on whether it started prior to Cilium. For more information, see +[Failed Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#failed-deployment) +in the Kubernetes docs. NOTE: Major upgrades might require additional setup steps. For more information, see @@ -814,11 +818,6 @@ management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all available configuration options. -NOTE: -In this alpha implementation of installing Elastic Stack through CI, reading the -environment logs through Elasticsearch is unsupported. This is supported if -[installed with the UI](#elastic-stack). - Support for installing the Elastic Stack managed application is provided by the GitLab APM group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at @@ -1026,691 +1025,37 @@ GitLab Container Security group. If you run into unknown issues, at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). -## Browse applications logs - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36769) in GitLab 13.2. - -Logs produced by pods running **GitLab Managed Apps** can be browsed using -[**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). - -## Install with one click (DEPRECATED) - -WARNING: -The one-click installation method was deprecated in GitLab 13.9 and will be removed in [GitLab 14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). -The removal does not break nor uninstall any apps you have installed but removes the GitLab UI page -for installing and updating your GitLab Managed Apps. -Follow the process to [take ownership of your GitLab Managed Apps](#take-ownership-of-your-gitlab-managed-apps). - -Applications managed by GitLab are installed onto the `gitlab-managed-apps` -namespace. This namespace: - -- Is different from the namespace used for project deployments. -- Is created once. -- Has a non-configurable name. - -To view a list of available applications to install for a: - -- [Project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes**. -- [Group-level cluster](../group/clusters/index.md), navigate to your group's - **Kubernetes** page. - -You can install the following applications with one click: - -- [Helm](#helm) -- [Ingress](#ingress) -- [cert-manager](#cert-manager) -- [Prometheus](#prometheus) -- [GitLab Runner](#gitlab-runner) -- [JupyterHub](#jupyterhub) -- [Knative](#knative) -- [Crossplane](#crossplane) -- [Elastic Stack](#elastic-stack) -- [Fluentd](#fluentd) - -With the exception of Knative, the applications are installed in a dedicated -namespace called `gitlab-managed-apps`. - -Some applications are installable only for a project-level cluster. -Support for installing these applications in a group-level cluster is -planned for future releases. -For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411). - -WARNING: -If you have an existing Kubernetes cluster with Helm already installed, -you should be careful as GitLab cannot detect it. In this case, installing -Helm with the applications results in the cluster having it twice, which -can lead to confusion during deployments. - -In GitLab versions 11.6 and greater, Helm is upgraded to the latest version -supported by GitLab before installing any of the applications. - -### Helm - -> - Introduced in GitLab 10.2 for project-level clusters. -> - Introduced in GitLab 11.6 for group-level clusters. -> - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 and later. -> - [Uses Helm 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46267) for clusters created with GitLab 13.6 and later. -> - [Offers legacy Tiller removal](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47457) in GitLab 13.7 and later. - -[Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is -used to install the GitLab-managed apps. GitLab runs each `helm` command -in a pod in the `gitlab-managed-apps` namespace inside the cluster. - -- For clusters created in GitLab 13.6 and newer, GitLab uses Helm 3 to manage - applications. -- For clusters created on versions of GitLab prior to 13.6, GitLab uses Helm 2 - with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. Prior - to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), GitLab - used an in-cluster Tiller server in the `gitlab-managed-apps` namespace. You - can safely uninstall the server from the GitLab application page if you have - previously installed it. This doesn't affect your other applications. - -The GitLab Helm integration does not support installing applications behind a proxy, -but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) -is available. - -#### Upgrade a cluster to Helm 3 - -GitLab does not offer a way to migrate existing application management -on existing clusters from Helm 2 to Helm 3. To migrate a cluster to Helm 3: - -1. Uninstall all applications on your cluster. -1. [Remove the cluster integration](../project/clusters/add_remove_clusters.md#removing-integration). -1. [Re-add the cluster](../project/clusters/add_remove_clusters.md#existing-kubernetes-cluster) as - an existing cluster. - -### cert-manager - -> Introduced in GitLab 11.6 for project- and group-level clusters. - -[cert-manager](https://cert-manager.io/docs/) is a native Kubernetes certificate -management controller that helps with issuing certificates. Installing -cert-manager on your cluster issues a certificate by [Let's Encrypt](https://letsencrypt.org/) -and ensures that certificates are valid and up-to-date. - -The chart used to install this application depends on the version of GitLab used. In: - -- GitLab 12.3 and newer, the [`jetstack/cert-manager`](https://github.com/jetstack/cert-manager) - chart is used with a - [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/cert_manager/values.yaml) - file. -- GitLab 12.2 and older, the - [`stable/cert-manager`](https://github.com/helm/charts/tree/master/stable/cert-manager) - chart was used. - -If you installed cert-manager prior to GitLab 12.3, Let's Encrypt -[blocks requests](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) -from older versions of `cert-manager`. To resolve this: - -1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). -1. Uninstall cert-manager. -1. Install cert-manager again. - -### GitLab Runner - -> - Introduced in GitLab 10.6 for project-level clusters. -> - Introduced in GitLab 11.10 for group-level clusters. - -[GitLab Runner](https://docs.gitlab.com/runner/) is the open source project that -is used to run your jobs and send the results back to GitLab. It's used in -conjunction with [GitLab CI/CD](../../ci/README.md), the open-source continuous -integration service included with GitLab that coordinates the jobs. - -If the project is on GitLab.com, [shared runners](../gitlab_com/index.md#shared-runners) -are available. You don't have to deploy one if they are enough for your -needs. If a project-specific runner is desired, or there are no shared runners, -you can deploy one. - -The deployed runner is set as **privileged**. Root access to the underlying -server is required to build Docker images, so it's the default. Be sure to read -the [security implications](../project/clusters/index.md#security-implications) -before deploying one. - -The [`runner/gitlab-runner`](https://gitlab.com/gitlab-org/charts/gitlab-runner) -chart is used to install this application, using -[a preconfigured `values.yaml`](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/master/values.yaml) -file. Customizing the installation by modifying this file is not supported. This -also means you cannot modify `config.toml` file for this Runner. If you want to -have that possibility and still deploy Runner in Kubernetes, consider using the -[Cluster management project](management_project.md) or installing Runner manually -via [GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html). - -### Ingress - -> - Introduced in GitLab 10.2 for project-level clusters. -> - Introduced in GitLab 11.6 for group-level clusters. - -[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) -provides load balancing, SSL termination, and name-based virtual hosting -out of the box. It acts as a web proxy for your applications and is useful -if you want to use [Auto DevOps](../../topics/autodevops/index.md) or deploy your own web apps. - -The Ingress Controller installed is -[Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/), -which is supported by the Kubernetes community. - -With the following procedure, a load balancer must be installed in your cluster -to obtain the endpoint. You can use either -Ingress, or Knative's own load balancer ([Istio](https://istio.io)) if using Knative. - -To publish your web application, you first need to find the endpoint, which is either an IP -address or a hostname associated with your load balancer. - -To install it, click on the **Install** button for Ingress. GitLab attempts -to determine the external endpoint and it should be available in a few minutes. - -#### Determining the external endpoint automatically - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17052) in GitLab 10.6. - -After you install Ingress, the external endpoint should be available in a few minutes. - -NOTE: -This endpoint can be used for the -[Auto DevOps base domain](../../topics/autodevops/index.md#auto-devops-base-domain) -using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. - -If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: - -1. [Examine your Kubernetes cluster](https://console.cloud.google.com/kubernetes) - on Google Kubernetes Engine to ensure there are no errors on its nodes. -1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) - on Google Kubernetes Engine. For more information, see - [Resource Quotas](https://cloud.google.com/compute/quotas). -1. Review [Google Cloud's Status](https://status.cloud.google.com/) for service - disruptions. - -The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) -file. - -After installing, you may see a `?` for **Ingress IP Address** depending on the -cloud provider. For EKS specifically, this is because the ELB is created -with a DNS name, not an IP address. If GitLab is still unable to -determine the endpoint of your Ingress or Knative application, you can -[determine it manually](#determining-the-external-endpoint-manually). - -#### Determining the external endpoint manually - -See the [Base domain section](../project/clusters/index.md#base-domain) for a -guide on how to determine the external endpoint manually. - -#### Using a static IP - -By default, an ephemeral external IP address is associated to the cluster's load -balancer. If you associate the ephemeral IP with your DNS and the IP changes, -your apps aren't reachable, and you'd have to change the DNS record again. -To avoid that, change it into a static reserved IP. - -Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). - -#### Pointing your DNS at the external endpoint - -After you have set up the external endpoint, associate it with a -[wildcard DNS record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) (such -as `*.example.com.`) to reach your apps. If your external endpoint is an IP -address, use an A record. If your external endpoint is a hostname, use a CNAME -record. - -#### Web Application Firewall (ModSecurity) - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. - -WARNING: -The Web Application Firewall is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/271276) -in GitLab 13.6, and planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/271349) -in GitLab 14.0. - -A Web Application Firewall (WAF) examines traffic being sent or received, -and can block malicious traffic before it reaches your application. The benefits -of a WAF are: - -- Real-time security monitoring for your application. -- Logging of all your HTTP traffic to the application. -- Access control for your application. -- Highly configurable logging and blocking rules. - -By default, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/), -which is a toolkit for real-time web application monitoring, logging, and access -control. GitLab applies the [OWASP's Core Rule Set](https://coreruleset.org/), -which provides generic attack detection capabilities. - -This feature: - -- Runs in "Detection-only mode" unless configured otherwise. -- Is viewable by checking your Ingress controller's `modsec` log for rule violations. - For example: - - ```shell - kubectl -n gitlab-managed-apps logs -l app=nginx-ingress,component=controller -c modsecurity-log -f - ``` - -To enable WAF, switch its respective toggle to the enabled position when installing -or updating [Ingress application](#ingress). - -If this is your first time using the GitLab WAF, we recommend you follow the -[quick start guide](../project/clusters/protect/web_application_firewall/quick_start_guide.md). - -There is a small performance overhead by enabling ModSecurity. If this is -considered significant for your application, you can disable ModSecurity's -rule engine for your deployed application in any of the following ways: - -1. Set the [deployment variable](../../topics/autodevops/index.md) - `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off` to prevent ModSecurity - from processing any requests for the given application or environment. -1. Switch its respective toggle to the disabled position, and then apply changes - by selecting **Save changes** to reinstall Ingress with the recent changes. - -![Disabling WAF](../project/clusters/protect/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png) - -##### Logging and blocking modes - -To help you tune your WAF rules, you can globally set your WAF to either -*Logging* or *Blocking* mode: - -- *Logging mode*: Allows traffic matching the rule to pass, and logs the event. -- *Blocking mode*: Prevents traffic matching the rule from passing, and logs the event. - -To change your WAF's mode: - -1. If you haven't already done so, - [install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md). -1. Navigate to **Operations > Kubernetes**. -1. In **Applications**, scroll to **Ingress**. -1. Under **Global default**, select your desired mode. -1. Select **Save changes**. - -##### WAF version updates - -Enabling, disabling, or changing the logging mode for **ModSecurity** is only -allowed in same version of [Ingress](#ingress) due to limitations in -[Helm](https://helm.sh/) which might be overcome in future releases. - -The **ModSecurity** user interface controls are disabled if the version deployed -differs from the one available in GitLab. However, actions at the [Ingress](#ingress) -level, such as uninstalling, can still be performed: - -![WAF settings disabled](../project/clusters/protect/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png) - -Update [Ingress](#ingress) to the most recent version to take advantage of bug -fixes, security fixes, and performance improvements. To update the -[Ingress application](#ingress), you must first uninstall it, and then re-install -it as described in [Install ModSecurity](../project/clusters/protect/web_application_firewall/quick_start_guide.md). - -##### Viewing Web Application Firewall traffic - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. - -You can view Web Application Firewall traffic by navigating to your project's -**Security & Compliance > Threat Monitoring** page. From there, you can see -tracked over time: - -- The total amount of traffic to your application. -- The proportion of traffic that's considered anomalous by the Web Application - Firewall's default [OWASP ruleset](https://coreruleset.org/). - -If a significant percentage of traffic is anomalous, investigate it for potential threats -by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). - -![Threat Monitoring](img/threat_monitoring_v12_9.png) - -### JupyterHub - -> - Introduced in GitLab 11.0 for project-level clusters. -> - Introduced in GitLab 12.3 for group and instance-level clusters. - -[JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service -for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) -provide a web-based interactive programming environment used for data analysis, -visualization, and machine learning. - -The [`jupyter/jupyterhub`](https://jupyterhub.github.io/helm-chart/) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/jupyter/values.yaml) -file. - -Authentication is enabled only for [project members](../project/members/index.md) -for project-level clusters and group members for group-level clusters with -[Developer or higher](../permissions.md) access to the associated project or group. - -GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) -that installs additional relevant packages on top of the base Jupyter. Ready-to-use -DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix) -are also available. +## Install with one click (REMOVED) -More information on creating executable runbooks can be found in -[our Runbooks documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). -Ingress must be installed and have an IP address assigned before -JupyterHub can be installed. +> [Removed](https://gitlab.com/groups/gitlab-org/-/epics/4280) in GitLab 14.0. -#### Jupyter Git Integration +The one-click installation method was deprecated in GitLab 13.9 and removed in [GitLab 14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). +The removal does not break nor uninstall any apps you have installed, it only +removes the "Applications" tab from the cluster page. +The new recommended way to manage cluster applications is to use the [cluster management project template](management_project_template.md). -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28783) in GitLab 12.0 for project-level clusters. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/32512) in GitLab 12.3 for group and instance-level clusters. +- If you want to migrate your GitLab managed apps management to this template, read + [migrating from GitLab managed apps to project template](migrating_from_gma_to_project_template.md). +- If you don't want to use the template, you can also manually manage your applications. + For that, follow the process to + [take ownership of your GitLab Managed Apps](#take-ownership-of-your-gitlab-managed-apps). -When installing JupyterHub onto your Kubernetes cluster, -[JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) -is provisioned and configured using the authenticated user's: +If you are not yet on GitLab 14.0 or later, you can refer to [an older version of this document](https://docs.gitlab.com/13.12/ee/user/clusters/applications.html#install-with-one-click-deprecated). -- Name. -- Email. -- Newly created access token. - -JupyterLab's Git extension enables full version control of your notebooks, and -issuance of Git commands in Jupyter. You can issue Git commands through the -**Git** tab on the left panel, or through Jupyter's command-line prompt. - -JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted -format, and in the single user Jupyter instance as plain text, because -[Git requires storing credentials as plain text](https://git-scm.com/docs/git-credential-store) -Potentially, if a nefarious user finds a way to read from the file system in the -single-user Jupyter instance, they could retrieve the token. - -![Jupyter's Git Extension](img/jupyter-git-extension.gif) - -You can clone repositories from the files tab in Jupyter: - -![Jupyter clone repository](img/jupyter-gitclone.png) - -### Knative - -> - Introduced in GitLab 11.5 for project-level clusters. -> - Introduced in GitLab 12.3 for group- and instance-level clusters. - -[Knative](https://cloud.google.com/knative/) provides a platform to -create, deploy, and manage serverless workloads from a Kubernetes -cluster. It's used in conjunction with, and includes -[Istio](https://istio.io) to provide an external IP address for all -programs hosted by Knative. - -The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) -chart is used to install this application. - -During installation, you must enter a wildcard domain where your applications -are exposed. Configure your DNS server to use the external IP address for that -domain. Applications created and installed are accessible as -`..`, which requires -your Kubernetes cluster to have -[RBAC enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). - -### Prometheus - -> - Introduced in GitLab 10.4 for project-level clusters. -> - Introduced in GitLab 11.11 for group-level clusters. - -[Prometheus](https://prometheus.io/docs/introduction/overview/) is an -open-source monitoring and alerting system you can use to supervise your -deployed applications. - -GitLab is able to monitor applications by using the -[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and -memory metrics are collected, and response metrics are also retrieved -from NGINX Ingress. - -The [`stable/prometheus`](https://github.com/helm/charts/tree/master/stable/prometheus) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/prometheus/values.yaml) -file. - -To enable monitoring, install Prometheus into the cluster with the **Install** -button. - -### Crossplane - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34702) in GitLab 12.5 for project-level clusters. - -[Crossplane](https://crossplane.github.io/docs/v0.9/) is a multi-cloud control plane -to help you manage applications and infrastructure across multiple clouds. It extends the -Kubernetes API using: - -- Custom resources. -- Controllers that watch those custom resources. - -Crossplane allows provisioning and lifecycle management of infrastructure components -across cloud providers in a uniform manner by abstracting cloud provider-specific -configurations. - -The Crossplane GitLab-managed application: - -- Installs Crossplane with a provider of choice on a Kubernetes cluster attached to the - project repository. -- Can then be used to provision infrastructure or managed applications such as - PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services - required by the application with the Auto DevOps pipeline. - -[`alpha/crossplane`](https://github.com/crossplane/crossplane/tree/v0.4.1/cluster/charts/crossplane) chart v0.4.1 is used to -install Crossplane using the -[`values.yaml`](https://github.com/crossplane/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) -file. - -For information about configuring Crossplane installed on the cluster, see -[Crossplane configuration](crossplane.md). - -### Elastic Stack - -> Introduced in GitLab 12.7 for project- and group-level clusters. - -[Elastic Stack](https://www.elastic.co/elastic-stack) is a complete end-to-end -log analysis solution which helps in deep searching, analyzing and visualizing the logs -generated from different machines. - -GitLab can gather logs from pods in your cluster. Filebeat runs as a DaemonSet -on each node in your cluster, and ships container logs to Elasticsearch for -querying. GitLab then connects to Elasticsearch for logs, instead of the -Kubernetes API, giving you access to more advanced querying capabilities. Log -data is deleted after 30 days, using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). - -The Elastic Stack cluster application is intended as a log aggregation solution -and is not related to our [Advanced Search](../search/advanced_search.md) -functionality, which uses a separate Elasticsearch cluster. - -To enable log shipping: - -1. Ensure your cluster contains at least three nodes of instance types larger - than `f1-micro`, `g1-small`, or `n1-standard-1`. -1. Navigate to **Operations > Kubernetes**. -1. In **Kubernetes Cluster**, select a cluster. -1. In the **Applications** section, find **Elastic Stack**, and then select - **Install**. - -The [`gitlab/elastic-stack`](https://gitlab.com/gitlab-org/charts/elastic-stack) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/elastic_stack/values.yaml) -file. The chart deploys three identical Elasticsearch pods which can't be -colocated, and each requires one CPU and 2 GB of RAM, making them -incompatible with clusters containing fewer than three nodes, or consisting of -`f1-micro`, `g1-small`, `n1-standard-1`, or `*-highcpu-2` instance types. - -#### Optional: deploy Kibana to perform advanced queries - -If you are an advanced user and have direct access to your Kubernetes cluster -using `kubectl` and `helm`, you can deploy Kibana manually. The following assumes -that `helm` has been [initialized](https://v2.helm.sh/docs/helm/) with `helm init`. - -Save the following to `kibana.yml`: - -```yaml -elasticsearch: - enabled: false - -filebeat: - enabled: false - -kibana: - enabled: true - elasticsearchHosts: http://elastic-stack-elasticsearch-master.gitlab-managed-apps.svc.cluster.local:9200 -``` - -Then install it on your cluster: - -```shell -helm repo add gitlab https://charts.gitlab.io -helm install --name kibana gitlab/elastic-stack --values kibana.yml -``` - -To access Kibana, forward the port to your local machine: - -```shell -kubectl port-forward svc/kibana-kibana 5601:5601 -``` - -Then, you can visit Kibana at `http://localhost:5601`. - -### Fluentd - -> Introduced in GitLab 12.10 for project- and group-level clusters. - -[Fluentd](https://www.fluentd.org/) is an open source data collector, which enables -you to unify the data collection and consumption to better use and understand -your data. Fluentd sends logs in syslog format. - -To enable Fluentd: - -1. Navigate to **Operations > Kubernetes** and click - **Applications**. Enter a host, port, and protocol - for sending the WAF logs with syslog. -1. Provide the host domain name or URL in **SIEM Hostname**. -1. Provide the host port number in **SIEM Port**. -1. Select a **SIEM Protocol**. -1. Select at least one of the available logs (such as WAF or Cilium). -1. Click **Save changes**. - -![Fluentd input fields](img/fluentd_v13_0.png) - -## Upgrading applications - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24789) in GitLab 11.8. - -The applications below can be upgraded. - -| Application | GitLab version | -| ----------- | -------------- | -| GitLab Runner | 11.8+ | - -To upgrade an application: - -1. For a: - - [Project-level cluster](../project/clusters/index.md), - navigate to your project's **Operations > Kubernetes**. - - [Group-level cluster](../group/clusters/index.md), - navigate to your group's **Kubernetes** page. -1. Select your cluster. -1. If an upgrade is available, the **Upgrade** button is displayed. Click the button to upgrade. - -Upgrades reset values back to the values built into the `runner` chart, plus the values set by -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/runner/values.yaml) - -## Uninstalling applications - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/60665) in GitLab 11.11. - -The applications below can be uninstalled. - -| Application | GitLab version | Notes | -| ----------- | -------------- | ----- | -| cert-manager | 12.2+ | The associated private key is deleted and cannot be restored. Deployed applications continue to use HTTPS, but certificates aren't renewed. Before uninstalling, you may want to [back up your configuration](https://cert-manager.io/docs/tutorials/backup/) or [revoke your certificates](https://letsencrypt.org/docs/revoking/). | -| GitLab Runner | 12.2+ | Any running pipelines are canceled. | -| Helm | 12.2+ | The associated Tiller pod, the `gitlab-managed-apps` namespace, and all of its resources are deleted and cannot be restored. | -| Ingress | 12.1+ | The associated load balancer and IP are deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed. | -| JupyterHub | 12.1+ | All data not committed to GitLab are deleted and cannot be restored. | -| Knative | 12.1+ | The associated IP are deleted and cannot be restored. | -| Prometheus | 11.11+ | All data are deleted and cannot be restored. | -| Crossplane | 12.5+ | All data are deleted and cannot be restored. | -| Elastic Stack | 12.7+ | All data are deleted and cannot be restored. | -| Sentry | 12.6+ | The PostgreSQL persistent volume remains and should be manually removed for complete uninstall. | - -To uninstall an application: - -1. For a: - - [Project-level cluster](../project/clusters/index.md), - navigate to your project's **Operations > Kubernetes**. - - [Group-level cluster](../group/clusters/index.md), - navigate to your group's **Kubernetes** page. -1. Select your cluster. -1. Click the **Uninstall** button for the application. - -Support for uninstalling all applications is planned for progressive rollout. -To follow progress, see the [relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/1201). - -## Troubleshooting applications - -Applications can fail with the following error: - -```plaintext -Error: remote error: tls: bad certificate -``` - -To avoid installation errors: - -- Before starting the installation of applications, make sure that time is synchronized - between your GitLab server and your Kubernetes cluster. -- Ensure certificates are not out of sync. When installing applications, GitLab - expects a new cluster with no previous installation of Helm. - - You can confirm that the certificates match by using `kubectl`: - - ```shell - kubectl get configmaps/values-content-configuration-ingress -n gitlab-managed-apps -o \ - "jsonpath={.data['cert\.pem']}" | base64 -d > a.pem - kubectl get secrets/tiller-secret -n gitlab-managed-apps -o "jsonpath={.data['ca\.crt']}" | base64 -d > b.pem - diff a.pem b.pem - ``` - -### Error installing managed apps on EKS cluster - -If you're using a managed cluster on AWS EKS, and you are not able to install some of the managed -apps, consider checking the logs. - -You can check the logs by running the following commands: - -```shell -kubectl get pods --all-namespaces -kubectl get services --all-namespaces -``` - -If you are getting the `Failed to assign an IP address to container` error, it's probably due to the -instance type you've specified in the AWS configuration. -The number and size of nodes might not have enough IP addresses to run or install those pods. - -For reference, all the AWS instance IP limits are found -[in this AWS repository on GitHub](https://github.com/aws/amazon-vpc-cni-k8s/blob/master/pkg/awsutils/vpc_ip_resource_limit.go) (search for `InstanceENIsAvailable`). - -### Unable to install Prometheus - -Installing Prometheus is failing with the following error: - -```shell -# kubectl -n gitlab-managed-apps logs install-prometheus -... -Error: Could not get apiVersions from Kubernetes: unable to retrieve the complete list of server APIs: admission.certmanager.k8s.io/v1beta1: the server is currently unable to handle the request -``` - -This is a bug that was introduced in Helm `2.15` and fixed in `3.0.2`. As a workaround, -ensure [`cert-manager`](#cert-manager) is installed successfully prior to installing Prometheus. - -### Unable to create a Persistent Volume Claim with DigitalOcean - -Trying to create additional block storage volumes might lead to the following error when using DigitalOcean: +## Browse applications logs -```plaintext -Server requested -[Warning] pod has unbound immediate PersistentVolumeClaims (repeated 2 times) -[Normal] pod didn't trigger scale-up (it wouldn't fit if a new node is added): -Spawn failed: Timeout -``` +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36769) in GitLab 13.2. -This is due to DigitalOcean imposing a few limits with regards to creating additional block storage volumes. -[Learn more about DigitalOcean Block Storage Volumes limits.](https://www.digitalocean.com/docs/volumes/#limits) +Logs produced by pods running **GitLab Managed Apps** can be browsed using +[**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). ## Take ownership of your GitLab Managed Apps > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327803) in GitLab 13.12. -With the removal of the [One-click install method](#install-with-one-click-deprecated) in GitLab 14.0, -the **Applications** tab (under your project's **Operations > Kubernetes**) -will no longer be displayed: +With the removal of the One-click install method in GitLab 14.0, +the **Applications** tab (under your project's **Infrastructure > Kubernetes clusters**) +is no longer displayed: ![GitLab Managed Apps - Applications tab](img/applications_tab_v13_12.png) @@ -1781,10 +1126,10 @@ If you choose to keep using Helm v2 (B), follow the steps below to manage your a ### Cluster integrations -Some applications were not only installed in your cluster by GitLab through Managed Apps but were also -directly integrated with GitLab so that you could benefit from seeing, controlling, or getting notified -about them through GitLab. -To keep them integrated, read the documentation for: +Some applications were not only installed in your cluster by GitLab through +Managed Apps but were also directly integrated with GitLab. If you had one of +these applications installed before GitLab 14.0, then a corresponding [cluster +integration](integrations.md) has been automatically enabled: - [Prometheus cluster integration](integrations.md#prometheus-cluster-integration) - [Elastic Stack cluster integration](integrations.md#elastic-stack-cluster-integration) diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index d1df5642514..26611c26e5e 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -33,9 +33,9 @@ permissions in a project or group. 1. Connect GitLab with Prometheus, depending on your configuration: - *If Prometheus is already configured,* navigate to **Settings > Integrations > Prometheus** to provide the API endpoint of your Prometheus server. - - *For GitLab-managed Prometheus,* navigate to your cluster's **Details** page, - select the **Applications** tab, and install Prometheus. The integration is - auto-configured for you. + - *To use the Prometheus cluster integration,* navigate to your cluster's **Details** page, + select the **Integrations** tab, and follow the instructions to enable the Prometheus + cluster integration. 1. Set up the Prometheus integration on the cloned example project. 1. Add the Kubecost `cost-model` to your cluster: - *For non-managed clusters*, deploy it with GitLab CI/CD. @@ -46,7 +46,7 @@ permissions in a project or group. kubectl apply -f kubernetes/ --namespace cost-model ``` -To access the cost insights, navigate to **Operations > Metrics** and select +To access the cost insights, navigate to **Monitor > Metrics** and select the `default_costs.yml` dashboard. You can [customize](#customize-the-cost-dashboard) this dashboard. diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index bdf9d582b93..8906d1224b1 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Crossplane configuration **(FREE)** -After [installing](applications.md#crossplane) Crossplane, you must configure it for use. +After [installing](applications.md#install-crossplane-using-gitlab-cicd) Crossplane, you must configure it for use. The process of configuring Crossplane includes: 1. [Configure RBAC permissions](#configure-rbac-permissions). diff --git a/doc/user/clusters/img/fluentd_v13_0.png b/doc/user/clusters/img/fluentd_v13_0.png deleted file mode 100644 index edc73285238..00000000000 Binary files a/doc/user/clusters/img/fluentd_v13_0.png and /dev/null differ diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md index a8b181f8726..6c87efaf5a3 100644 --- a/doc/user/clusters/integrations.md +++ b/doc/user/clusters/integrations.md @@ -14,6 +14,17 @@ To enable cluster integrations, first add a Kubernetes cluster to a GitLab [group](../group/clusters/index.md#group-level-kubernetes-clusters) or [instance](../instance/clusters/index.md). +You can install your applications manually as shown in the following sections, or use the +[Cluster management project template](management_project_template.md) that automates the +installation. + +Although, the [Cluster management project template](management_project_template.md) still +requires that you manually do the last steps of these sections, +[Enable Prometheus integration for your cluster](#enable-prometheus-integration-for-your-cluster) +or [Enable Elastic Stack integration for your cluster](#enable-elastic-stack-integration-for-your-cluster) +depending on which application you are installing. We plan to also automate this step in the future, +see the [opened issue](https://gitlab.com/gitlab-org/gitlab/-/issues/326565). + ## Prometheus cluster integration > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55244) in GitLab 13.11. @@ -43,10 +54,8 @@ it up using [Helm](https://helm.sh/) as follows: kubectl create ns gitlab-managed-apps # Download Helm chart values that is compatible with the requirements above. -# You should substitute the tag that corresponds to the GitLab version in the URL -# - https://gitlab.com/gitlab-org/gitlab/-/raw//vendor/prometheus/values.yaml -# -wget https://gitlab.com/gitlab-org/gitlab/-/raw/v13.9.0-ee/vendor/prometheus/values.yaml +# These are included in the Cluster Management project template. +wget https://gitlab.com/gitlab-org/project-templates/cluster-management/-/raw/master/applications/prometheus/values.yaml # Add the Prometheus community Helm chart repository helm repo add prometheus-community https://prometheus-community.github.io/helm-charts @@ -64,7 +73,7 @@ To enable the Prometheus integration for your cluster: 1. Go to the cluster's page: - For a [project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes**. + **Infrastructure > Kubernetes clusters**. - For a [group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** page. - For an [instance-level cluster](../instance/clusters/index.md), navigate to your instance's @@ -103,10 +112,8 @@ running: kubectl create namespace gitlab-managed-apps # Download Helm chart values that is compatible with the requirements above. -# You should substitute the tag that corresponds to the GitLab version in the URL -# - https://gitlab.com/gitlab-org/gitlab/-/raw//vendor/elastic_stack/values.yaml -# -wget https://gitlab.com/gitlab-org/gitlab/-/raw/v13.9.0-ee/vendor/elastic_stack/values.yaml +# These are included in the Cluster Management project template. +wget https://gitlab.com/gitlab-org/project-templates/cluster-management/-/raw/master/applications/elastic-stack/values.yaml # Add the GitLab Helm chart repository helm repo add gitlab https://charts.gitlab.io @@ -121,7 +128,7 @@ To enable the Elastic Stack integration for your cluster: 1. Go to the cluster's page: - For a [project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes**. + **Infrastructure > Kubernetes clusters**. - For a [group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** page. - For an [instance-level cluster](../instance/clusters/index.md), navigate to your instance's diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index e728577e194..f741ab2d95a 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -6,10 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Cluster management project **(FREE)** -WARNING: -This is an _alpha_ feature, and it is subject to change at any time without -prior notice. - > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32810) in GitLab 12.5 A project can be designated as the management project for a cluster. @@ -20,7 +16,7 @@ privileges. This can be useful for: -- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (beta)](applications.md#install-using-gitlab-cicd-deprecated) for details. +- Creating pipelines to install cluster-wide applications into your cluster, see [management project template](management_project_template.md) for details. - Any jobs that require `cluster-admin` privileges. ## Permissions @@ -50,7 +46,7 @@ To select a cluster management project to use: 1. Navigate to the appropriate configuration page. For a: - [Project-level cluster](../project/clusters/index.md), navigate to your project's - **Operations > Kubernetes** page. + **Infrastructure > Kubernetes clusters** page. - [Group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** page. - [Instance-level cluster](../instance/clusters/index.md), navigate to Admin Area's **Kubernetes** diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md new file mode 100644 index 00000000000..52390cb18b0 --- /dev/null +++ b/doc/user/clusters/management_project_template.md @@ -0,0 +1,86 @@ +--- +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 +--- + +# Cluster Management Project Template **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0 with Helmfile support via Helm v3 instead, and a much more flexible usage of Helmfile. This introduces breaking changes that are detailed below. + +This [GitLab built-in project template](../project/working_with_projects.md#built-in-templates) +provides a quicker start for users interested in managing cluster +applications via [Helm v3](https://helm.sh/) charts. More specifically, taking advantage of the +[Helmfile](https://github.com/roboll/helmfile) utility client. The template consists of some pre-configured apps that +should help you get started quickly using various GitLab features. Still, you have all the flexibility to remove the ones you do not +need, or even add new ones that are not built-in. + +## How to use this template + +1. Create a new project, choosing "GitLab Cluster Management" from the list of [built-in project templates](../project/working_with_projects.md#built-in-templates). +1. Make this project a [cluster management project](management_project.md). +1. If you used the [GitLab Managed Apps](applications.md), refer to + [Migrating from GitLab Manged Apps](migrating_from_gma_to_project_template.md). + +### Components + +In the repository of the newly-created project, you will find: + +- A predefined [`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/.gitlab-ci.yml) + file, with a CI pipeline already configured. +- A main [`helmfile.yaml`](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/blob/master/helmfile.yaml) to toggle which applications you would like to manage. +- An `applications` directory with a `helmfile.yaml` configured for each application GitLab provides. + +#### The `.gitlab-ci.yml` file + +The base image used in your pipeline is built by the [cluster-applications](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications) +project. This image consists of a set of Bash utility scripts to support [Helm v3 releases](https://helm.sh/docs/intro/using_helm/#three-big-concepts): + +- `gl-fail-if-helm2-releases-exist {namespace}`: It tries to detect whether you have apps deployed through Helm v2 + releases for a given namespace. If so, it will fail the pipeline and ask you to manually + [migrate your Helm v2 releases to Helm v3](https://helm.sh/docs/topics/v2_v3_migration/). +- `gl-ensure-namespace {namespace}`: It creates the given namespace if it does not exist and adds the necessary label + for the [Cilium](https://github.com/cilium/cilium/) app network policies to work. +- `gl-adopt-resource-with-helm-v3 {arguments}`: Used only internally in the [cert-manager's](https://cert-manager.io/) Helmfile to + facilitate the GitLab Managed Apps adoption. +- `gl-adopt-crds-with-helm-v3 {arguments}`: Used only internally in the [cert-manager's](https://cert-manager.io/) Helmfile to + facilitate the GitLab Managed Apps adoption. +- `gl-helmfile {arguments}`: A thin wrapper that triggers the [Helmfile](https://github.com/roboll/helmfile) command. + +#### The main `helmfile.yml` file + +This file has a list of paths to other Helmfiles for each app. They're all commented out by default, so you must uncomment +the paths for the apps that you would like to manage. + +By default, each `helmfile.yaml` in these sub-paths will have the attribute `installed: true`, which signifies that everytime +the pipeline runs, Helmfile will try to either install or update your apps according to the current state of your +cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile will try to uninstall this app +from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works. + +Furthermore, each app has an `applications/{app}/values.yaml` file. This is the +place where you can define some default values for your app's Helm chart. Some apps will already have defaults +pre-defined by GitLab. + +#### Built-in applications + +The built-in applications are intended to provide an easy way to get started with various Kubernetes oriented GitLab features. + +The [built-in supported applications](https://gitlab.com/gitlab-org/project-templates/cluster-management/-/tree/master/applications) are: + +- Apparmor +- Cert-manager +- Cilium +- Elastic Stack +- Falco +- Fluentd +- GitLab Runner +- Ingress +- Prometheus +- Sentry +- Vault + +### Migrating from GitLab Managed Apps + +If you had GitLab Managed Apps, either One-Click or CI/CD install, read the docs on how to +[migrate from GitLab Managed Apps to project template](migrating_from_gma_to_project_template.md) diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md new file mode 100644 index 00000000000..7fa6ccea433 --- /dev/null +++ b/doc/user/clusters/migrating_from_gma_to_project_template.md @@ -0,0 +1,95 @@ +--- +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 +--- + +# Migrating from GitLab Managed Apps to a management project template + +The [GitLab Managed Apps](applications.md) are deprecated in GitLab 14.0. To migrate to the new way of managing them: + +1. Read how the [management project template](management_project_template.md) works, and + create a new project based on the "GitLab Cluster Management" template. +1. Create a new project as explained in the [management project template](management_project_template.md). +1. Detect apps deployed through Helm v2 releases by using the pre-configured [`.gitlab-ci.yml`](management_project_template.md#the-gitlab-ciyml-file) file: + - In case you had overwritten the default GitLab Managed Apps namespace, edit `.gitlab-ci.yml`, + and make sure the script is receiving the correct namespace as an argument: + + ```yaml + script: + - gl-fail-if-helm2-releases-exist + ``` + + - If you kept the default name (`gitlab-managed-apps`), then the script is already + set up. + + Either way, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and read the logs of the + `detect-helm2-releases` job to know if you have any Helm v2 releases and which are they. + +1. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm docs on + [how to migrate from Helm v2 to Helm v3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/), + and clean up the Helm v2 releases after you are confident that they have been successfully migrated. + +1. In this step you should already have only Helm v3 releases. + Uncomment from the main [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file) the paths for the + applications that you would like to manage with this project. Although you could uncomment all the ones you want to + managed at once, we recommend you repeat the following steps separately for each app, so you do not get lost during + the process. +1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version currently deployed + for your app. Take a GitLab Runner Helm v3 release as an example: + + The following command lists the releases and their versions: + + ```shell + helm ls -n gitlab-managed-apps + + NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION + runner gitlab-managed-apps 1 2021-06-09 19:36:55.739141644 +0000 UTC deployed gitlab-runner-0.28.0 13.11.0 + ``` + + Take the version from the `CHART` column which is in the format `{release}-v{chart_version}`, + then edit the `version:` attribute in the `./applications/gitlab-runner/helmfile.yaml`, so that it matches the version + you have currently deployed. This is a safe step to avoid upgrading versions during this migration. + Make sure you replace `gitlab-managed-apps` from the above command if you have your apps deployed to a different + namespace. + +1. Edit the `applications/{app}/values.yaml` associated with your app to match the currently + deployed values. For example, for GitLab Runner: + + 1. Copy the output of the following command (it might be big): + + ```shell + helm get values runner -n gitlab-managed-apps -a --output yaml + ``` + + 1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command. + + This safe step will guarantee that no unexpected default values overwrite your currently deployed values. + For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake. + +1. Some apps require special attention: + + - Ingress: Due to an existing [chart issue](https://github.com/helm/charts/pull/13646), you might see + `spec.clusterIP: Invalid value` when trying to run the [`./gl-helmfile`](management_project_template.md#the-gitlab-ciyml-file) + command. To work around this, after overwriting the release values in `applications/ingress/values.yaml`, + you might need to overwrite all the occurrences of `omitClusterIP: false`, setting it to `omitClusterIP: true`. + Another approach,could be to collect these IPs by running `kubectl get services -n gitlab-managed-apps` + and then overwriting each `ClusterIP` that it complains about with the value you got from that command. + + - Vault: This application introduces a breaking change from the chart we used in Helm v2 to the chart + used in Helm v3. So, the only way to integrate it with this Cluster Management Project is to actually uninstall this app and accept the + chart version proposed in `applications/vault/values.yaml`. + +1. After following all the previous steps, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) + and watch the `apply` job logs to see if any of your applications were successfully detected, installed, and whether they got any + unexpected updates. + + Some annotation checksums are expected to be updated, as well as this attribute: + + ```diff + --- heritage: Tiller + +++ heritage: Tiller + ``` + +After getting a successful pipeline, repeat these steps for any other deployed apps +you want to manage with the Cluster Management Project. diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 43dbafb8f6f..f757a548aee 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -91,11 +91,11 @@ To run a License Compliance scanning job, you need GitLab Runner with the For GitLab 12.8 and later, to enable License Compliance, you must [include](../../../ci/yaml/README.md#includetemplate) the -[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) +[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml) that's provided as a part of your GitLab installation. For older versions of GitLab from 11.9 to 12.7, you must [include](../../../ci/yaml/README.md#includetemplate) the -[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml). +[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/d2cc841c55d65bc8134bfb3a467e66c36ac32b0a/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml). For GitLab versions earlier than 11.9, you can copy and use the job as defined that template. @@ -121,7 +121,7 @@ always take the latest License Compliance artifact available. Behind the scenes, [GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/license-finder) is used to detect the languages/frameworks and in turn analyzes the licenses. -The License Compliance settings can be changed through [CI/CD variables](#available-variables) by using the +The License Compliance settings can be changed through [CI/CD variables](#available-cicd-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. ### When License Compliance runs @@ -129,7 +129,7 @@ The License Compliance settings can be changed through [CI/CD variables](#availa When using the GitLab `License-Scanning.gitlab-ci.yml` template, the License Compliance job doesn't wait for other stages to complete. -### Available variables +### Available CI/CD variables License Compliance can be configured using CI/CD variables. @@ -153,7 +153,7 @@ License Compliance can be configured using CI/CD variables. > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. -The `license_management` image already embeds many auto-detection scripts, languages, +The `license_finder` image already embeds many auto-detection scripts, languages, and packages. Nevertheless, it's almost impossible to cover all cases for all projects. That's why sometimes it's necessary to install extra packages, or to have extra steps in the project automated setup, like the download and installation of a certificate. @@ -265,11 +265,11 @@ license_scanning: ### Custom root certificates for Python You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). #### Using private Python repositories -If you have a private Python repository you can use the `PIP_INDEX_URL` [CI/CD variable](#available-variables) +If you have a private Python repository you can use the `PIP_INDEX_URL` [CI/CD variable](#available-cicd-variables) to specify its location. ### Configuring npm projects @@ -292,7 +292,7 @@ registry = https://npm.example.com #### Custom root certificates for npm You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). To disable TLS verification you can provide the [`strict-ssl`](https://docs.npmjs.com/using-npm/config/#strict-ssl) setting. @@ -323,7 +323,7 @@ npmRegistryServer: "https://npm.example.com" #### Custom root certificates for Yarn You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). ### Configuring Bower projects @@ -347,7 +347,7 @@ For example: #### Custom root certificates for Bower You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a `ca` setting in a [`.bowerrc`](https://bower.io/docs/config/#bowerrc-specification) file. @@ -368,7 +368,7 @@ source "https://gems.example.com" #### Custom root certificates for Bundler You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a [`BUNDLE_SSL_CA_CERT`](https://bundler.io/v2.0/man/bundle-config.1.html) [variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. @@ -392,7 +392,7 @@ my-registry = { index = "https://my-intranet:8080/git/index" } To supply a custom root certificate to complete TLS verification, do one of the following: -- Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +- Use the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). - Specify a [`CARGO_HTTP_CAINFO`](https://doc.rust-lang.org/cargo/reference/environment-variables.html) [variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. @@ -425,7 +425,7 @@ For example: #### Custom root certificates for Composer You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), or by +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), or by specifying a [`COMPOSER_CAFILE`](https://getcomposer.org/doc/03-cli.md#composer-cafile) [variable](../../../ci/variables/README.md#custom-cicd-variables) in the job definition. @@ -499,7 +499,7 @@ You can provide custom certificates by adding a `.conan/cacert.pem` file to the setting [`CA_CERT_PATH`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-cacert-path) to `.conan/cacert.pem`. -If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables), this +If you specify the `ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables), this variable's X.509 certificates are installed in the Docker image's default trust store and Conan is configured to use this as the default `CA_CERT_PATH`. @@ -507,7 +507,7 @@ configured to use this as the default `CA_CERT_PATH`. To configure [Go modules](https://github.com/golang/go/wiki/Modules) based projects, specify [CI/CD variables](https://golang.org/pkg/cmd/go/#hdr-Environment_variables) -in the `license_scanning` job's [variables](#available-variables) section in `.gitlab-ci.yml`. +in the `license_scanning` job's [variables](#available-cicd-variables) section in `.gitlab-ci.yml`. If a project has [vendored](https://golang.org/pkg/cmd/go/#hdr-Vendor_Directories) its modules, then the combination of the `vendor` directory and `mod.sum` file are used to detect the software @@ -556,10 +556,13 @@ For example: #### Custom root certificates for NuGet You can supply a custom root certificate to complete TLS verification by using the -`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-variables). +`ADDITIONAL_CA_CERT_BUNDLE` [CI/CD variable](#available-cicd-variables). ### Migration from `license_management` to `license_scanning` +WARNING: +The `license_management` job was deprecated in GitLab 12.8. The `License-Management.gitlab-ci.yml` template was removed from GitLab 14.0. + In GitLab 12.8 a new name for `license_management` job was introduced. This change was made to improve clarity around the purpose of the scan, which is to scan and collect the types of licenses present in a projects dependencies. GitLab 13.0 drops support for `license_management`. If you're using a custom setup for License Compliance, you're required @@ -730,8 +733,9 @@ Developers of the project can view the policies configured in a project. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13067) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. -`License-Check` is a [security approval](../../application_security/index.md#enabling-security-approvals-within-a-project) rule you can enable to allow an individual or group to approve a -merge request that contains a `denied` license. +`License-Check` is a [merge request approval](../../project/merge_requests/approvals/index.md) rule +you can enable to allow an individual or group to approve a merge request that contains a `denied` +license. You can enable `License-Check` one of two ways: @@ -816,7 +820,7 @@ license_scanning: ASDF_RUBY_VERSION: '2.7.2' ``` -A full list of variables can be found in [CI/CD variables](#available-variables). +A full list of variables can be found in [CI/CD variables](#available-cicd-variables). To find out what tools are pre-installed in the `license_scanning` Docker image use the following command: diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 50007545a65..cf57afb8324 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -7,7 +7,8 @@ type: reference, howto # Threads **(FREE)** -GitLab encourages communication through comments, threads, and suggestions. +GitLab encourages communication through comments, threads, and +[code suggestions](../project/merge_requests/reviews/suggestions.md). For example, you can create a comment in the following places: @@ -22,8 +23,10 @@ There are standard comments, and you also have the option to create a comment in the form of a thread. A comment can also be [turned into a thread](#start-a-thread-by-replying-to-a-standard-comment) when it receives a reply. -The comment area supports [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md). You can edit your own -comment at any time, and anyone with [Maintainer access level](../permissions.md) or +The comment area supports [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md). +You can [suggest code changes](../project/merge_requests/reviews/suggestions.md) in your comment, +which the user can accept through the user interface. You can edit your own +comment at any time, and anyone with the [Maintainer role](../permissions.md) or higher can also edit a comment made by someone else. You can also reply to a comment notification email to reply to the comment if diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index cdb4ca52c9c..223d3363186 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -153,289 +153,19 @@ content directly from common public CDN hostnames. ## Webhooks -A limit of: +The following limits apply for [Webhooks](../project/integrations/webhooks.md): -- 100 webhooks applies to projects. -- 50 webhooks applies to groups. **(BRONZE ONLY)** -- Payload is limited to 25MB +| Setting | GitLab.com | Default | +| ------- | ---------- | ------- | +| [Webhook rate limit](../../administration/instance_limits.md#webhook-rate-limit) | `120` calls per minute for Free tier, unlimited for all paid tiers | 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` ## Shared runners -GitLab offers Linux and Windows shared runners hosted on GitLab.com for executing your pipelines. +GitLab has shared runners on GitLab.com that you can use to run your CI jobs. -NOTE: -Shared runners provided by GitLab are **not** configurable. Consider [installing your own runner](https://docs.gitlab.com/runner/install/) if you have specific configuration needs. - -### Linux shared runners - -Linux shared runners on GitLab.com run in autoscale mode and are powered by Google Cloud Platform. - -Autoscaling means reduced queue times to spin up CI/CD jobs, and isolated VMs for each project, thus maximizing security. These shared runners are available for users and customers on GitLab.com. - -GitLab offers Ultimate tier capabilities and included CI/CD minutes per group per month for our [Open Source](https://about.gitlab.com/solutions/open-source/join/), [Education](https://about.gitlab.com/solutions/education/), and [Startups](https://about.gitlab.com/solutions/startups/) programs. For private projects, GitLab offers various [plans](https://about.gitlab.com/pricing/), starting with a Free tier. - -All your CI/CD jobs run on [n1-standard-1 instances](https://cloud.google.com/compute/docs/machine-types) with 3.75GB of RAM, CoreOS and the latest Docker Engine -installed. Instances provide 1 vCPU and 25GB of HDD disk space. The default -region of the VMs is US East1. -Each instance is used only for one job, this ensures any sensitive data left on the system can't be accessed by other people their CI jobs. - -The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated for GitLab projects as well as community forks of them. They use a slightly larger machine type (n1-standard-2) and have a bigger SSD disk size. They don't run untagged jobs and unlike the general fleet of shared runners, the instances are re-used up to 40 times. - -Jobs handled by the shared runners on GitLab.com (`shared-runners-manager-X.gitlab.com`), -**time out after 3 hours**, regardless of the timeout configured in a -project. Check the issues [4010](https://gitlab.com/gitlab-com/infrastructure/-/issues/4010) and [4070](https://gitlab.com/gitlab-com/infrastructure/-/issues/4070) for the reference. - -Below are the shared runners settings. - -| Setting | GitLab.com | Default | -| ----------- | ----------------- | ---------- | -| [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) | [Runner versions dashboard](https://dashboards.gitlab.com/d/000000159/ci?from=now-1h&to=now&refresh=5m&orgId=1&panelId=12&fullscreen&theme=light) | - | -| Executor | `docker+machine` | - | -| Default Docker image | `ruby:2.5` | - | -| `privileged` (run [Docker in Docker](https://hub.docker.com/_/docker/)) | `true` | `false` | - -#### Pre-clone script - -Linux shared runners on GitLab.com provide a way to run commands in a CI -job before the runner attempts to run `git init` and `git fetch` to -download a GitLab repository. The -[`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) -can be used for: - -- Seeding the build directory with repository data -- Sending a request to a server -- Downloading assets from a CDN -- Any other commands that must run before the `git init` - -To use this feature, define a [CI/CD variable](../../ci/variables/README.md#custom-cicd-variables) called -`CI_PRE_CLONE_SCRIPT` that contains a bash script. - -[This example](../../development/pipelines.md#pre-clone-step) -demonstrates how you might use a pre-clone step to seed the build -directory. - -#### `config.toml` - -The full contents of our `config.toml` are: - -NOTE: -Settings that are not public are shown as `X`. - -**Google Cloud Platform** - -```toml -concurrent = X -check_interval = 1 -metrics_server = "X" -sentry_dsn = "X" - -[[runners]] - name = "docker-auto-scale" - request_concurrency = X - url = "https://gitlab.com/" - token = "SHARED_RUNNER_TOKEN" - pre_clone_script = "eval \"$CI_PRE_CLONE_SCRIPT\"" - executor = "docker+machine" - environment = [ - "DOCKER_DRIVER=overlay2", - "DOCKER_TLS_CERTDIR=" - ] - limit = X - [runners.docker] - image = "ruby:2.5" - privileged = true - volumes = [ - "/certs/client", - "/dummy-sys-class-dmi-id:/sys/class/dmi/id:ro" # Make kaniko builds work on GCP. - ] - [runners.machine] - IdleCount = 50 - IdleTime = 3600 - MaxBuilds = 1 # For security reasons we delete the VM after job has finished so it's not reused. - MachineName = "srm-%s" - MachineDriver = "google" - MachineOptions = [ - "google-project=PROJECT", - "google-disk-size=25", - "google-machine-type=n1-standard-1", - "google-username=core", - "google-tags=gitlab-com,srm", - "google-use-internal-ip", - "google-zone=us-east1-d", - "engine-opt=mtu=1460", # Set MTU for container interface, for more information check https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3214#note_82892928 - "google-machine-image=PROJECT/global/images/IMAGE", - "engine-opt=ipv6", # This will create IPv6 interfaces in the containers. - "engine-opt=fixed-cidr-v6=fc00::/7", - "google-operation-backoff-initial-interval=2" # Custom flag from forked docker-machine, for more information check https://github.com/docker/machine/pull/4600 - ] - [[runners.machine.autoscaling]] - Periods = ["* * * * * sat,sun *"] - Timezone = "UTC" - IdleCount = 70 - IdleTime = 3600 - [[runners.machine.autoscaling]] - Periods = ["* 30-59 3 * * * *", "* 0-30 4 * * * *"] - Timezone = "UTC" - IdleCount = 700 - IdleTime = 3600 - [runners.cache] - Type = "gcs" - Shared = true - [runners.cache.gcs] - CredentialsFile = "/path/to/file" - BucketName = "bucket-name" -``` - -### Windows shared runners (beta) - -The Windows shared runners are in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) -and shouldn't be used for production workloads. - -During this beta period, the [shared runner pipeline quota](../admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota) -applies for groups and projects in the same manner as Linux runners. This may -change when the beta period ends, as discussed in this [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/30834). - -Windows shared runners on GitLab.com autoscale by launching virtual machines on -the Google Cloud Platform. This solution uses an -[autoscaling driver](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/tree/master/docs/readme.md) -developed by GitLab for the [custom executor](https://docs.gitlab.com/runner/executors/custom.html). -Windows shared runners execute your CI/CD jobs on `n1-standard-2` instances with -2 vCPUs and 7.5 GB RAM. You can find a full list of available Windows packages in -the [package documentation](https://gitlab.com/gitlab-org/ci-cd/shared-runners/images/gcp/windows-containers/blob/master/cookbooks/preinstalled-software/README.md). - -We want to keep iterating to get Windows shared runners in a stable state and -[generally available](https://about.gitlab.com/handbook/product/gitlab-the-product/#generally-available-ga). -You can follow our work towards this goal in the -[related epic](https://gitlab.com/groups/gitlab-org/-/epics/2162). - -#### Configuration - -The full contents of our `config.toml` are: - -NOTE: -Settings that aren't public are shown as `X`. - -```toml -concurrent = X -check_interval = 3 - -[[runners]] - name = "windows-runner" - url = "https://gitlab.com/" - token = "TOKEN" - executor = "custom" - builds_dir = "C:\\GitLab-Runner\\builds" - cache_dir = "C:\\GitLab-Runner\\cache" - shell = "powershell" - [runners.custom] - config_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe" - config_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "config"] - prepare_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe" - prepare_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "prepare"] - run_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe" - run_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "run"] - cleanup_exec = "C:\\GitLab-Runner\\autoscaler\\autoscaler.exe" - cleanup_args = ["--config", "C:\\GitLab-Runner\\autoscaler\\config.toml", "custom", "cleanup"] -``` - -The full contents of our `autoscaler/config.toml` are: - -```toml -Provider = "gcp" -Executor = "winrm" -OS = "windows" -LogLevel = "info" -LogFormat = "text" -LogFile = "C:\\GitLab-Runner\\autoscaler\\autoscaler.log" -VMTag = "windows" - -[GCP] - ServiceAccountFile = "PATH" - Project = "some-project-df9323" - Zone = "us-east1-c" - MachineType = "n1-standard-2" - Image = "IMAGE" - DiskSize = 50 - DiskType = "pd-standard" - Subnetwork = "default" - Network = "default" - Tags = ["TAGS"] - Username = "gitlab_runner" - -[WinRM] - MaximumTimeout = 3600 - ExecutionMaxRetries = 0 - -[ProviderCache] - Enabled = true - Directory = "C:\\GitLab-Runner\\autoscaler\\machines" -``` - -#### Example - -Below is a simple `.gitlab-ci.yml` file to show how to start using the -Windows shared runners: - -```yaml -.shared_windows_runners: - tags: - - shared-windows - - windows - - windows-1809 - -stages: - - build - - test - -before_script: - - Set-Variable -Name "time" -Value (date -Format "%H:%m") - - echo ${time} - - echo "started by ${GITLAB_USER_NAME}" - -build: - extends: - - .shared_windows_runners - stage: build - script: - - echo "running scripts in the build job" - -test: - extends: - - .shared_windows_runners - stage: test - script: - - echo "running scripts in the test job" -``` - -#### Limitations and known issues - -- All the limitations mentioned in our [beta - definition](https://about.gitlab.com/handbook/product/#beta). -- The average provisioning time for a new Windows VM is 5 minutes. - This means that you may notice slower build start times - on the Windows shared runner fleet during the beta. In a future - release we intend to update the autoscaler to enable - the pre-provisioning of virtual machines. This is intended to significantly reduce - the time it takes to provision a VM on the Windows fleet. You can - follow along in the [related issue](https://gitlab.com/gitlab-org/ci-cd/custom-executor-drivers/autoscaler/-/issues/32). -- The Windows shared runner fleet may be unavailable occasionally - for maintenance or updates. -- The Windows shared runner virtual machine instances do not use the - GitLab Docker executor. This means that you can't specify - [`image`](../../ci/yaml/README.md#image) or [`services`](../../ci/yaml/README.md#services) in - your pipeline configuration. -- For the beta release, we have included a set of software packages in - the base VM image. If your CI job requires additional software that's - not included in this list, then you must add installation - commands to [`before_script`](../../ci/yaml/README.md#before_script) or [`script`](../../ci/yaml/README.md#script) to install the required - software. Note that each job runs on a new VM instance, so the - installation of additional software packages needs to be repeated for - each job in your pipeline. -- The job may stay in a pending state for longer than the - Linux shared runners. -- There is the possibility that we introduce breaking changes which will - require updates to pipelines that are using the Windows shared runner - fleet. +For more information, see [choosing a runner](../../ci/runners/README.md). ## Sidekiq @@ -502,26 +232,12 @@ for `shared_buffers` is quite high and as such we are looking into adjusting it. More information on this particular change can be found at . An up to date list of proposed changes can be found at -. +. ## Puma GitLab.com uses the default of 60 seconds for [Puma request timeouts](https://docs.gitlab.com/omnibus/settings/puma.html#worker-timeout). -## Unicorn - -GitLab.com adjusts the memory limits for the [unicorn-worker-killer](https://rubygems.org/gems/unicorn-worker-killer) gem. - -Base default: - -- `memory_limit_min` = 750MiB -- `memory_limit_max` = 1024MiB - -Web front-ends: - -- `memory_limit_min` = 1024MiB -- `memory_limit_max` = 1280MiB - ## GitLab.com-specific rate limits NOTE: diff --git a/doc/user/group/bulk_editing/index.md b/doc/user/group/bulk_editing/index.md index 48644b7427d..feceafd0991 100644 --- a/doc/user/group/bulk_editing/index.md +++ b/doc/user/group/bulk_editing/index.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../user/group/index.md' +remove_date: '2021-08-13' --- This document was moved to [another location](../../../user/group/index.md). diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 87b259df9d8..4de464822f7 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -17,12 +17,11 @@ your group, enabling you to use the same cluster across multiple projects. To view your group level Kubernetes clusters, navigate to your project and select **Kubernetes** from the left-hand menu. -## Installing applications +## Cluster management project -GitLab can install and manage some applications in your group-level -cluster. For more information on installing, upgrading, uninstalling, -and troubleshooting applications for your group cluster, see -[GitLab Managed Apps](../../clusters/applications.md). +Attach a [cluster management project](../../clusters/management_project.md) +to your cluster to manage shared resources requiring `cluster-admin` privileges for +installation, such as an Ingress controller. ## RBAC compatibility @@ -72,9 +71,6 @@ for deployments with a cluster not managed by GitLab, you must ensure: (this is [not automatic](https://gitlab.com/gitlab-org/gitlab/-/issues/31519)). Editing `KUBE_NAMESPACE` directly is discouraged. -If you [install applications](#installing-applications) on your cluster, GitLab creates -the resources required to run them, even if you choose to manage your own cluster. - ### Clearing the cluster cache > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31759) in GitLab 12.6. @@ -100,7 +96,7 @@ per [multiple Kubernetes clusters](#multiple-kubernetes-clusters) When specifyin this is automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during the [Auto DevOps](../../../topics/autodevops/index.md) stages. -The domain should have a wildcard DNS configured to the Ingress IP address. +The domain should have a wildcard DNS configured to the Ingress IP address. [More details](../../project/clusters/index.md#base-domain). ## Environment scopes **(PREMIUM)** diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index 016bda329b2..d544003536e 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -9,26 +9,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.6. -Custom project templates are useful for organizations that need to create many similar types of [projects](../project/index.md) and want to start from the same jumping-off point. +Custom project templates are useful for organizations that need to create many similar types of +[projects](../project/index.md). +Projects created from these templates serve as a common starting point. ## Setting up group-level project templates -To use a custom project template for a new project you need to: +To use a custom project template for a new project: -1. [Create a 'templates' subgroup](subgroups/index.md). -1. [Add repositories (projects) to the that new subgroup](index.md#add-projects-to-a-group), as your templates. -1. Edit your group's settings to look to your 'templates' subgroup for templates: - 1. In the left-hand menu, click **{settings}** **Settings > General**. +1. [Create a `templates` subgroup](subgroups/index.md). +1. [Add repositories (projects) to that new subgroup](index.md#add-projects-to-a-group), + as your templates. +1. Edit your group's settings to look to your _templates_ subgroup for templates: - NOTE: - If you don't have access to the group's settings, you may not have sufficient privileges (for example, you may need developer or higher permissions). - - 1. Scroll to **Custom project templates** and click **Expand**. If no **Custom project templates** section displays, make sure you've created a subgroup, and added a project (repository) to it. - 1. Select the 'templates' subgroup. + 1. In the left menu, select **Settings > General**. If you don't have access to the + group's settings, you may not have sufficient privileges (for example, you may need developer + or higher permissions). + 1. Scroll to **Custom project templates** and select **Expand**. If no **Custom project templates** + section displays, make sure you've created a subgroup and added a project (repository) to it. + 1. Select the **templates** subgroup. ### Example structure -Here is a sample group/project structure for a hypothetical "Acme Co" for project templates: +Here's a sample group/project structure for project templates, for a hypothetical _Acme Co_: ```plaintext # GitLab instance and group @@ -53,24 +56,22 @@ gitlab.com/acmeco/ ### Adjust Settings -Users can configure a GitLab group that serves as template -source under a group's **Settings > General > Custom project templates**. - -NOTE: -GitLab administrators can -[set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md). - -Within this section, you can configure the group where all the custom project -templates are sourced. Every project _template_ directly under the group namespace is -available to every signed-in user, if all enabled [project features](../project/settings/index.md#sharing-and-permissions) except for GitLab Pages are set to **Everyone With Access**. - -However, private projects will be available only if the user is a member of the project. +Users can configure a GitLab group that serves as template source under a group's +**Settings > General > Custom project templates**. NOTE: -Only direct subgroups can be set as the template source. Projects of nested subgroups of a selected template source cannot be used. - -Repository and database information that are copied over to each new project are -identical to the data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). +GitLab administrators can [set project templates for an entire GitLab instance](../admin_area/custom_project_templates.md). + +Within this section, you can configure the group where all the custom project templates are sourced. +If all enabled [project features](../project/settings/index.md#sharing-and-permissions) +(except for GitLab Pages) are set to **Everyone With Access**, then every project template directly +under the group namespace is available to every signed-in user. However, private projects are +available only if the user is a member of the project. Also note that only direct subgroups can be +set as the template source. Projects of nested subgroups of a selected template source cannot be +used. + +Repository and database information that are copied over to each new project are identical to the +data exported with the [GitLab Project Import/Export](../project/settings/import_export.md). D; ``` -Subgraphs can also be included: +You can also include subgraphs: ````markdown ```mermaid @@ -237,16 +192,17 @@ end #### PlantUML -To make PlantUML available in GitLab, a GitLab administrator needs to enable it first. Read more in [PlantUML & GitLab](../administration/integration/plantuml.md). +To make PlantUML available in GitLab, a GitLab administrator must enable it. For more information, see the +[PlantUML & GitLab](../administration/integration/plantuml.md) page. #### Kroki -To make Kroki available in GitLab, a GitLab administrator needs to enable it first. -Read more in the [Kroki integration](../administration/integration/kroki.md) page. +To make Kroki available in GitLab, a GitLab administrator must enable it. +For more information, see the [Kroki integration](../administration/integration/kroki.md) page. -### Emoji +### Emojis -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#emoji). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#emojis). ```markdown Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: @@ -270,13 +226,13 @@ If you're new to this, don't be -#### Emoji and your OS +#### Emojis and your operating system -The emoji example above uses hard-coded images for this documentation. Rendered emoji -in GitLab may appear different depending on the OS and browser used. +The previous emoji example uses hard-coded images. Rendered emojis +in GitLab may be different depending on the OS and browser used. -Most emoji are natively supported on macOS, Windows, iOS, Android, and fall back on image-based -emoji where there is no support. +Most emojis are natively supported on macOS, Windows, iOS, Android, and fall back on image-based +emojis where there is no support. @@ -291,17 +247,17 @@ this font installed by default. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23331) in GitLab 11.6. Front matter is metadata included at the beginning of a Markdown document, preceding -its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/), +the content. This data can be used by static site generators like [Jekyll](https://jekyllrb.com/docs/front-matter/), [Hugo](https://gohugo.io/content-management/front-matter/), and many other applications. -When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, +When you view a Markdown file rendered by GitLab, front matter is displayed as-is, in a box at the top of the document. The HTML content displays after the front matter. To view an example, you can toggle between the source and rendered version of a -[GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/README.md). +[GitLab documentation file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md). -In GitLab, front matter is only used in Markdown files and wiki pages, not the other +In GitLab, front matter is used only in Markdown files and wiki pages, not the other places where Markdown formatting is supported. It must be at the very top of the document -and must be between delimiters, as explained below. +and must be between delimiters. The following delimiters are supported: @@ -352,9 +308,9 @@ $example = array( ### Inline diff -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-diff). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-diff). -With inline diff tags you can display `{+ additions +}` or `[- deletions -]`. +With inline diff tags, you can display `{+ additions +}` or `[- deletions -]`. The wrapping tags can be either curly braces or square brackets: @@ -369,7 +325,7 @@ The wrapping tags can be either curly braces or square brackets: --- -However, the wrapping tags can't be mixed: +However, you cannot mix the wrapping tags: ```markdown - {+ addition +] @@ -379,7 +335,7 @@ However, the wrapping tags can't be mixed: ``` If your diff includes words in `` `code` `` font, make sure to escape each backtick `` ` `` with a -backslash `\`, otherwise the diff highlight don't render correctly: +backslash `\`. Otherwise the diff highlight does not render correctly: ```markdown - {+ Just regular text +} @@ -391,18 +347,18 @@ backslash `\`, otherwise the diff highlight don't render correctly: ### Math -If this section is not rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#math). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#math). -It's possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX). +Math written in LaTeX syntax is rendered with [KaTeX](https://github.com/KaTeX/KaTeX). -Math written between dollar signs `$` are rendered inline with the text. Math written -inside a [code block](#code-spans-and-blocks) with the language declared as `math`, are rendered +Math written between dollar signs `$` is rendered inline with the text. Math written +in a [code block](#code-spans-and-blocks) with the language declared as `math` is rendered on a separate line: ````markdown This math is inline $`a^2+b^2=c^2`$. -This is on a separate line +This is on a separate line: ```math a^2+b^2=c^2 @@ -417,71 +373,22 @@ This is on a separate line a^2+b^2=c^2 ``` -_Be advised that KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._ +_KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._ -This also works for the Asciidoctor `:stem: latexmath`. For details, see +This syntax also works for the Asciidoctor `:stem: latexmath`. For details, see the [Asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activating-stem-support). -### Special GitLab references - -GitLab Flavored Markdown recognizes special GitLab related references. For example, you can reference -an issue, a commit, a team member, or even an entire project team. GitLab Flavored Markdown turns -that reference into a link so you can navigate between them. - -Additionally, GitLab Flavored Markdown recognizes certain cross-project references and also has a shorthand -version to reference other projects from the same namespace. - -GitLab Flavored Markdown recognizes the following: - -| references | input | cross-project reference | shortcut inside same namespace | -| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | -| specific user | `@user_name` | | | -| specific group | `@group_name` | | | -| entire team | `@all` | | | -| project | `namespace/project>` | | | -| issue | ``#123`` | `namespace/project#123` | `project#123` | -| merge request | `!123` | `namespace/project!123` | `project!123` | -| snippet | `$123` | `namespace/project$123` | `project$123` | -| epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | -| vulnerability **(ULTIMATE)** (1)| `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | -| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | -| label by ID | `~123` | `namespace/project~123` | `project~123` | -| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | -| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | -| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | -| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | -| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | -| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | -| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | -| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | -| repository file references | `[README](doc/README.md)` | | | -| repository file line references | `[README](doc/README.md#L13)` | | | -| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | - -1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. - -For example, referencing an issue by using `#123` formats the output as a link -to issue number 123 with text `#123`. Likewise, a link to issue number 123 is -recognized and formatted with text `#123`. If you don't want `#123` to link to an issue, -add a leading backslash `\#123`. - -In addition to this, links to some objects are also recognized and formatted. Some examples of these are: - -- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, which are rendered as `#1234 (comment 101075757)` -- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, which are rendered as `#1234 (designs)`. -- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, which are rendered as `#1234[layout.png]`. - ### Task lists -If this section isn't rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#task-lists). +[View this topic in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#task-lists). -You can add task lists anywhere Markdown is supported, but only issues, merge requests, and -comments support clicking to toggle the boxes. In other -places, you must edit the Markdown manually to change the status by adding or -removing an `x` inside the square brackets. +You can add task lists anywhere Markdown is supported. -To create a task list, add a specially-formatted Markdown list. You can use either -unordered or ordered lists: +- In issues, merge requests, and comments, you can click to select the boxes. +- In all other places, you cannot click to select the boxes. You must edit the Markdown manually + by adding or removing an `x` in the brackets. + +To create a task list, follow the format of an ordered or unordered list: ```markdown - [x] Completed task @@ -496,13 +403,14 @@ unordered or ordered lists: 1. [x] Sub-task 2 ``` -![Task list as rendered by the GitLab interface](img/completed_tasks_v13_3.png) +![Task list as rendered by GitLab](img/completed_tasks_v13_3.png) ### Table of contents -Add a table of contents to a Markdown file, wiki page, issue request, or merge request -description by adding the tag `[[_TOC_]]` on its own line. -It displays an unordered list that links to subheadings in the document. +A table of contents is an unordered list that links to subheadings in the document. + +To add a table of contents to a Markdown file, wiki page, issue request, or merge request +description, add the `[[_TOC_]]` tag on its own line. ```markdown This is an intro sentence to my Wiki page. @@ -522,14 +430,14 @@ Second section content. ### Wiki-specific Markdown -The following examples show how links inside wikis behave. +The following topics show how links inside wikis behave. #### Wiki - direct page link -A link which just includes the slug for a page points to that page, -_at the base level of the wiki_. +A direct page link includes the slug for a page that points to that page, +at the base level of the wiki. -This snippet would link to a `documentation` page at the root of your wiki: +This example links to a `documentation` page at the root of your wiki: ```markdown [Link to Documentation](documentation) @@ -537,10 +445,10 @@ This snippet would link to a `documentation` page at the root of your wiki: #### Wiki - direct file link -Links with a file extension point to that file, _relative to the current page_. +A direct file link points to a file extension for a file, relative to the current page. -If the snippet below was placed on a page at `/documentation/related`, -it would link to `/documentation/file.md`: +If the following example is on a page at `/documentation/related`, +it links to `/documentation/file.md`: ```markdown [Link to File](file.md) @@ -548,32 +456,32 @@ it would link to `/documentation/file.md`: #### Wiki - hierarchical link -A link can be constructed relative to the current wiki page using `./`, +A hierarchical link can be constructed relative to the current wiki page by using `./`, `../`, and so on. -If this snippet was placed on a page at `/documentation/main`, -it would link to `/documentation/related`: +If this example is on a page at `/documentation/main`, +it links to `/documentation/related`: ```markdown [Link to Related Page](related) ``` -If this snippet was placed on a page at `/documentation/related/content`, -it would link to `/documentation/main`: +If this example is on a page at `/documentation/related/content`, +it links to `/documentation/main`: ```markdown [Link to Related Page](../main) ``` -If this snippet was placed on a page at `/documentation/main`, -it would link to `/documentation/related.md`: +If this example is on a page at `/documentation/main`, +it links to `/documentation/related.md`: ```markdown [Link to Related Page](related.md) ``` -If this snippet was placed on a page at `/documentation/related/content`, -it would link to `/documentation/main.md`: +If this example is on a page at `/documentation/related/content`, +it links to `/documentation/main.md`: ```markdown [Link to Related Page](../main.md) @@ -581,26 +489,75 @@ it would link to `/documentation/main.md`: #### Wiki - root link -A link starting with a `/` is relative to the wiki root. +A root link starts with a `/` and is relative to the wiki root. -This snippet links to `/documentation`: +This example links to `/documentation`: ```markdown [Link to Related Page](/documentation) ``` -This snippet links to `/miscellaneous.md`: +This example links to `/miscellaneous.md`: ```markdown [Link to Related Page](/miscellaneous.md) ``` +## GitLab-specific references + +GitLab Flavored Markdown renders GitLab-specific references. For example, you can reference +an issue, a commit, a team member, or even an entire project team. GitLab Flavored Markdown turns +that reference into a link so you can navigate between them. + +Additionally, GitLab Flavored Markdown recognizes certain cross-project references and also has a shorthand +version to reference other projects from the same namespace. + +GitLab Flavored Markdown recognizes the following: + +| references | input | cross-project reference | shortcut inside same namespace | +| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | +| specific user | `@user_name` | | | +| specific group | `@group_name` | | | +| entire team | `@all` | | | +| project | `namespace/project>` | | | +| issue | ``#123`` | `namespace/project#123` | `project#123` | +| merge request | `!123` | `namespace/project!123` | `project!123` | +| snippet | `$123` | `namespace/project$123` | `project$123` | +| epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | +| vulnerability **(ULTIMATE)** (1)| `[vulnerability:123]` | `[vulnerability:namespace/project/123]` | `[vulnerability:project/123]` | +| feature flag | `[feature_flag:123]` | `[feature_flag:namespace/project/123]` | `[feature_flag:project/123]` | +| label by ID | `~123` | `namespace/project~123` | `project~123` | +| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | +| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | +| scoped label by name | `~"priority::high"` | `namespace/project~"priority::high"` | `project~"priority::high"` | +| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | +| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | +| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | +| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | +| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | +| repository file references | `[README](doc/README.md)` | | | +| repository file line references | `[README](doc/README.md#L13)` | | | +| [alert](../operations/incident_management/alerts.md) | `^alert#123` | `namespace/project^alert#123` | `project^alert#123` | + +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222483) in GitLab 13.7. + +For example, referencing an issue by using `#123` formats the output as a link +to issue number 123 with text `#123`. Likewise, a link to issue number 123 is +recognized and formatted with text `#123`. If you don't want `#123` to link to an issue, +add a leading backslash `\#123`. + +In addition to this, links to some objects are also recognized and formatted. Some examples of these are: + +- Comments on issues: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234#note_101075757"`, which are rendered as `#1234 (comment 101075757)` +- The issues designs tab: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs"`, which are rendered as `#1234 (designs)`. +- Links to individual designs: `"https://gitlab.com/gitlab-org/gitlab/-/issues/1234/designs/layout.png"`, which are rendered as `#1234[layout.png]`. + ### Embedding metrics in GitLab Flavored Markdown Metric charts can be embedded in GitLab Flavored Markdown. Read [Embedding Metrics in GitLab flavored Markdown](../operations/metrics/embed.md) for more details. -## Standard Markdown and extensions in GitLab +## Features extended from standard Markdown All standard Markdown formatting should work as expected in GitLab. Some standard functionality is extended with additional features, without affecting the standard usage. @@ -629,7 +586,7 @@ Quote break. #### Multiline blockquote -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiline-blockquote). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiline-blockquote). GitLab Flavored Markdown extends the standard Markdown by also supporting multi-line blockquotes fenced by `>>>`: @@ -713,7 +670,7 @@ Tildes are OK too. #### Colored code and syntax highlighting If this section isn't rendered correctly, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax highlighting in code blocks. For a list of supported languages visit the @@ -804,7 +761,7 @@ Strikethrough uses two tildes. ~~Scratch this.~~ #### Multiple underscores in words and mid-word emphasis If this section isn't rendered correctly, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words). +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#multiple-underscores-in-words). Avoid italicizing a portion of a word, especially when you're dealing with code and names that often appear with multiple underscores. @@ -995,7 +952,7 @@ Do not change to a reference style link. #### Videos -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#videos). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#videos). Image tags that link to files with a video extension are automatically converted to a video player. The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`: @@ -1012,7 +969,7 @@ Here's a sample video: #### Audio -If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#audio). +If this section isn't rendered correctly, [view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#audio). Similar to videos, link tags for files with an audio extension are automatically converted to an audio player. The valid audio extensions are `.mp3`, `.oga`, `.ogg`, `.spx`, and `.wav`: @@ -1030,7 +987,7 @@ Here's a sample audio clip: ### Inline HTML To see the second example of Markdown rendered in HTML, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html). +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#inline-html). You can also use raw HTML in your Markdown, and it usually works pretty well. @@ -1095,7 +1052,7 @@ Markdown is fine in GitLab. #### Collapsible section To see the second Markdown example rendered in HTML, -[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary). +[view it in GitLab](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#details-and-summary). Content can be collapsed using HTML's [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) @@ -1439,26 +1396,32 @@ while the equation for the theory of relativity is E = mc2. Tables are not part of the core Markdown spec, but they are part of GitLab Flavored Markdown. 1. The first line contains the headers, separated by "pipes" (`|`). -1. The second line separates the headers from the cells, and must contain three or more dashes. +1. The second line separates the headers from the cells. + - The cells can contain only empty spaces, hyphens, and + (optionally) colons for horizontal alignment. + - Each cell must contain at least one hyphen, but adding more hyphens to a + cell does not change the cell's rendering. + - Any content other than hyphens, whitespace, or colons is not allowed 1. The third, and any following lines, contain the cell values. - You **can't** have cells separated over many lines in the Markdown, they must be kept to single lines, but they can be very long. You can also include HTML `
` tags to force newlines if needed. - The cell sizes **don't** have to match each other. They are flexible, but must be separated by pipes (`|`). - You **can** have blank cells. +1. Column widths are calculated dynamically based on the content of the cells. Example: ```markdown | header 1 | header 2 | header 3 | -| --- | ------ |----------| +| --- | --- | --- | | cell 1 | cell 2 | cell 3 | | cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell 9 | ``` | header 1 | header 2 | header 3 | -| --- | ------ |----------| +| --- | --- | --- | | cell 1 | cell 2 | cell 3 | | cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It eventually wraps the text when the cell is too large for the display size. | | cell 7 | | cell 9 | @@ -1467,18 +1430,18 @@ Additionally, you can choose the alignment of text in columns by adding colons ( to the sides of the "dash" lines in the second row. This affects every cell in the column: ```markdown -| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | -| :--- | :---: | ---: | :----------- | :------: | ------------: | -| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | -| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +| Left Aligned | Centered | Right Aligned | +| :--- | :---: | ---: | +| Cell 1 | Cell 2 | Cell 3 | +| Cell 4 | Cell 5 | Cell 6 | ``` -| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | -| :--- | :---: | ---: | :----------- | :------: | ------------: | -| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | -| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +| Left Aligned | Centered | Right Aligned | +| :--- | :---: | ---: | +| Cell 1 | Cell 2 | Cell 3 | +| Cell 4 | Cell 5 | Cell 6 | -[In GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#tables), +[In GitLab itself](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/markdown.md#tables), the headers are always left-aligned in Chrome and Firefox, and centered in Safari. You can use HTML formatting to adjust the rendering of tables. For example, you can @@ -1486,13 +1449,13 @@ use `
` tags to force a cell to have multiple lines: ```markdown | Name | Details | -|------|---------| +| --- | --- | | Item1 | This is on one line | | Item2 | This item has:
- Multiple items
- That we want listed separately | ``` | Name | Details | -|------|---------| +| --- | --- | | Item1 | This is on one line | | Item2 | This item has:
- Multiple items
- That we want listed separately | @@ -1501,7 +1464,7 @@ but they do not render properly on `docs.gitlab.com`: ```markdown | header 1 | header 2 | -|----------|----------| +| --- | --- | | cell 1 | cell 2 | | cell 3 |
  • - [ ] Task one
  • - [ ] Task two
| ``` @@ -1529,3 +1492,56 @@ 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 be3454dbd02..29ca3a48e70 100644 --- a/doc/user/operations_dashboard/index.md +++ b/doc/user/operations_dashboard/index.md @@ -12,7 +12,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Operations Dashboard provides a summary of each project's operational health, including pipeline and alert status. -The dashboard can be accessed from the top bar, by clicking **More > Operations**. +To access the dashboard, on the top bar, select **Menu > Operations**. ## Adding a project to the dashboard diff --git a/doc/user/packages/composer_repository/index.md b/doc/user/packages/composer_repository/index.md index bc1e59e4ac2..b5170dfa55b 100644 --- a/doc/user/packages/composer_repository/index.md +++ b/doc/user/packages/composer_repository/index.md @@ -120,7 +120,7 @@ You can publish a Composer package to the Package Registry as part of your CI/CD deploy: stage: deploy script: - - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag= "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/packages/composer"' + - 'curl --header "Job-Token: $CI_JOB_TOKEN" --data tag= "${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/composer"' ``` 1. Run the pipeline. @@ -131,7 +131,7 @@ To view the published package, go to **Packages & Registries > Package Registry* A more detailed Composer CI/CD file is also available as a `.gitlab-ci.yml` template: -1. On the left sidebar, click **Project overview**. +1. On the left sidebar, select **Project information**. 1. Above the file list, click **Set up CI/CD**. If this button is not available, select **CI/CD Configuration** and then **Edit**. 1. From the **Apply a template** list, select **Composer**. diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 53d191cbcfe..a429e746cf2 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -281,7 +281,7 @@ image: conanio/gcc7 create_package: stage: deploy script: - - conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan + - conan remote add gitlab ${CI_API_V4_URL}/projects/$CI_PROJECT_ID/packages/conan - conan new /0.1 -t - conan create . +/stable - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload /0.1@+/stable --all --remote=gitlab diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 6d7b009bb09..9d65c5d37ad 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -512,6 +512,17 @@ On GitLab.com, the execution time for the cleanup policy is limited, and some of 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. @@ -633,7 +644,9 @@ Examples: - Select all tags, keep at least 1 tag per image, clean up any tag older than 14 days, run once a month, preserve any images with the name `master` and the policy is enabled: ```shell - curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: " --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' "https://gitlab.example.com/api/v4/projects/2" + curl --request PUT --header 'Content-Type: application/json;charset=UTF-8' --header "PRIVATE-TOKEN: " \ + --data-binary '{"container_expiration_policy_attributes":{"cadence":"1month","enabled":true,"keep_n":1,"older_than":"14d","name_regex":"","name_regex_delete":".*","name_regex_keep":".*-master"}}' \ + "https://gitlab.example.com/api/v4/projects/2" ``` Valid values for `cadence` when using the API are: diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index b871a08c133..f0bf2fc3363 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -46,7 +46,6 @@ guides you through the process. | Puppet | [#36897](https://gitlab.com/gitlab-org/gitlab/-/issues/36897) | | RPM | [#5932](https://gitlab.com/gitlab-org/gitlab/-/issues/5932) | | SBT | [#36898](https://gitlab.com/gitlab-org/gitlab/-/issues/36898) | -| Terraform | [Draft: Merge Request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18834) | | Vagrant | [#36899](https://gitlab.com/gitlab-org/gitlab/-/issues/36899) | @@ -54,6 +53,16 @@ guides you through the process. The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects. +## Infrastructure Registry + +The GitLab [Infrastructure Registry](infrastructure_registry/index.md) is a secure and private registry for infrastructure packages. You can use GitLab CI/CD to create and publish infrastructure packages. + +The Infrastructure Registry supports the following formats: + +| Package type | GitLab version | +| ------------ | -------------- | +| [Terraform Module](terraform_module_registry/index.md) | 14.0+ | + ## Dependency Proxy The [Dependency Proxy](dependency_proxy/index.md) is a local proxy for frequently-used upstream images and packages. diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md new file mode 100644 index 00000000000..00370bd2f48 --- /dev/null +++ b/doc/user/packages/infrastructure_registry/index.md @@ -0,0 +1,93 @@ +--- +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 +--- + +# Infrastructure Registry **(FREE)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. + +With the GitLab Infrastructure Registry, you can use GitLab projects as a +private registry for infrastructure packages. You can create and publish +packages with GitLab CI/CD, which can then be consumed from other private +projects. + +## View packages + +To view packages within your project or group: + +1. Go to the project or group. +1. Go to **Packages & Registries > Infrastructure Registry**. + +You can search, sort, and filter packages on this page. + +When you view packages in a group: + +- All packages published to the group and its projects are displayed. +- Only the projects you can access are displayed. +- If a project is private, or you are not a member of the project, it is not displayed. + +For information on how to create and upload a package, view the GitLab +documentation for your package type: + +- [Terraform modules](../terraform_module_registry/index.md) + +## Use GitLab CI/CD to build packages + +To use [GitLab CI/CD](../../../ci/README.md) to build packages, you can +authenticate with the [`CI_JOB_TOKEN` predefined variable](../../../ci/variables/predefined_variables.md). + +CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). + +Learn more about using CI/CD to build: + +- [Terraform modules](../terraform_module_registry/index.md#publish-a-terraform-module-by-using-cicd) + +If you use CI/CD to build a package, you can find extended activity information +when you view the package details: + +![Package CI/CD activity](../package_registry/img/package_activity_v12_10.png) + +You can see the pipeline that published the package as well as the commit and the user who triggered it. However, the history is limited to five updates per package. + +## Download a package + +To download a package: + +1. Go to **Packages & Registries > Infrastructure Registry**. +1. Select the name of the package you want to download. +1. In the **Activity** section, select the name of the package you want to download. + +## Delete a package + +You cannot edit a package after you publish it in the Infrastructure Registry. Instead, you +must delete and recreate it. + +To delete a package, you must have suitable [permissions](../../permissions.md). + +You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI. + +To delete a package in the UI, from your group or project: + +1. Go to **Packages & Registries > Infrastructure Registry**. +1. Find the name of the package you want to delete. +1. Select **Delete**. + +The package is permanently deleted. + +## Disable the Infrastructure Registry + +The Infrastructure Registry is automatically enabled. + +For self-managed instances, a GitLab administrator can +[disable](../../../administration/packages/index.md) **Packages & Registries**, +which removes this menu item from the sidebar. **(FREE SELF)** + +You can also remove the Infrastructure Registry for a specific project: + +1. In your project, go to **Settings > General**. +1. Expand the **Visibility, project features, permissions** section and toggle **Packages** off (in gray). +1. Select **Save changes**. + +To enable it back, follow the same steps above and toggle it on (in blue). diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index ba7b55dc47d..2567cc3b828 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -341,7 +341,7 @@ file: ```groovy repositories { maven { - url "https://gitlab.example.com/api/v4/groups//-/packages/maven" + url "${CI_API_V4_URL}/groups//-/packages/maven" name "GitLab" credentials(HttpHeaderCredentials) { name = 'Job-Token' @@ -611,8 +611,11 @@ Now navigate to your project's **Packages & Registries** page and view the publi ### Publishing a package with the same name or version -When you publish a package with the same name or version as an existing package, -the existing package is overwritten. +When you publish a package with the same name and version as an existing package, the new package +files are added to the existing package. You can still use the UI or API to access and view the +existing package's older files. + +To delete these older package versions, consider using the Packages API or the UI. #### Do not allow duplicate Maven packages @@ -742,17 +745,17 @@ You can create a new package each time the `master` branch is updated. gitlab-maven - ${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven + $env{CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven gitlab-maven - ${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven + ${CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven gitlab-maven - ${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven + ${CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven ``` diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index ace432b305f..735873be237 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -110,7 +110,8 @@ To authenticate, use one of the following: - It's not recommended, but you can use [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow). Standard OAuth tokens cannot authenticate to the GitLab npm Registry. You must use a personal access token with OAuth headers. - A [CI job token](#authenticate-with-a-ci-job-token). -- Your npm package name must be in the format of [@scope/package-name](#package-naming-convention). It must match exactly, including the case. +- Your npm package name must be in the format of [`@scope/package-name`](#package-naming-convention). + It must match exactly, including the case. ### Authenticate with a personal access token or deploy token @@ -282,7 +283,7 @@ Prerequisites: - [Authenticate](#authenticate-to-the-package-registry) to the Package Registry. - Set a [project-level npm endpoint](#use-the-gitlab-endpoint-for-npm-packages). -- Your npm package name must be in the format of [@scope/package-name](#package-naming-convention). +- Your npm package name must be in the format of [`@scope/package-name`](#package-naming-convention). It must match exactly, including the case. This is different than the npm naming convention, but it is required to work with the GitLab Package Registry. @@ -300,7 +301,7 @@ stages: deploy: stage: deploy script: - - echo "//gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc + - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc - npm publish ``` @@ -532,7 +533,7 @@ If you get this error, ensure that: ### `npm publish` returns `npm ERR! 400 Bad Request` If you get this error, your package name may not meet the -[@scope/package-name package naming convention](#package-naming-convention). +[`@scope/package-name` package naming convention](#package-naming-convention). Ensure the name meets the convention exactly, including the case. Then try to publish again. diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md index 7e59b19076a..f19d565ef36 100644 --- a/doc/user/packages/nuget_repository/index.md +++ b/doc/user/packages/nuget_repository/index.md @@ -336,7 +336,7 @@ updated: stage: deploy script: - dotnet pack -c Release - - dotnet nuget add source "$CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text + - dotnet nuget add source "${CI_API_V4_URL}/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text - dotnet nuget push "bin/Release/*.nupkg" --source gitlab only: - master diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index f04f6f1316e..52ce7d62940 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -40,14 +40,16 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`. CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -Learn more about using CI/CD to build: +Learn more about using the GitLab Package Registry with CI/CD: -- [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) -- [Conan packages](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) -- [Generic packages](../generic_packages/index.md#publish-a-generic-package-by-using-cicd) -- [Maven packages](../maven_repository/index.md#create-maven-packages-with-gitlab-cicd) -- [npm packages](../npm_registry/index.md#publish-an-npm-package-by-using-cicd) -- [NuGet packages](../nuget_repository/index.md#publish-a-nuget-package-by-using-cicd) +- [Composer](../composer_repository/index.md#publish-a-composer-package-by-using-cicd) +- [Conan](../conan_repository/index.md#publish-a-conan-package-by-using-cicd) +- [Generic](../generic_packages/index.md#publish-a-generic-package-by-using-cicd) +- [Maven](../maven_repository/index.md#create-maven-packages-with-gitlab-cicd) +- [npm](../npm_registry/index.md#publish-an-npm-package-by-using-cicd) +- [NuGet](../nuget_repository/index.md#publish-a-nuget-package-by-using-cicd) +- [PyPI](../pypi_repository/#authenticate-with-a-ci-job-token) +- [RubyGems](../rubygems_registry/#authenticate-with-a-ci-job-token) If you use CI/CD to build a package, extended activity information is displayed when you view the package details: @@ -81,6 +83,22 @@ To delete a package in the UI, from your group or project: The package is permanently deleted. +## Delete files associated with a package + +To delete package files, you must have suitable [permissions](../../permissions.md). + +You can delete packages by using [the API](../../../api/packages.md#delete-a-package-file) or the UI. + +To delete package files in the UI, from your group or project: + +1. Go to **Packages & Registries > Package Registry**. +1. Find the name of the package you want to delete. +1. Select the package to view additional details. +1. Find the name of the file you would like to delete. +1. Expand the ellipsis and select **Delete file**. + +The package files are permanently deleted. + ## Disable the Package Registry The Package Registry is automatically enabled. @@ -100,6 +118,9 @@ The **Packages & Registries > Package Registry** entry is removed from the sideb ## Package workflows -Learn how to use the GitLab Package Registry to build your own custom package workflow. +Learn how to use the GitLab Package Registry to build your own custom package workflow: + +- [Use a project as a package registry](../workflows/project_registry.md) + to publish all of your packages to one project. -- [Use a project as a package registry](../workflows/project_registry.md) to publish all of your packages to one project. +- Publish multiple different packages from one [monorepo project](../workflows/working_with_monorepos.md). diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 17b51e313fa..2dd00fdc273 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -216,7 +216,7 @@ run: script: - pip install twine - python setup.py sdist bdist_wheel - - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/* + - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/* ``` You can also use `CI_JOB_TOKEN` in a `~/.pypirc` file that you check in to @@ -233,6 +233,14 @@ username = gitlab-ci-token password = ${env.CI_JOB_TOKEN} ``` +### Authenticate to access packages within a group + +Follow the instructions above for the token type, but use the group URL in place of the project URL: + +```shell +https://gitlab.example.com/api/v4/groups//-/packages/pypi +``` + ## Publish a PyPI package Prerequisites: @@ -316,6 +324,8 @@ more than once, a `404 Bad Request` error occurs. ## Install a PyPI package +### Install from the project level + To install the latest version of a package, use the following command: ```shell @@ -350,6 +360,33 @@ Installing collected packages: mypypipackage Successfully installed mypypipackage-0.0.1 ``` +### Install from the group level + +To install the latest version of a package from a group, use the following command: + +```shell +pip install --index-url https://:@gitlab.example.com/api/v4/groups//-/packages/pypi/simple --no-deps +``` + +In this command: + +- `` is the package name. +- `` is a personal access token name with the `read_api` scope. +- `` is a personal access token with the `read_api` scope. +- `` is the group ID. + +In these commands, you can use `--extra-index-url` instead of `--index-url`. However, using +`--extra-index-url` makes you vulnerable to dependency confusion attacks because it checks the PyPi +repository for the package before it checks the custom repository. `--extra-index-url` adds the +provided URL as an additional registry which the client checks if the package is present. +`--index-url` tells the client to check for the package at the provided URL only. + +If you're following the guide and want to install the `MyPyPiPackage` package, you can run: + +```shell +pip install mypypipackage --no-deps --index-url https://:@gitlab.example.com/api/v4/groups//-/packages/pypi/simple +``` + ### Package names GitLab looks for packages that use diff --git a/doc/user/packages/rubygems_registry/index.md b/doc/user/packages/rubygems_registry/index.md index e4d297ac1d8..743bc229e11 100644 --- a/doc/user/packages/rubygems_registry/index.md +++ b/doc/user/packages/rubygems_registry/index.md @@ -88,11 +88,11 @@ run: - mkdir ~/.gem - echo "---" > ~/.gem/credentials - | - echo "https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/rubygems: '${CI_JOB_TOKEN}'" >> ~/.gem/credentials + echo "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/rubygems: '${CI_JOB_TOKEN}'" >> ~/.gem/credentials - chmod 0600 ~/.gem/credentials # rubygems requires 0600 permissions on the credentials file script: - gem build my_gem - - gem push my_gem-0.0.1.gem --host https://gitlab.example.com/api/v4/projects/${CI_PROJECT_ID}/packages/rubygems + - gem push my_gem-0.0.1.gem --host ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/rubygems ``` You can also use `CI_JOB_TOKEN` in a `~/.gem/credentials` file that you check in to diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md new file mode 100644 index 00000000000..efb2b8ddf8e --- /dev/null +++ b/doc/user/packages/terraform_module_registry/index.md @@ -0,0 +1,124 @@ +--- +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 +--- + +# Terraform module registry **(FREE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. + +Publish Terraform modules in your project's Infrastructure Registry, then reference them using GitLab +as a Terraform module registry. + +## Authenticate to the Terraform module registry + +To authenticate to the Terraform module registry, you need either: + +- A [personal access token](../../../api/README.md#personalproject-access-tokens) with at least `read_api` rights. +- A [CI/CD job token](../../../api/README.md#gitlab-cicd-job-token). + +## Publish a Terraform Module + +When you publish a Terraform Module, if it does not exist, it is created. + +If a package with the same name and version already exists, it will not be created. It does not overwrite the existing package. + +Prerequisites: + +- You need to [authenticate with the API](../../../api/README.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. + +```plaintext +PUT /projects/:id/packages/terraform/modules/:module_name/:module_system/:module_version/file +``` + +| Attribute | Type | Required | Description | +| -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/README.md#namespaced-path-encoding). | +| `module_name` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`). +| `module_system` | string | yes | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), or hyphens (`-`). +| `module_version` | string | yes | The package version. It must be valid according to the [Semantic Versioning Specification](https://semver.org/). + +Provide the file content in the request body. + +Example request using a personal access token: + +```shell +curl --header "PRIVATE-TOKEN: " \ + --upload-file path/to/file.tgz \ + "https://gitlab.example.com/api/v4/projects//packages/terraform/modules/my-module/my-system/0.0.1/file" +``` + +Example response: + +```json +{ + "message":"201 Created" +} +``` + +Example request using a deploy token: + +```shell +curl --header "DEPLOY-TOKEN: " \ + --upload-file path/to/file.tgz \ + "https://gitlab.example.com/api/v4/projects//packages/terraform/modules/my-module/my-system/0.0.1/file" +``` + +Example response: + +```json +{ + "message":"201 Created" +} +``` + +## Reference a Terraform Module + +Prerequisites: + +- You need to [authenticate with the API](../../../api/README.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. + +Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: + +```plaintext +credentials "gitlab.com" { + token = "" +} +``` + +Where `gitlab.com` can be replaced with the hostname of your self-managed GitLab instance. + +You can then reference your Terraform Module from a downstream Terraform project: + +```plaintext +module "" { + source = "gitlab.com///" +} +``` + +## Publish a Terraform module by using CI/CD + +To work with Terraform modules in [GitLab CI/CD](../../../ci/README.md), you can use +`CI_JOB_TOKEN` in place of the personal access token in your commands. + +For example: + +```yaml +image: curlimages/curl:latest + +stages: + - upload + +upload: + stage: upload + script: + - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.tgz "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/my-module/my-system/0.0.1/file"' +``` + +## Example projects + +For examples of the Terraform module registry, check the projects below: + +- The [_GitLab local file_ project](https://gitlab.com/mattkasa/gitlab-local-file) creates a minimal Terraform module and uploads it into the Terraform module registry using GitLab CI/CD. +- The [_Terraform module test_ project](https://gitlab.com/mattkasa/terraform-module-test) uses the module from the previous example. diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 3e1c1e7f2ad..12978ad72a5 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -34,8 +34,8 @@ of each package management system to publish different package types to the same Let's take a look at how you might create a public place to hold all of your public packages. -1. Create a new project in GitLab. The project doesn't require any code or content. Note the project ID - that's displayed on the project overview page. +1. Create a new project in GitLab. The project doesn't require any code or content. +1. On the left sidebar, select **Project information**, and note the project ID. 1. Create an access token. All package types in the Package Registry are accessible by using [GitLab personal access tokens](../../profile/personal_access_tokens.md). If you're using CI/CD, you can use CI job tokens (`CI_JOB_TOKEN`) to authenticate. diff --git a/doc/user/packages/workflows/working_with_monorepos.md b/doc/user/packages/workflows/working_with_monorepos.md new file mode 100644 index 00000000000..4e431b036de --- /dev/null +++ b/doc/user/packages/workflows/working_with_monorepos.md @@ -0,0 +1,64 @@ +--- +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 +--- + +# Monorepo package management workflows + +One project or Git repository can contain multiple different subprojects or submodules that are all +packaged and published individually. + +## Publishing different packages to the parent project + +The number and name of packages you can publish to one project is not limited. +You can accomplish this by setting up different configuration files for each +package. See the documentation for the package manager of your choice since +each has its own specific files and instructions to follow to publish +a given package. + +The example here uses [NPM](../npm_registry/index.md). +In this example, `MyProject` is the parent project. It contains a sub-project `Foo` in the +`components` directory: + +```plaintext +MyProject/ + |- src/ + | |- components/ + | |- Foo/ + |- package.json +``` + +The goal is to publish the packages for `MyProject` and `Foo`. Following the instructions in the +[GitLab NPM registry documentation](../npm_registry/index.md), +you can publish `MyProject` by modifying the `package.json` file with a `publishConfig` section, +and by doing one of the following: + +- Modify your local NPM configuration with CLI commands like `npm config set`. +- Save a `.npmrc` file in the root of the project specifying these configuration settings. + +If you follow the instructions, you can publish `MyProject` by running `npm publish` from the root +directory. + +Publishing `Foo` is almost exactly the same. Simply follow the same steps while in the `Foo` +directory. `Foo` needs its own `package.json` file, which you can add manually by using `npm init`. +`Foo` also needs its own configuration settings. Since you are publishing to the same place, if you +used `npm config set` to set the registry for the parent project, then no additional setup is +necessary. If you used an `.npmrc` file, you need an additional `.npmrc` file in the `Foo` directory. +Be sure to add `.npmrc` files to the `.gitignore` file or use environment variables in place of your +access tokens to prevent your tokens from being exposed. This `.npmrc` file can be identical to the +one you used in `MyProject`. You can now run `npm publish` from the `Foo` directory and you can +publish `Foo` separately from `MyProject`. + +You could follow a similar process for Conan packages. However, instead of `.npmrc` and +`package.json`, you have `conanfile.py` in multiple locations within the project. + +## Publishing to other projects + +A package is associated with a project on GitLab, but the package does not need to be associated +with the code in that project. When configuring NPM or Maven, you only use the `Project ID` to set +the registry URL that the package uploads to. If you set this to any project that you have access to +and update any other configuration similarly depending on the package type, your packages are +published to that project. This means you can publish multiple packages to one project, even if +their code does not exist in the same place. See the [project registry workflow documentation](project_registry.md) +for more information. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 245efc0e908..6739d08e156 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -4,20 +4,17 @@ 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 --- -# Permissions +# Permissions and roles -Users have different abilities depending on the access level they have in a +Users have different abilities depending on the role they have in a particular group or project. If a user is both in a project's group and the -project itself, the highest permission level is used. +project itself, the highest role is used. -On public and internal projects, the Guest role is not enforced. All users can: +On [public and internal projects](../api/projects.md#project-visibility-level), the Guest role +(not to be confused with [Guest user](#free-guest-users)) is not enforced. -- Create issues. -- Leave comments. -- Clone or download the project code. - -When a member leaves a team's project, all the assigned [Issues](project/issues/index.md) and [Merge Requests](project/merge_requests/index.md) -are unassigned automatically. +When a member leaves a team's project, all the assigned [issues](project/issues/index.md) and +[merge requests](project/merge_requests/index.md) are automatically unassigned. GitLab [administrators](../administration/index.md) receive all permissions. @@ -39,11 +36,11 @@ usernames. A GitLab administrator can configure the GitLab instance to NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. -The Owner permission is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects. +The Owner role is only available at the group or personal namespace level (and for instance administrators) and is inherited by its projects. While Maintainer is the highest project-level role, some actions can only be performed by a personal namespace or group owner, or an instance administrator, who receives all permissions. For more information, see [projects members documentation](project/members/index.md). -The following table depicts the various user permission levels in a project. +The following table lists project permissions available for each role: | Action | Guest | Reporter | Developer |Maintainer| Owner | |---------------------------------------------------|---------|------------|-------------|----------|--------| @@ -71,7 +68,7 @@ The following table depicts the various user permission levels in a project. | View requirements **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Insights **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Issue analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View Merge Request analytics **(STARTER)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| View Merge Request analytics **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | | View Value Stream analytics | ✓ | ✓ | ✓ | ✓ | ✓ | | Manage user-starred metrics dashboards (*7*) | ✓ | ✓ | ✓ | ✓ | ✓ | | View confidential issues | (*2*) | ✓ | ✓ | ✓ | ✓ | @@ -80,6 +77,7 @@ The following table depicts the various user permission levels in a project. | Label issues | | ✓ | ✓ | ✓ | ✓ | | Set issue weight | | ✓ | ✓ | ✓ | ✓ | | [Set issue estimate and record time spent](project/time_tracking.md) | | ✓ | ✓ | ✓ | ✓ | +| View a time tracking report | ✓ (*1*) | ✓ | ✓ | ✓ | ✓ | | Lock issue threads | | ✓ | ✓ | ✓ | ✓ | | Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | | Manage linked issues | | ✓ | ✓ | ✓ | ✓ | @@ -91,7 +89,7 @@ The following table depicts the various user permission levels in a project. | See [DORA metrics](analytics/ci_cd_analytics.md) | | ✓ | ✓ | ✓ | ✓ | | See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | | View CI/CD analytics | | ✓ | ✓ | ✓ | ✓ | -| View Code Review analytics **(STARTER)** | | ✓ | ✓ | ✓ | ✓ | +| View Code Review analytics **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | View Repository analytics | | ✓ | ✓ | ✓ | ✓ | | View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | | View metrics dashboard annotations | | ✓ | ✓ | ✓ | ✓ | @@ -103,6 +101,7 @@ The following table depicts the various user permission levels in a project. | Move [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Reopen [test case](../ci/test_cases/index.md) | | ✓ | ✓ | ✓ | ✓ | | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | +| View project statistics | | ✓ | ✓ | ✓ | ✓ | | Publish [packages](packages/index.md) | | | ✓ | ✓ | ✓ | | Create/edit/delete a Cleanup policy | | | ✓ | ✓ | ✓ | | Upload [Design Management](project/issues/design_management.md) files | | | ✓ | ✓ | ✓ | @@ -119,7 +118,6 @@ The following table depicts the various user permission levels in a project. | Lock merge request threads | | | ✓ | ✓ | ✓ | | Approve merge requests (*9*) | | | ✓ | ✓ | ✓ | | Manage/Accept merge requests | | | ✓ | ✓ | ✓ | -| View project statistics | | | ✓ | ✓ | ✓ | | Create new environments | | | ✓ | ✓ | ✓ | | Stop environments | | | ✓ | ✓ | ✓ | | Enable Review Apps | | | ✓ | ✓ | ✓ | @@ -256,16 +254,18 @@ NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. Any user can remove themselves from a group, unless they are the last Owner of -the group. The following table depicts the various user permission levels in a -group. +the group. + +The following table lists group permissions available for each role: | Action | Guest | Reporter | Developer | Maintainer | Owner | |--------------------------------------------------------|-------|----------|-----------|------------|-------| | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | | View group wiki pages **(PREMIUM)** | ✓ (6) | ✓ | ✓ | ✓ | ✓ | | View Insights charts **(ULTIMATE)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | -| Create/edit group epic **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| View group epic **(PREMIUM)** | ✓ | ✓ | ✓ | ✓ | ✓ | +| Create/edit group epic **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | +| Create/edit/delete epic boards **(PREMIUM)** | | ✓ | ✓ | ✓ | ✓ | | Manage group labels | | ✓ | ✓ | ✓ | ✓ | | See a container registry | | ✓ | ✓ | ✓ | ✓ | | Pull [packages](packages/index.md) | | ✓ | ✓ | ✓ | ✓ | @@ -289,8 +289,8 @@ group. | Create/Delete group deploy tokens | | | | | ✓ | | Manage group members | | | | | ✓ | | Delete group | | | | | ✓ | -| Delete group epic **(PREMIUM)** | | | | | ✓ | -| Edit SAML SSO Billing **(PREMIUM SAAS)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | +| Delete group epic **(PREMIUM)** | | | | | ✓ | +| Edit SAML SSO Billing **(PREMIUM SAAS)** | ✓ | ✓ | ✓ | ✓ | ✓ (4) | | View group Audit Events | | | ✓ (7) | ✓ (7) | ✓ | | Disable notification emails | | | | | ✓ | | View Contribution analytics | ✓ | ✓ | ✓ | ✓ | ✓ | @@ -359,10 +359,11 @@ External users still count towards a license seat. An administrator can flag a user as external by either of the following methods: -- Either [through the API](../api/users.md#user-modification). -- Or by navigating to the **Admin Area > Overview > Users** to create a new user - or edit an existing one. There, you can find the option to flag the user as - external. +- [Through the API](../api/users.md#user-modification). +- Using the GitLab UI: + 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the left sidebar, select **Overview > Users** to create a new user or edit an existing one. + There, you can find the option to flag the user as external. Additionally users can be set as external users using [SAML groups](../integration/saml.md#external-groups) and [LDAP groups](../administration/auth/ldap/index.md#external-groups). @@ -370,7 +371,11 @@ and [LDAP groups](../administration/auth/ldap/index.md#external-groups). ### Setting new users to external By default, new users are not set as external users. This behavior can be changed -by an administrator on the **Admin Area > Settings > General** page, under **Account and limit**. +by an administrator: + +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Settings > General**. +1. Expand the **Account and limit** section. If you change the default behavior of creating new users as external, you have the option to narrow it down by defining a set of internal users. @@ -455,33 +460,32 @@ NOTE: In GitLab 11.0, the Master role was renamed to Maintainer. GitLab CI/CD permissions rely on the role the user has in GitLab. There are four -permission levels in total: - -- admin -- maintainer -- developer -- guest/reporter - -The admin user can perform any action on GitLab CI/CD in scope of the GitLab -instance and project. In addition, all admins can use the admin interface under -`/admin/runners`. - -| Action | Guest, Reporter | Developer |Maintainer| Admin | -|---------------------------------------|-----------------|-------------|----------|--------| -| See commits and jobs | ✓ | ✓ | ✓ | ✓ | -| Retry or cancel job | | ✓ | ✓ | ✓ | -| Erase job artifacts and job logs | | ✓ (*1*) | ✓ | ✓ | -| Delete project | | | ✓ | ✓ | -| Create project | | | ✓ | ✓ | -| Change project configuration | | | ✓ | ✓ | -| Add specific runners | | | ✓ | ✓ | -| Add shared runners | | | | ✓ | -| See events in the system | | | | ✓ | -| Admin interface | | | | ✓ | +roles: + +- Administrator +- Maintainer +- Developer +- Guest/Reporter + +The Administrator role can perform any action on GitLab CI/CD in scope of the GitLab +instance and project. + +| Action | Guest, Reporter | Developer |Maintainer| Administrator | +|---------------------------------------|-----------------|-------------|----------|---------------| +| See commits and jobs | ✓ | ✓ | ✓ | ✓ | +| Retry or cancel job | | ✓ | ✓ | ✓ | +| Erase job artifacts and job logs | | ✓ (*1*) | ✓ | ✓ | +| Delete project | | | ✓ | ✓ | +| Create project | | | ✓ | ✓ | +| Change project configuration | | | ✓ | ✓ | +| Add specific runners | | | ✓ | ✓ | +| Add shared runners | | | | ✓ | +| See events in the system | | | | ✓ | +| Admin Area | | | | ✓ | 1. Only if the job was: - Triggered by the user - - [In GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/35069) and later, not run for a protected branch + - [In GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/35069) and later, run for a non-protected branch. ### Job permissions diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 91688989e55..972414dbf0b 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -14,16 +14,21 @@ You can create users: ## Create users on sign in page -If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create their own accounts by selecting "Register now" on the sign-in page, or navigate to `https://gitlab.example.com/users/sign_up`. +If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create +their own accounts by either: + +- Selecting the **Register now** link on the sign-in page. +- Navigating to `https://gitlab.example.com/users/sign_up`. ![Register Tab](img/register_v13_6.png) ## Create users in Admin Area -As an admin user, you can manually create users by: +As an Admin user, you can manually create users: -1. Navigating to **Admin Area > Overview > Users** (`/admin/users` page). -1. Selecting the **New User** button. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users** (`/admin/users`). +1. Select **New user**. You can also [create users through the API](../../../api/users.md) as an admin. @@ -33,9 +38,11 @@ You can also [create users through the API](../../../api/users.md) as an admin. ## Create users through authentication integrations -Users will be: +Users are: - Automatically created upon first sign in with the [LDAP integration](../../../administration/auth/ldap/index.md). -- Created when first signing in via an [OmniAuth provider](../../../integration/omniauth.md) if the `allow_single_sign_on` setting is present. -- Created when first signing with [Group SAML](../../group/saml_sso/index.md) -- Automatically created by [SCIM](../../group/saml_sso/scim_setup.md) when the user is created in the identity provider. +- Created when first signing in using an [OmniAuth provider](../../../integration/omniauth.md) if + the `allow_single_sign_on` setting is present. +- Created when first signing with [Group SAML](../../group/saml_sso/index.md). +- Automatically created by [SCIM](../../group/saml_sso/scim_setup.md) when the user is created in + the identity provider. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 361353a0f8c..c4ab54736bc 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -13,7 +13,7 @@ Users can be deleted from a GitLab instance, either by: - An administrator. NOTE: -Deleting a user will delete all projects in that user namespace. +Deleting a user deletes all projects in that user namespace. ## As a user @@ -28,7 +28,8 @@ As a user, to delete your own account: As an administrator, to delete a user account: -1. Go to **Admin Area > Overview > Users**. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, select **Overview > Users**. 1. Select a user. 1. Under the **Account** tab, select: - **Delete user** to delete only the user but maintain their diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index c763226015e..3f42fc0d131 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -505,7 +505,18 @@ Feature.disable(:webauthn) 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. -Most authentication apps have a feature in the settings for syncing the time for the codes themselves. For Google Authenticator for example, go to `Settings > Time correction for codes`. +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. + 1. Select Settings. + 1. Select the Time correction for the codes. + 1. Select Sync now. +- For iOS: + 1. Go to Settings. + 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. - diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index c7772ac2238..f9e15ced858 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can find the available integrations under your project's **Settings > Integrations** page. You need to have at least -[maintainer permission](../../permissions.md) on the project. +the [Maintainer role](../../permissions.md) on the project. ## Integrations diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index b91a8a1fb3b..521f15f330e 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/index.md' +remove_date: '2021-07-07' --- This document was moved to [another location](../../../integration/jira/index.md). diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index b3091275835..c9ab4532760 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/jira_cloud_configuration.md' +remove_date: '2021-06-18' --- This document was moved to [another location](../../../integration/jira/jira_cloud_configuration.md). diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 485b48df01b..3aacf051c22 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/index.md' +remove_date: '2021-07-13' --- This document was moved to [another location](../../../integration/jira/index.md). diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 191b8f207a1..de6eec62b96 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,5 +1,6 @@ --- redirect_to: '../../../integration/jira/jira_server_configuration.md' +remove_date: '2021-06-18' --- This document was moved to [another location](../../../integration/jira/jira_server_configuration.md). diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 20f5b73b37c..834bf15c287 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -67,9 +67,9 @@ After you enable custom slash commands in Mattermost, you need configuration information from GitLab. To get this information: 1. In a different browser tab than your current Mattermost session, sign in to - GitLab as a user with [administrator permissions](../../permissions.md). -1. In the top navigation bar, go to **{admin}** **Admin Area**. -1. In the left menu, go to **Settings > Integrations** and select + GitLab as a user with [Administrator role](../../permissions.md). +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. In the left menu, select **Settings > Integrations**, then select **Mattermost slash commands**. 1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** as you need it for the next step. All other values are suggestions. diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 5bd4062b125..b0ae290e7cd 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -80,19 +80,6 @@ instance configuration or provide custom settings. Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). -### Service templates - -[Service templates](services_templates.md) were a way to set predefined values for -a project integration across all new projects on the instance. They are deprecated and -[scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) -in GitLab 14.0. - -GitLab recommends you use [project integration management](../../admin_area/settings/project_integration_management.md) -instead of service templates. GitLab versions 13.3 and later provide -[instance-level integrations](../../admin_area/settings/project_integration_management.md#project-integration-management) -you can use. -instead. - ## Troubleshooting integrations Some integrations use service hooks for integration with external applications. To confirm which ones use service hooks, see the [integrations listing](#integrations-listing) above. GitLab stores details of service hook requests made within the last 2 days. To view details of the requests, go to that integration's configuration page. @@ -128,6 +115,6 @@ plugins. This allows the community to keep the plugins up to date so that they always work in newer GitLab versions. For an overview of what integrations are available, please see the -[project_services source directory](https://gitlab.com/gitlab-org/gitlab/tree/master/app/models/project_services). +[project_services source directory](https://gitlab.com/gitlab-org/gitlab/-/tree/master/app/models/project_services). Contributions are welcome! diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 4922c8d9b62..adc98151ce4 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -17,7 +17,7 @@ in the GitLab interface. There are two ways to set up Prometheus integration, depending on where your apps are running: -- For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes). +- For deployments on Kubernetes, GitLab can be [integrated with an in-cluster Prometheus](#prometheus-cluster-integration) - For other deployment targets, [specify the Prometheus server](#manual-configuration-of-prometheus). Once enabled, GitLab detects metrics from known services in the @@ -27,141 +27,13 @@ Once enabled, GitLab detects metrics from known services in the ## Enabling Prometheus Integration -### Managed Prometheus on Kubernetes +### Prometheus cluster integration -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/55244) in GitLab 13.11. +> - [Replaced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62725) the Prometheus cluster applications in GitLab 14.0. -**Deprecated:** Managed Prometheus on Kubernetes is deprecated, and -scheduled for removal in [GitLab -14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). - -GitLab can seamlessly deploy and manage Prometheus on a -[connected Kubernetes cluster](../clusters/index.md), to help you monitor your apps. - -#### Requirements - -- A [connected Kubernetes cluster](../clusters/index.md) - -#### Getting started - -After you have a connected Kubernetes cluster, you can deploy a managed Prometheus with a single click. - -1. Go to the **Operations > Kubernetes** page to view your connected clusters -1. Select the cluster you would like to deploy Prometheus to -1. Click the **Install** button to deploy Prometheus to the cluster - -![Managed Prometheus Deploy](img/prometheus_deploy.png) - -#### About managed Prometheus deployments - -Prometheus is deployed into the `gitlab-managed-apps` namespace, using the -[official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). -Prometheus is only accessible in the cluster, with GitLab communicating through the -[Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). - -The Prometheus server -[automatically detects and monitors](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) -nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, -set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - -- `prometheus.io/scrape` to `true` to enable monitoring of the resource. -- `prometheus.io/port` to define the port of the metrics endpoint. -- `prometheus.io/path` to define the path of the metrics endpoint. Defaults to `/metrics`. - -CPU and Memory consumption is monitored, but requires -[naming conventions](prometheus_library/kubernetes.md#specifying-the-environment) -to determine the environment. If you are using -[Auto DevOps](../../../topics/autodevops/index.md), this is handled automatically. - -The [NGINX Ingress](../clusters/index.md#installing-applications) that is deployed -by GitLab to clusters, is automatically annotated for monitoring providing key -response metrics: latency, throughput, and error rates. - -##### Example of Kubernetes service annotations and labels - -As an example, to activate Prometheus monitoring of a service: - -1. Add at least this annotation: `prometheus.io/scrape: 'true'`. -1. Add two labels so GitLab can retrieve metrics dynamically for any environment: - - `application: ${CI_ENVIRONMENT_SLUG}` - - `release: ${CI_ENVIRONMENT_SLUG}` -1. Create a dynamic PromQL query. For example, a query like - `temperature{application="{{ci_environment_slug}}",release="{{ci_environment_slug}}"}` to either: - - Add [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). - - Add [custom dashboards](../../../operations/metrics/dashboards/index.md). - -The following is a service definition to accomplish this: - -```yaml ---- -# Service -apiVersion: v1 -kind: Service -metadata: - name: service-${CI_PROJECT_NAME}-${CI_COMMIT_REF_SLUG} - # === Prometheus annotations === - annotations: - prometheus.io/scrape: 'true' - labels: - application: ${CI_ENVIRONMENT_SLUG} - release: ${CI_ENVIRONMENT_SLUG} - # === End of Prometheus === -spec: - selector: - app: ${CI_PROJECT_NAME} - ports: - - port: ${EXPOSED_PORT} - targetPort: ${CONTAINER_PORT} -``` - -#### Access the UI of a Prometheus managed application in Kubernetes - -You can connect directly to Prometheus, and view the Prometheus user interface, when -using a Prometheus managed application in Kubernetes: - -1. Find the name of the Prometheus pod in the user interface of your Kubernetes - provider, such as GKE, or by running the following `kubectl` command in your - terminal: - - ```shell - kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server' - ``` - - The command should return a result like the following example, where - `prometheus-prometheus-server-55b4bd64c9-dpc6b` is the name of the Prometheus pod: - - ```plaintext - gitlab-managed-apps prometheus-prometheus-server-55b4bd64c9-dpc6b 2/2 Running 0 71d - ``` - -1. Run a `kubectl port-forward` command. In the following example, `9090` is the - Prometheus server's listening port: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 9090:9090 -n gitlab-managed-apps - ``` - - The `port-forward` command forwards all requests sent to your system's `9090` port - to the `9090` port of the Prometheus pod. If the `9090` port on your system is used - by another application, you can change the port number before the colon to your - desired port. For example, to forward port `8080` of your local system, change the - command to: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 8080:9090 -n gitlab-managed-apps - ``` - -1. Open `localhost:9090` in your browser to display the Prometheus user interface. - -#### Script access to Prometheus - -You can script the access to Prometheus, extracting the name of the pod automatically like this: - -```shell -POD_INFORMATION=$(kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server') -POD_NAME=$(echo $POD_INFORMATION | awk '{print $1;}') -kubectl port-forward $POD_NAME 9090:9090 -n gitlab-managed-apps -``` +GitLab can query an in-cluster Prometheus for your metrics. +See [Prometheus cluster integration](../../clusters/integrations.md#prometheus-cluster-integration) for details. ### Manual configuration of Prometheus @@ -223,12 +95,12 @@ to integrate with. ### Precedence with multiple Prometheus configurations Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) -and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you +and [cluster integration](#prometheus-cluster-integration) of Prometheus, you can use only one: - If you have enabled a [Prometheus manual configuration](#manual-configuration-of-prometheus) - and a [managed Prometheus on Kubernetes](#managed-prometheus-on-kubernetes), + and a [Prometheus cluster integration](#prometheus-cluster-integration), the manual configuration takes precedence and is used to run queries from [custom dashboards](../../../operations/metrics/dashboards/index.md) and [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index e14c1c0f6fd..1bafa4938af 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -33,7 +33,7 @@ integration services must be enabled. Prometheus needs to be deployed into the cluster and configured properly in order to gather Kubernetes metrics. GitLab supports two methods for doing so: -- GitLab [integrates with Kubernetes](../../clusters/index.md), and can [deploy Prometheus into a connected cluster](../prometheus.md#managed-prometheus-on-kubernetes). It is automatically configured to collect Kubernetes metrics. +- GitLab [integrates with Kubernetes](../../clusters/index.md), and can [query a Prometheus in a connected cluster](../../../clusters/integrations.md#prometheus-cluster-integration). The in-cluster Prometheus can be configured to automatically collect application metrics from your cluster. - To configure your own Prometheus server, you can follow the [Prometheus documentation](https://prometheus.io/docs/introduction/overview/). ## Specifying the Environment diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 8846aadd420..d1fe58390fe 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -27,28 +27,6 @@ NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors it](#about-managed-nginx-ingress-deployments). - -For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: - -- NGINX Ingress should be version 0.16.0 or above, with metrics enabled. -- NGINX Ingress should be annotated for Prometheus monitoring. -- Prometheus should be configured to monitor annotated pods. - -### About managed NGINX Ingress deployments - -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). - -NGINX is configured for Prometheus monitoring, by setting: - -- `enable-vts-status: "true"`, to export Prometheus metrics. -- `prometheus.io/scrape: "true"`, to enable automatic discovery. -- `prometheus.io/port: "10254"`, to specify the metrics port. - -When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. - -### Manually setting up NGINX Ingress for Prometheus monitoring - Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint starts running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: 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 4752fec976c..6bdd2c64dcf 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -27,28 +27,6 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using the GitLab [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors](#about-managed-nginx-ingress-deployments) it. - -For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: - -- NGINX Ingress should be version 0.9.0 or above, with metrics enabled. -- NGINX Ingress should be annotated for Prometheus monitoring. -- Prometheus should be configured to monitor annotated pods. - -### About managed NGINX Ingress deployments - -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). - -NGINX is configured for Prometheus monitoring, by setting: - -- `enable-vts-status: "true"`, to export Prometheus metrics. -- `prometheus.io/scrape: "true"`, to enable automatic discovery. -- `prometheus.io/port: "10254"`, to specify the metrics port. - -When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. - -### Manually setting up NGINX Ingress for Prometheus monitoring - Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint begins running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 93ce74eb735..37df48c75f8 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -1,67 +1,9 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../admin_area/settings/project_integration_management.md' +remove_date: '2021-09-09' --- -# Service templates **(FREE)** +This document was moved to [another location](../../admin_area/settings/project_integration_management.md). -WARNING: -Service templates are [deprecated and scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) -in GitLab 14.0. Use [project integration management](#central-administration-of-project-integrations) instead. - -Using a service template, GitLab administrators can: - -- Provide default values for configuring integrations when creating new projects. -- Bulk configure all existing projects in one step. - -When you enable a service template: - -- The defaults are applied to **all** existing projects that either: - - Don't already have the integration enabled. - - Don't have custom values stored for already enabled integrations. -- Values are populated on each project's configuration page for the applicable - integration. -- Settings are stored at the project level. - -If you disable the template: - -- GitLab default values again become the default values for integrations on - new projects. -- Projects previously configured using the template continue to use those settings. - -If you change the template, the revised values are applied to new projects. This feature -does not provide central administration of integration settings. - -## Central administration of project integrations - -A new set of features is being introduced in GitLab to provide more control over -how integrations are configured at the instance, group, and project level. For -more information, read more about: - -- [Setting up project integration management](../../admin_area/settings/project_integration_management.md) (introduced in GitLab 13.3) -- [Our plans for managing integrations](https://gitlab.com/groups/gitlab-org/-/epics/2137). - -## Enable a service template - -Navigate to the **Admin Area > Service Templates** and choose the service -template you wish to create. - -Recommendation: - -- Test the settings on some projects individually before enabling a template. -- Copy the working settings from a project to the template. - -There is no "Test settings" option when enabling templates. If the settings do not work, -these incorrect settings are applied to all existing projects that do not already have -the integration configured. Fixing the integration then needs to be done project-by-project. - -## Service for external issue trackers - -The following image shows an example service template for Redmine. - -![Redmine service template](img/services_templates_redmine_example.png) - -For each project, you still need to configure the issue tracking -URLs by replacing `:issues_tracker_id` in the above screenshot with the ID used -by your external issue tracker. + + diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index b2bf8e5731a..05515c58161 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -27,7 +27,8 @@ notifications: 1. Navigate to: - **Settings > Integrations** in a project to enable the integration at the project level. - **Settings > Integrations** in a group to enable the integration at the group level. - - **Settings > Integrations** in the Admin Area (**{admin}**) to enable an instance-level integration. + - On the top bar, select **Menu >** **{admin}** **Admin**. Then, in the left sidebar, + select **Settings > Integrations** to enable an instance-level integration. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Webex Teams. diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index d74a2bec1f6..406b1e9ba6b 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -34,8 +34,10 @@ Webhooks are available: - Per project, at a project's **Settings > Webhooks** menu. **(FREE)** - Additionally per group, at a group's **Settings > Webhooks** menu. **(PREMIUM)** -NOTE: -On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. +GitLab.com enforces various [webhook limits](../../../user/gitlab_com/index.md#webhooks), including: + +- The maximum number of webhooks and their size, both per project, and per group. +- The number of webhook calls per minute. ## Possible uses for webhooks @@ -308,8 +310,10 @@ X-Gitlab-Event: Issue Hook "duplicated_to_id": null, "time_estimate": 0, "total_time_spent": 0, + "time_change": 0, "human_total_time_spent": null, "human_time_estimate": null, + "human_time_change": null, "weight": null, "iid": 23, "url": "http://example.com/diaspora/issues/23", @@ -1161,6 +1165,7 @@ X-Gitlab-Event: Pipeline Hook "id": 380987, "description": "shared-runners-manager-6.gitlab.com", "active": true, + "runner_type": "instance_type", "is_shared": true, "tags": [ "linux", @@ -1196,7 +1201,8 @@ X-Gitlab-Event: Pipeline Hook "id":380987, "description":"shared-runners-manager-6.gitlab.com", "active":true, - "is_shared":true, + "runner_type": "instance_type", + "is_shared": true, "tags": [ "linux", "docker" @@ -1230,6 +1236,7 @@ X-Gitlab-Event: Pipeline Hook "id": 380987, "description": "shared-runners-manager-6.gitlab.com", "active": true, + "runner_type": "instance_type", "is_shared": true, "tags": [ "linux", @@ -1333,6 +1340,7 @@ X-Gitlab-Event: Job Hook }, "runner": { "active": true, + "runner_type": "project_type", "is_shared": false, "id": 380987, "description": "shared-runners-manager-6.gitlab.com", diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index e1b6956f873..8f71d469e34 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -34,11 +34,11 @@ boards in the same project. Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) | -|------------------|--------------------------------|------------------------------|---------------------------|----------------| -| Free | Multiple | 1 | No | No | -| Premium | Multiple | Multiple | Yes | Yes | -| Ultimate | Multiple | Multiple | Yes | Yes | +| Tier | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) | +| -------- | ------------------------------ | --------------------------------------------------- | ------------------------------------------------------- | --------------------------------- | +| Free | Multiple | 1 | No | No | +| Premium | Multiple | Multiple | Yes | Yes | +| Ultimate | Multiple | Multiple | Yes | Yes | To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below. @@ -203,7 +203,7 @@ When visiting a board, issues appear ordered in any list. You're able to change that order by dragging the issues. The changed order is saved, so that anybody who visits the same board later sees the reordering, with some exceptions. -The first time a given issue appears in any board (that is, the first time a user +The first time an issue appears in any board (that is, the first time a user loads a board containing that issue), it is ordered in relation to other issues in that list. The order is done according to [label priority](labels.md#label-priority). @@ -222,6 +222,28 @@ This ordering also affects [issue lists](issues/sorting_issue_lists.md). Changing the order in an issue board changes the ordering in an issue list, and vice versa. +### GraphQL-based issue boards + + + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. +> - [Deployed behind a feature flag](../feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-issue-boards). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +The work-in-progress GraphQL-based boards come with these features: + +- [Edit more issue attributes](#edit-an-issue) +- [View blocked issues](#blocked-issues) + +The GraphQL-based Issue Board is a work in progress. +Learn more about the known issues in [epic 5596](https://gitlab.com/groups/gitlab-org/-/epics/5596). + ## GitLab Enterprise features for issue boards GitLab issue boards are available on the GitLab Free tier, but some @@ -269,40 +291,12 @@ especially in combination with [assignee lists](#assignee-lists). ![issue board summed weights](img/issue_board_summed_weights_v13_6.png) -### Group issue boards **(PREMIUM)** +### Group issue boards Accessible at the group navigation level, a group issue board offers the same features as a project-level board. -It can display issues from all projects in that -group and its descendant subgroups. Similarly, you can only filter by group labels for these -boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only -group-level objects are available. - -#### GraphQL-based sidebar for group issue boards **(PREMIUM)** - - - - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285074) in GitLab 13.9. -> - It's [deployed behind a feature flag](../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-graphql-based-sidebar-for-group-issue-boards). **(PREMIUM SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -The work-in-progress GraphQL-based sidebar for group issue boards brings better performance and the -ability to edit issue titles in the issue sidebar. - -To **edit an issue's title** in the issue sidebar: - -1. In a group issue board, select the issue card. The issue sidebar opens on the right. -1. Next to the issue's title, select **Edit**. +It can display issues from all projects that fall under the group and its descendant subgroups. -This is work in progress as of GitLab 13.9. Learn more about the known issues in -[MR 51480](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51480). - - +Users on GitLab Free can use a single group issue board. ### Assignee lists **(PREMIUM)** @@ -318,7 +312,7 @@ assignee list: 1. Search and select the user you want to add as an assignee. Now that the assignee list is added, you can assign or unassign issues to that user -by [dragging issues](#drag-issues-between-lists) to and from an assignee list. +by [moving issues](#move-issues-and-lists) to and from an assignee list. To remove an assignee list, just as with a label list, click the trash icon. ![Assignee lists](img/issue_board_assignee_lists_v13_6.png) @@ -334,7 +328,7 @@ milestone, giving you more freedom and visibility on the issue board. To add a m 1. Select the **Milestone** tab. 1. Search and click the milestone. -Like the assignee lists, you're able to [drag issues](#drag-issues-between-lists) +Like the assignee lists, you're able to [drag issues](#move-issues-and-lists) to and from a milestone list to manipulate the milestone of the dragged issues. As in other list types, click the trash icon to remove a list. @@ -361,7 +355,7 @@ iteration. To add an iteration list: 1. In the dropdown, select an iteration. 1. Select **Add to board**. -Like the milestone lists, you're able to [drag issues](#drag-issues-between-lists) +Like the milestone lists, you're able to [drag issues](#move-issues-and-lists) to and from a iteration list to manipulate the iteration of the dragged issues. ![Iteration lists](img/issue_board_iteration_lists_v13_10.png) @@ -399,7 +393,7 @@ appears on the right. There you can see and edit the issue's: - Weight - Notifications setting -You can also [drag issues](#drag-issues-between-lists) to change their position and epic assignment: +You can also [drag issues](#move-issues-and-lists) to change their position and epic assignment: - To reorder an issue, drag it to the new position within a list. - To assign an issue to another epic, drag it to the epic's horizontal lane. @@ -442,27 +436,49 @@ status. When you hover over the blocked icon (**{issue-block}**), a detailed information popover is displayed. -To enable this in group issue boards, enable the [GraphQL-based sidebar](#graphql-based-sidebar-for-group-issue-boards). -The feature is enabled by default when you use group issue boards with epic swimlanes. +This feature is only supported when using the [GraphQL-based boards](#graphql-based-issue-boards). The feature is enabled by default regardless when you use group issue boards in epic swimlanes mode. ![Blocked issues](img/issue_boards_blocked_icon_v13_10.png) ## Actions you can take on an issue board +- [Edit an issue](#edit-an-issue). - [Create a new list](#create-a-new-list). - [Remove an existing list](#remove-a-list). - [Remove an issue from a list](#remove-an-issue-from-a-list). - [Filter issues](#filter-issues) that appear across your issue board. - [Create workflows](#create-workflows). -- [Drag issues between lists](#drag-issues-between-lists). +- [Move issues and lists](#move-issues-and-lists). - [Multi-select issue cards](#multi-select-issue-cards). - Drag and reorder the lists. - Change issue labels (by dragging an issue between lists). -- Close an issue (by dragging it to the **Done** list). +- Close an issue (by dragging it to the **Closed** list). If you're not able to do some of the things above, make sure you have the right [permissions](#permissions). +### Edit an issue + +You can edit an issue without leaving the board view. +To open the right sidebar, select an issue card (not its title). + +You can edit the following issue attributes in the right sidebar: + +- Assignees +- [Epic](../group/epics/index.md) +- Milestone +- Time tracking value (view only) +- Due date +- Labels +- [Weight](issues/issue_weight.md) +- Notifications setting + +When you use [GraphQL-based boards](#graphql-based-issue-boards), you can also edit the following issue attributes: + +- Title +- [Iteration](../group/iterations/index.md) +- Confidentiality + ### Create a new list Create a new list by clicking the **Add list** dropdown button in the upper right corner of the issue board. @@ -480,12 +496,12 @@ You can now choose it to create a list. ### Remove a list Removing a list doesn't have any effect on issues and labels, as it's just the -list view that's removed. You can always restore it later if you need. +list view that's removed. You can always create it again later if you need. To remove a list from an issue board: -1. Select the **List settings** icon (**{settings}**) on the top of the list you want to remove. The - list settings sidebar opens on the right. +1. On the top of the list you want to remove, select the **List settings** icon (**{settings}**). + The list settings sidebar opens on the right. 1. Select **Remove list**. A confirmation dialog appears. 1. Select **OK**. @@ -516,9 +532,8 @@ The steps depend on the scope of the list: ### Filter issues -You should be able to use the filters on top of your issue board to show only -the results you want. It's similar to the filtering used in the issue tracker, -as the metadata from the issues and labels is re-used in the issue board. +You can use the filters on top of your issue board to show only +the results you want. It's similar to the filtering used in the [issue tracker](issues/index.md). You can filter by the following: @@ -532,6 +547,16 @@ You can filter by the following: - Release - Weight +#### Filtering issues in a group board + +When [filtering issues](#filter-issues) in a **group** board, keep this behavior in mind: + +- Milestones: you can filter by the milestones belonging to the group and its descendant groups. +- Labels: you can only filter by the labels belonging to the group but not its descendant groups. + +When you edit issues individually using the right sidebar, you can additionally select the +milestones and labels from the **project** that the issue is from. + ### Create workflows By reordering your lists, you can create workflows. As lists in issue boards are @@ -570,20 +595,45 @@ to another list, the label changes and a system note is recorded. ![issue board system notes](img/issue_board_system_notes_v13_6.png) -### Drag issues between lists +### Move issues and lists + +You can move issues and lists by dragging them. + +Prerequisites: -When dragging issues between lists, different behavior occurs depending on the source list and the target list. +- A minimum of [Reporter](../permissions.md#project-members-permissions) access to a project in GitLab. -| | To Open | To Closed | To label `B` list | To assignee `Bob` list | -| ------------------------------ | ------------------ | ------------ | ---------------------------- | ------------------------------------- | -| **From Open** | - | Issue closed | `B` added | `Bob` assigned | -| **From Closed** | Issue reopened | - | Issue reopened
`B` added | Issue reopened
`Bob` assigned | -| **From label `A` list** | `A` removed | Issue closed | `A` removed
`B` added | `Bob` assigned | -| **From assignee `Alice` list** | `Alice` unassigned | Issue closed | `B` added | `Alice` unassigned
`Bob` assigned | +To move an issue, select the issue card and drag it to another position in its current list or +into a different list. Learn about possible effects in [Dragging issues between lists](#dragging-issues-between-lists). + +To move a list, select its top bar, and drag it horizontally. +You can't move the **Open** and **Closed** lists, but you can hide them when editing an issue board. + +#### Dragging issues between lists + +To move an issue to another list, select the issue card and drag it onto that list. + +When you drag issues between lists, the result is different depending on the source list +and the target list. + +| | To Open | To Closed | To label B list | To assignee Bob list | +| ---------------------------- | -------------- | ----------- | ------------------------------ | ----------------------------- | +| **From Open** | - | Close issue | Add label B | Assign Bob | +| **From Closed** | Reopen issue | - | Reopen issue and add label B | Reopen issue and assign Bob | +| **From label A list** | Remove label A | Close issue | Remove label A and add label B | Assign Bob | +| **From assignee Alice list** | Unassign Alice | Close issue | Add label B | Unassign Alice and assign Bob | ### Multi-select issue cards -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18954) in GitLab 12.4. +> - [Placed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61955) behind a [feature flag](../feature_flags.md), disabled by default in GitLab 14.0. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-multi-selecting-issue-cards). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. You can select multiple issue cards, then drag the group to another position within the list, or to another list. This makes it faster to reorder many issues at once. @@ -626,10 +676,14 @@ A few things to remember: by default. If you have more than 20 issues, start scrolling down and the next 20 appear. -## Enable or disable GraphQL-based sidebar for group issue boards **(PREMIUM SELF)** +### Enable or disable GraphQL-based issue boards **(FREE SELF)** -GraphQL-based sidebar for group issue boards is under development and not ready for production use. -It is deployed behind a feature flag that is **disabled by default**. +NOTE: +When enabling GraphQL-based issue boards, you must also enable the +[new add list form](#enable-or-disable-new-add-list-form). + +GraphQL-based issue boards is not ready for production use. +It is deployed behind a feature flag that is **disabled by default** as of GitLab 13.12. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. @@ -685,3 +739,22 @@ To disable it: ```ruby Feature.disable(:iteration_board_lists) ``` + +### Enable or disable multi-selecting issue cards **(FREE SELF)** + +Multi-selecting issue cards 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(:board_multi_select) +``` + +To disable it: + +```ruby +Feature.disable(:board_multi_select) +``` diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 25357a1db0b..ed15d7a2e63 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -77,11 +77,11 @@ least [Reporter access](../../permissions.md#project-members-permissions). Howev confidential issues, but can only view the ones that they created themselves. Confidential issues are also hidden in search results for unprivileged users. -For example, here's what a user with Maintainer and Guest access sees in the -project's search results respectively. +For example, here's what a user with the [Maintainer role](../../permissions.md) and Guest access +sees in the project's search results respectively. -| Maintainer access | Guest access | -| :-----------: | :----------: | +| Maintainer role | Guest access | +|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| | ![Confidential issues search by maintainer](img/confidential_issues_search_master.png) | ![Confidential issues search by guest](img/confidential_issues_search_guest.png) | ## Merge Requests for Confidential Issues diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 5c95665230a..29adf396d4d 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -4,41 +4,46 @@ group: unassigned info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Export Issues to CSV +# Export issues to CSV **(FREE)** > Moved to GitLab Free in 12.10. -Issues can be exported as CSV from GitLab and are sent to your default notification email as an attachment. +You can export issues as CSV files from GitLab, which are sent to your default +notification email address as an attachment. -## Overview +**Export Issues to CSV** enables you and your team to export all the data +collected from issues into a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) +file, which stores tabular data in plain text. -**Export Issues to CSV** enables you and your team to export all the data collected from issues into -a **[comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values)** (CSV) file, -which stores tabular data in plain text. +> _CSVs are a handy way of getting data from one program to another where one +program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) -> _CSVs are a handy way of getting data from one program to another where one program cannot read the other ones normal output._ [Ref](https://www.quora.com/What-is-a-CSV-file-and-its-uses) +CSV files can be used with any plotter or spreadsheet-based program, such as +Microsoft Excel, Open Office Calc, , +or Google Sheets. -CSV files can be used with any plotter or spreadsheet-based program, such as Microsoft Excel, -Open Office Calc, or Google Spreadsheets. +Here are some of the uses of exporting issues as CSV files: -## Use cases - -Among numerous use cases for exporting issues for CSV, we can name a few: - -- Make a snapshot of issues for offline analysis or to communicate with other teams who may not be in GitLab -- Create diagrams, graphs, and charts from the CSV data -- Present the data in any other format for auditing or sharing reasons -- Import the issues elsewhere to a system outside of GitLab -- Long-term issues' data analysis with multiple snapshots created along the time -- Use the long-term data to gather relevant feedback given in the issues, and improve your product based on real metrics +- Make a snapshot of issues for offline analysis or to communicate with other + teams who may not be in GitLab. +- Create diagrams, graphs, and charts from the CSV data. +- Present the data in any other format for auditing or sharing reasons. +- Import the issues elsewhere to a system outside of GitLab. +- Long-term issues' data analysis with multiple snapshots created along the + time. +- Use the long-term data to gather relevant feedback given in the issues, and + improve your product based on real metrics. ## Choosing which issues to include -After selecting a project, from the issues page you can narrow down which issues to export using the search bar, along with the All/Open/Closed tabs. All issues returned are exported, including those not shown on the first page. +After selecting a project, from the issues page you can narrow down which +issues to export using the search bar, along with the All/Open/Closed tabs. All +issues returned are exported, including those not shown on the first page. ![CSV export button](img/csv_export_button_v12_9.png) -GitLab asks you to confirm the number of issues and email address for the export, after which the email is prepared. +GitLab asks you to confirm the number of issues and email address for the +export, after which the email is prepared. ![CSV export modal dialog](img/csv_export_modal.png) @@ -48,33 +53,41 @@ Exported issues are always sorted by `Issue ID`. ## Format -Data is encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: - -| Column | Description | -|---------|-------------| -| Issue ID | Issue `iid` | -| URL | A link to the issue on GitLab | -| Title | Issue `title` | -| State | `Open` or `Closed` | -| Description | Issue `description` | -| Author | Full name of the issue author | -| Author Username | Username of the author, with the `@` symbol omitted | -| Assignee | Full name of the issue assignee | +Data is encoded with a comma as the column delimiter, with `"` used to quote +fields if needed, and newlines to separate rows. The first row contains the +headers, which are listed in the following table along with a description of +the values: + +| Column | Description | +|-------------------|-------------| +| Issue ID | Issue `iid` | +| URL | A link to the issue on GitLab | +| Title | Issue `title` | +| State | `Open` or `Closed` | +| Description | Issue `description` | +| Author | Full name of the issue author | +| Author Username | Username of the author, with the `@` symbol omitted | +| Assignee | Full name of the issue assignee | | Assignee Username | Username of the author, with the `@` symbol omitted | -| Confidential | `Yes` or `No` | -| Locked | `Yes` or `No` | -| Due Date | Formatted as `YYYY-MM-DD` | -| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | -| Milestone | Title of the issue milestone | -| Weight | Issue weight | -| Labels | Title of any labels joined with a `,` | -| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | -| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | -| Epic ID | ID of the parent epic **(ULTIMATE)**, introduced in 12.7 | -| Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Confidential | `Yes` or `No` | +| Locked | `Yes` or `No` | +| Due Date | Formatted as `YYYY-MM-DD` | +| Created At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Updated At (UTC) | Formatted as `YYYY-MM-DD HH:MM:SS` | +| Milestone | Title of the issue milestone | +| Weight | Issue weight | +| Labels | Title of any labels joined with a `,` | +| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | +| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | +| Epic ID | ID of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | ## Limitations - Export Issues to CSV is not available at the Group's Issues List. -- As the issues are sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 15MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. +- Issues are sent as an email attachment, with a 15 MB export limit to ensure + successful delivery across a range of email providers. If you reach the limit, + we suggest narrowing the search before export, perhaps by exporting open and + closed issues separately. +- CSV files are plain text files. This means that the exported CSV file doesn't + contain any issue attachments. diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index de7a36a4886..02a4f6a4384 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -4,7 +4,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Importing issues from CSV +# Importing issues from CSV **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23532) in GitLab 11.7. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 2a003e68a73..e0eb35d1e49 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -48,7 +48,7 @@ If the requirements are not met, the **Designs** tab displays a message to the u Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff`, `ico`, `webp`, or `svg`. -Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned for a future release. +Support for [PDF](https://gitlab.com/gitlab-org/gitlab/-/issues/32811) is planned for a future release. ## Limitations @@ -219,11 +219,14 @@ There are two ways to resolve/unresolve a Design thread: ![Resolve checkbox](img/resolve_design-discussion_checkbox_v13_1.png) +Resolving a discussion thread also marks any pending to-do items related to notes +inside the thread as done. This is applicable only for to-do items owned by the user triggering the action. + Note that your resolved comment pins disappear from the Design to free up space for new discussions. However, if you need to revisit or find a resolved discussion, all of your resolved threads are available in the **Resolved Comment** area at the bottom of the right sidebar. -## Add to dos for designs +## Add to-do items for designs > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index a82823947dc..5b8dd617ab9 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -4,13 +4,9 @@ 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 --- -# Due dates +# Due dates **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3614) in GitLab 8.7. - -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -Due dates can be used in issues to keep track of deadlines and make sure features are +Due dates can be used in [issues](index.md) to keep track of deadlines and make sure features are shipped on time. Users need at least [Reporter permissions](../../permissions.md) to be able to edit the due date. All users with permission to view the issue can view the due date. @@ -24,11 +20,11 @@ the user setting the due date. ![Create a due date](img/due_dates_create.png) -You can also set a due date via the issue sidebar. Expand the -sidebar and click **Edit** to pick a due date or remove the existing one. +You can also set a due date by using the issue sidebar. Expand the +sidebar and select **Edit** to pick a due date or remove the existing one. Changes are saved immediately. -![Edit a due date via the sidebar](img/due_dates_edit_sidebar.png) +![Edit a due date with the sidebar](img/due_dates_edit_sidebar.png) The last way to set a due date is by using [quick actions](../quick_actions.md), directly in an issue's description or comment: @@ -52,9 +48,9 @@ of the issue. Like the due date, the "day before the due date" is determined by server's timezone. Issues with due dates can also be exported as an iCalendar feed. The URL of the -feed can be added to calendar applications. The feed is accessible by clicking -on the **Subscribe to calendar** button on the following pages: +feed can be added to calendar applications. The feed is accessible by selecting +the **Subscribe to calendar** button on the following pages: -- on the **Assigned Issues** page that is linked on the right-hand side of the GitLab header -- on the **Project Issues** page -- on the **Group Issues** page +- The **Assigned Issues** page linked on the right side of the GitLab header +- The **Project Issues** page +- The **Group Issues** page diff --git a/doc/user/project/issues/img/issue_type_change_v13_12.png b/doc/user/project/issues/img/issue_type_change_v13_12.png new file mode 100644 index 00000000000..3b4864ffbbb Binary files /dev/null and b/doc/user/project/issues/img/issue_type_change_v13_12.png differ diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 3af6c528db9..13f5beadb16 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -221,7 +221,7 @@ merge request is also listed here. You can award emojis to issues. You can select the "thumbs up" and "thumbs down", or the gray "smiley-face" to choose from the list of available -[GitLab Flavored Markdown Emoji](../../markdown.md#emoji). +[GitLab Flavored Markdown Emoji](../../markdown.md#emojis). NOTE: Posting "+1" as a comment in a thread spams all subscribed participants of that issue, diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 9e8a75743a7..35573518626 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -315,10 +315,15 @@ issues are still displayed, but are not closed automatically. ![disable issue auto close - settings](img/disable_issue_auto_close.png) +The automatic issue closing is also disabled in a project if the project has the issue tracker +disabled. If you want to enable automatic issue closing, make sure to +[enable GitLab Issues](../settings/index.md#sharing-and-permissions). + This only applies to issues affected by new merge requests or commits. Already -closed issues remain as-is. Disabling automatic issue closing only affects merge -requests *in* the project and does not prevent other projects from closing it -via cross-project issues. +closed issues remain as-is. +If issue tracking is enabled, disabling automatic issue closing only applies to merge requests +attempting to automatically close issues within the same project. +Merge requests in other projects can still close another project's issues. #### Customizing the issue closing pattern **(FREE SELF)** @@ -326,9 +331,20 @@ In order to change the default issue closing pattern, GitLab administrators must [`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) of your installation. +## Change the issue type + +Users with [developer permission](../../permissions.md) +can change an issue's type. To do this, edit the issue and select an issue type from the +**Issue type** selector menu: + +- [Issue](index.md) +- [Incident](../../../operations/incident_management/index.md) + +![Change the issue type](img/issue_type_change_v13_12.png) + ## Deleting issues -Users with [project owner permission](../../permissions.md) can delete an issue by +Users with the [Owner role](../../permissions.md) can delete an issue by editing it and selecting **Delete issue**. ![delete issue - button](img/delete_issue_v13_11.png) diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 0cb5b5d993e..e7adc045e98 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -282,4 +282,4 @@ To resolve the duplication, [in GitLab 13.2](https://gitlab.com/gitlab-org/gitla and later, some duplicate labels have `_duplicate` appended to their titles. You can safely change these labels' titles if you prefer. -For details of the original problem, see [issue 30390](https://gitlab.com/gitlab-org/gitlab/issues/30390). +For details of the original problem, see [issue 30390](https://gitlab.com/gitlab-org/gitlab/-/issues/30390). diff --git a/doc/user/project/members/img/access_requests_management_v13_9.png b/doc/user/project/members/img/access_requests_management_v13_9.png deleted file mode 100644 index b7883e9d134..00000000000 Binary files a/doc/user/project/members/img/access_requests_management_v13_9.png and /dev/null differ diff --git a/doc/user/project/members/img/add_user_email_accept_v13_9.png b/doc/user/project/members/img/add_user_email_accept_v13_9.png deleted file mode 100644 index a6b303e05ca..00000000000 Binary files a/doc/user/project/members/img/add_user_email_accept_v13_9.png and /dev/null differ diff --git a/doc/user/project/members/img/add_user_email_ready_v13_8.png b/doc/user/project/members/img/add_user_email_ready_v13_8.png deleted file mode 100644 index a610b46a176..00000000000 Binary files a/doc/user/project/members/img/add_user_email_ready_v13_8.png and /dev/null differ diff --git a/doc/user/project/members/img/add_user_email_search_v13_8.png b/doc/user/project/members/img/add_user_email_search_v13_8.png deleted file mode 100644 index 934cf19bd3d..00000000000 Binary files a/doc/user/project/members/img/add_user_email_search_v13_8.png and /dev/null differ diff --git a/doc/user/project/members/img/withdraw_access_request_button.png b/doc/user/project/members/img/withdraw_access_request_button.png deleted file mode 100644 index e5a8fe0b356..00000000000 Binary files a/doc/user/project/members/img/withdraw_access_request_button.png and /dev/null differ diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 7dc1a9c612f..ab33ff0f6d8 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -1,10 +1,10 @@ --- -stage: none -group: unassigned +stage: Manage +group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Members of a project +# Members of a project **(FREE)** Members are the users and groups who have access to your project. @@ -17,12 +17,13 @@ to perform actions. Prerequisite: -- You must have maintainer or owner [permissions](../../permissions.md). +- You must have the [Maintainer or Owner role](../../permissions.md). To add a user to a project: 1. Go to your project and select **Members**. -1. On the **Invite member** tab, under **GitLab member of Email address**, type the username or email address. +1. On the **Invite member** tab, under **GitLab member or Email address**, type the username or email address. + In GitLab 13.11 and later, you can [replace this form with a modal window](#add-a-member-modal-window). 1. Select a [role](../../permissions.md). 1. Optional. Choose an expiration date. On that date, the user can no longer access the project. 1. Select **Invite**. @@ -30,15 +31,24 @@ To add a user to a project: If the user has a GitLab account, they are added to the members list. If you used an email address, the user receives an email. +If the invitation is not accepted, GitLab sends reminder emails two, +five, and ten days later. Unaccepted invites are automatically +deleted after 90 days. + +If the user does not have a GitLab account, they are prompted to create an account +using the email address the invitation was sent to. + ## Add groups to a project -When you assign a group to a project, each user in the group gets access to the project, -based on the role they're assigned in the group. However, the user's access is also -limited by the maximum role you choose when you invite the group. +When you add a group to a project, each user in the group gets access to the project. +Each user's access is based on: + +- The role they're assigned in the group. +- The maximum role you choose when you invite the group. Prerequisite: -- You must have maintainer or owner [permissions](../../permissions.md). +- You must have the [Maintainer or Owner role](../../permissions.md). To add groups to a project: @@ -61,7 +71,7 @@ retain the same permissions as the project you import them from. Prerequisite: -- You must have maintainer or owner [permissions](../../permissions.md). +- You must have the [Maintainer or Owner role](../../permissions.md). To import users: @@ -74,20 +84,39 @@ A success message is displayed and the new members are now displayed in the list ## Inherited membership -When your project belongs to a group, group members inherit the membership and permission -level for the project from the group. +When your project belongs to a group, group members inherit their role +from the group. ![Project members page](img/project_members_v13_9.png) -From the image above, we can deduce the following things: +In this example: + +- Three members have access to the project. +- **User 0** is a Reporter and has inherited their role from the **demo** group, + which contains the project. +- **User 1** belongs directly to the project. In the **Source** column, they are listed + as a **Direct member**. +- **Administrator** is the [Owner](../../permissions.md) and member of all groups. + They have inherited their role from the **demo** group. + +## Remove a member from a project + +If a user is a direct member of a project, you can remove them. +If membership is inherited from a parent group, then the member can be removed only from the parent +group itself. -- There are 3 members that have access to the project. -- User0 is a Reporter and has inherited their permissions from group `demo` - which contains current project. -- User1 is shown as a **Direct member** in the **Source** column, therefore they belong directly - to the project we're inspecting. -- Administrator is the Owner and member of **all** groups and for that reason, - there is an indication of an ancestor group and inherited Owner permissions. +Prerequisite: + +- You must have the [Owner role](../../permissions.md). +- Optional. Unassign the member from all issues and merge requests that + are assigned to them. + +To remove a member from a project: + +1. Go to your project and select **Members**. +1. Next to the project member you want to remove, select **Remove member** **{remove}**. +1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. +1. Select **Remove member**. ## Filter and sort members @@ -95,22 +124,21 @@ From the image above, we can deduce the following things: > - [Improved](https://gitlab.com/groups/gitlab-org/-/epics/4901) in GitLab 13.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299954) in GitLab 13.10. -The following sections illustrate how you can filter and sort members in a project. To view these options, -navigate to your desired project, go to **Members**, and include the noted search terms. - -### Membership filter - -By default, inherited and direct members are displayed. The membership filter can be used to display only inherited or only direct members. +You can filter and sort members in a project. -#### Display inherited members +### Display inherited members -To display inherited members, include `Membership` `=` `Inherited` in the search text box. +1. Go to your project and select **Members**. +1. In the **Filter members** box, select `Membership` `=` `Inherited`. +1. Press Enter. ![Project members filter inherited](img/project_members_filter_inherited_v13_9.png) -#### Display direct members +### Display direct members -To display direct members, include `Membership` `=` `Direct` in the search text box. +1. Go to your project and select **Members**. +1. In the **Filter members** box, select `Membership` `=` `Direct`. +1. Press Enter. ![Project members filter direct](img/project_members_filter_direct_v13_9.png) @@ -126,36 +154,41 @@ You can sort members by **Account**, **Access granted**, **Max role**, or **Last ![Project members sort](img/project_members_sort_v13_9.png) -## Invite people using their e-mail address +## Request access to a project -NOTE: -In GitLab 13.11, you can [replace this form with a modal window](#add-a-member-modal-window). +GitLab users can request to become a member of a project. -If a user you want to give access to doesn't have an account on your GitLab -instance, you can invite them just by typing their e-mail address in the -user search field. +1. Go to the project you'd like to be a member of. +1. By the project name, select **Request Access**. -![Invite user by mail](img/add_user_email_search_v13_8.png) +![Request access button](img/request_access_button.png) -As you can imagine, you can mix inviting multiple people and adding existing -GitLab users to the project. +An email is sent to the most recently active project maintainers. +Up to ten project maintainers are notified. +Any project maintainer can approve or decline the request. -![Invite user by mail ready to submit](img/add_user_email_ready_v13_8.png) +If a project does not have any maintainers, the notification is sent to the +most recently active owners of the project's group. + +If you change your mind before your request is approved, select +**Withdraw Access Request**. -Once done, hit **Add users to project** and watch that there is a new member -with the e-mail address we used above. From there on, you can resend the -invitation, change their access level, or even delete them. +## Prevent users from requesting access to a project -![Invite user members list](img/add_user_email_accept_v13_9.png) +You can prevent users from requesting access to a project. + +Prerequisite: -While unaccepted, the system automatically sends reminder emails on the second, fifth, -and tenth day after the invitation was initially sent. +- You must be the project owner. -After the user accepts the invitation, they are prompted to create a new -GitLab account using the same e-mail address the invitation was sent to. +1. Go to the project and select **Settings > General**. +1. Expand the **Visibility, project features, permissions** section. +1. Under **Project visibility**, select **Users can request access**. +1. Select **Save changes**. -NOTE: -Unaccepted invites are automatically deleted after 90 days. +## Share a project with a group + +Instead of adding users one by one, you can [share a project with an entire group](share_project_with_groups.md). ### Add a member modal window @@ -172,10 +205,10 @@ This feature might not be available to you. Check the **version history** note a In GitLab 13.11, you can optionally replace the form to add a member with a modal window. To add a member after enabling this feature: -1. Go to your project's page. -1. In the left sidebar, go to **Members**, and then select **Invite members**. -1. Enter an email address, and select a role permission for this user. -1. (Optional) Select an **Access expiration date**. +1. Go to your project and select **Members**. +1. Select **Invite members**. +1. Enter an email address and select a role. +1. Optional. Select an **Access expiration date**. 1. Select **Invite**. ### Enable or disable modal window **(FREE SELF)** @@ -196,65 +229,3 @@ To disable it: ```ruby Feature.disable(:invite_members_group_modal) ``` - -## Project membership and requesting access - -Project owners can : - -- Allow non-members to request access to the project. -- Prevent non-members from requesting access. - -To configure this, go to the project settings and click on **Allow users to request access**. - -GitLab users can request to become a member of a project. Go to the project you'd -like to be a member of and click the **Request Access** button on the right -side of your screen. - -![Request access button](img/request_access_button.png) - -After access is requested: - -- Up to ten project maintainers are notified of the request via email. - Email is sent to the most recently active project maintainers. -- Any project maintainer can approve or decline the request on the members page. - -NOTE: -If a project does not have any maintainers, the notification is sent to the -most recently active owners of the project's group. - -![Manage access requests](img/access_requests_management_v13_9.png) - -If you change your mind before your request is approved, just click the -**Withdraw Access Request** button. - -![Withdraw access request button](img/withdraw_access_request_button.png) - -## Share project with group - -Alternatively, you can [share a project with an entire group](share_project_with_groups.md) instead of adding users one by one. - -## Remove a member from the project - -Only users with permissions of [Owner](../../permissions.md#group-members-permissions) can manage -project members. - -You can remove a user from the project if the given member has a direct membership in the project. -If membership is inherited from a parent group, then the member can be removed only from the parent -group itself. - -When removing a member, you can decide whether to unassign the user from all issues and merge -requests they are currently assigned or leave the assignments as they are. - -- **Unassigning the removed member** from all issues and merge requests might be helpful when a user - is leaving a private project and you wish to revoke their access to any issues and merge requests - they are assigned. -- **Keeping the issues and merge requests assigned** might be helpful for projects that accept public - contributions where a user doesn't have to be a member to be able to contribute to issues and - merge requests. - -To remove a member from a project: - -1. Go to your project and select **Members**. -1. Next to the project member you want to remove, select **Remove member** **{remove}**. -1. Optional. In the confirmation box, select the **Also unassign this user from related issues and merge requests** checkbox. -1. Select **Remove member**. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md index 085e4db0b94..caef5ef60b7 100644 --- a/doc/user/project/members/share_project_with_groups.md +++ b/doc/user/project/members/share_project_with_groups.md @@ -60,7 +60,7 @@ To share a project after enabling this feature: 1. Go to your project's page. 1. In the left sidebar, go to **Members**, and then select **Invite a group**. -1. Select a group, and select a **Max access level**. +1. Select a group, and select a **Max role**. 1. (Optional) Select an **Access expiration date**. 1. Select **Invite**. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 09770bd447d..76aff18b00d 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Accessibility Testing +# Accessibility testing **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. @@ -17,11 +17,11 @@ impact of pending code changes. GitLab uses [pa11y](https://pa11y.org/), a free and open source tool for measuring the accessibility of web sites, and has built a simple -[CI job template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). +[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`. -## Accessibility Merge Request widget +## 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. @@ -29,7 +29,7 @@ analyzed to a file called `accessibility`. In addition to the report artifact that is created, GitLab will also show the Accessibility Report in the merge request widget area: -![Accessibility Merge Request Widget](img/accessibility_mr_widget_v13_0.png) +![Accessibility merge request widget](img/accessibility_mr_widget_v13_0.png) ## Configure Accessibility Testing @@ -38,7 +38,7 @@ on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](htt For GitLab 12.9 and later, to define the `a11y` job, you must [include](../../../ci/yaml/README.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) +[`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. Add the following to your `.gitlab-ci.yml` file: @@ -67,7 +67,7 @@ For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.js NOTE: For GitLab versions earlier than 12.9, you can use `include:remote` and use a -link to the [current template in `master`](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) +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. diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 5917d67c398..63d5119c1b4 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -24,19 +24,17 @@ of the merge request. ## Enabling commit edits from upstream members 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 Developer -permissions to the source project. Once enabled, upstream members can -retry the pipelines and jobs of the merge request: +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: -1. While creating or editing a merge request, select the checkbox **Allow - commits from members who can merge to the target branch**. +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**. + checkbox. +1. Finish creating your merge request. - ![Enable contribution](img/allow_collaboration.png) - -1. Once the merge request is created, you can see that commits from members who - can merge to the target branch are allowed. - - ![Check that contribution is enabled](img/allow_collaboration_after_save.png) +After you create the merge request, the merge request widget displays a message: +**Members who can merge are allowed to add commits.** ## Pushing to the fork as the upstream member @@ -48,41 +46,39 @@ Assuming that: - The forked project URL is `git@gitlab.com:thedude/awesome-project.git`. - The branch of the merge request is `update-docs`. -Here's how the process would look like: - -1. First, you need to get the changes that the merge request has introduced. - Click the **Check out branch** button that has some pre-populated - commands that you can run. - - ![Check out branch button](img/checkout_button.png) +To find and work with the changes from the fork: -1. Use the copy button to copy the first command and paste them - in your terminal: +1. Open the merge request page, and select the **Overview** tab. +1. Scroll to the merge request widget, and select **Check out branch**: + ![Check out branch button](img/commit-button_v13_12.png) +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: ```shell git fetch git@gitlab.com:thedude/awesome-project.git update-docs git checkout -b thedude-awesome-project-update-docs FETCH_HEAD ``` - This fetches the branch of the forked project and then create a local branch + These commands fetch the branch from the forked project, and create a local branch based off the fetched branch. -1. Make any changes you want and commit. -1. Push to the forked project: +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:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs ``` - Note the colon (`:`) between the two branches. The above 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. + Note the colon (`:`) between the two branches. ## Troubleshooting ### Pipeline status unavailable from MR page of forked project -When a user forks a project, the permissions on the forked copy are not copied over +When a user forks a project, the permissions of the forked copy are not copied from the original project. The creator of the fork must grant permissions to the forked copy before members in the upstream project can view or merge the changes in the merge request. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index ac48e44da52..3c47c2af344 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -42,7 +42,7 @@ for more control of the level of oversight and security your project needs, incl - [Require security team approval.](settings.md#security-approvals-in-merge-requests) You can configure your merge request approval rules and settings through the GitLab -user interface or [with the API](../../../../api/merge_request_approvals.md). +user interface or with the [Merge request approvals API](../../../../api/merge_request_approvals.md). ## Approve a merge request @@ -97,36 +97,6 @@ Without the approvals, the work cannot merge. Required approvals enable multiple - [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. **(ULTIMATE)** -## Notify external services **(ULTIMATE)** - -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. -> - [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](../../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. - -You can create an external approval rule to integrate approvals with third-party tools. -When users create, change, or close merge requests, GitLab sends a notification. -The users of the third-party tools can then approve merge requests from outside of GitLab. - -With this integration, you can integrate with third-party workflow tools, like -[ServiceNow](https://www.servicenow.co.uk/), or the custom tool of your choice. -You can modify your external approval rules -[by using the REST API](../../../../api/merge_request_approvals.md#external-project-level-mr-approvals). - -The lack of an external approval doesn't block the merging of a merge request. - -When [approval rule overrides](settings.md#prevent-overrides-of-default-approvals) are allowed, -changes to default approval rules will **not** be applied to existing -merge requests, except for changes to the [target branch](rules.md#approvals-for-protected-branches) -of the rule. - -To learn more about use cases, feature discovery, and development timelines, -see the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). - ## Related links - [Merge request approvals API](../../../../api/merge_request_approvals.md) diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 32f0160771f..1e4b0f659ee 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval rules +# Merge request approval rules **(FREE)** Approval rules define how many [approvals](index.md) a merge request must receive before it can be merged, and which users should do the approving. You can define approval rules: @@ -144,7 +144,7 @@ approve in these ways: [**Prevent committers approval**](settings.md#prevent-committers-from-approving-their-own-work) project setting. -### Code owners as eligible approvers +### 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. @@ -162,7 +162,7 @@ You can also [require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners) for protected branches. **(PREMIUM)** -## Merge request approval segregation of duties +## Merge request approval segregation of duties **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40491) in GitLab 13.4. > - Moved to GitLab Premium in 13.9. diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index 8769f6a7470..97e4b7da396 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval settings +# Merge request approval settings **(FREE)** You can configure the settings for [merge request approvals](index.md) to ensure the approval rules meet your use case. You can also configure diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index aa43d34cdd9..930df65f3fc 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -16,17 +16,17 @@ There are two main ways to have a merge request flow with GitLab: With the protected branch flow everybody works within the same GitLab project. -The project maintainers get Maintainer access and the regular developers get -Developer access. +The project maintainers get the [Maintainer role](../../permissions.md) and the regular developers +get Developer access. -The maintainers mark the authoritative branches as 'Protected'. +Maintainers mark the authoritative branches as 'Protected'. -The developers push feature branches to the project and create merge requests +Developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. -By default, only users with Maintainer access can merge changes into a protected -branch. +By default, only users with the [Maintainer role](../../permissions.md) can merge changes into a +protected branch. **Advantages** @@ -39,14 +39,14 @@ branch. ## Forking workflow -With the forking workflow the maintainers get Maintainer access and the regular +With the forking workflow, maintainers get the [Maintainer role](../../permissions.md) and regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it. Developers create forks of the authoritative project and push their feature branches to their own forks. -To get their changes into master they need to create a merge request across +To get their changes into the default branch, they need to create a merge request across forks. **Advantages** diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index b33919c7fbe..d11ad53a9d6 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -40,18 +40,18 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance). +[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. -For an example Performance job, see +For an example Browser Performance job, see [Configuring Browser Performance Testing](#configuring-browser-performance-testing). NOTE: If the Browser Performance report has no data to compare, such as when you add the Browser Performance job in your `.gitlab-ci.yml` for the very first time, -the Browser Performance report widget doesn't show. It must have run at least -once on the target branch (`master`, for example), before it displays in a +the Browser Performance report widget doesn't display. It must have run at least +once on the target branch (`main`, for example), before it displays in a merge request targeting that branch. ![Browser Performance Widget](img/browser_performance_testing.png) @@ -70,27 +70,26 @@ using Docker-in-Docker. include: template: Verify/Browser-Performance.gitlab-ci.yml - performance: + browser_performance: variables: URL: https://example.com ``` WARNING: -In GitLab 14.0 and later, the job [is scheduled to be renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) -from `performance` to `browser_performance`. +In GitLab 13.12 and earlier, the job [was named](https://gitlab.com/gitlab-org/gitlab/-/issues/225914) `performance`. The above example: -- Creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you +- Creates a `browser_performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you defined in `URL` to gather key metrics. - Uses a template that doesn't work with Kubernetes clusters. If you are using a Kubernetes cluster, - use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) + use [`template: Jobs/Browser-Performance-Testing.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Browser-Performance-Testing.gitlab-ci.yml) instead. - Uses a CI/CD template that is included in all GitLab installations since 12.4. If you are using GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. @@ -108,7 +107,7 @@ makes on the given URL, and change the version: include: template: Verify/Browser-Performance.gitlab-ci.yml -performance: +browser_performance: variables: URL: https://www.sitespeed.io/ SITESPEED_VERSION: 13.2.0 @@ -127,7 +126,7 @@ if the `Total Score` metric degrades by 5 points or more: include: template: Verify/Browser-Performance.gitlab-ci.yml -performance: +browser_performance: variables: URL: https://example.com DEGRADATION_THRESHOLD: 5 @@ -140,13 +139,13 @@ The `Total Score` metric is based on sitespeed.io's [coach performance score](ht The above CI YAML configuration is great for testing against static environments, and it can be extended for dynamic environments, but a few extra steps are required: -1. The `performance` job should run after the dynamic environment has started. +1. The `browser_performance` job should run after the dynamic environment has started. 1. In the `review` job: 1. Generate a URL list file with the dynamic URL. 1. Save the file as an artifact, for example with `echo $CI_ENVIRONMENT_URL > environment_url.txt` in your job's `script`. 1. Pass the list as the URL environment variable (which can be a URL or a file containing URLs) - to the `performance` job. + to the `browser_performance` job. 1. You can now run the sitespeed.io container against the desired hostname and paths. @@ -176,7 +175,7 @@ review: except: - master -performance: +browser_performance: dependencies: - review variables: @@ -191,7 +190,7 @@ GitLab version: - In 13.2 the feature was renamed from `Performance` to `Browser Performance` with additional template CI/CD variables. -- In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). +- In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). - For 11.5 to 12.3 no template is available and the job has to be defined manually as follows: ```yaml diff --git a/doc/user/project/merge_requests/changes.md b/doc/user/project/merge_requests/changes.md index adcf4518209..e594f8048e3 100644 --- a/doc/user/project/merge_requests/changes.md +++ b/doc/user/project/merge_requests/changes.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, reference --- -# Changes tab in merge requests +# Changes tab in merge requests **(FREE)** The **Changes** tab on a [merge request](index.md), below the main merge request details and next to the discussion tab, shows the changes to files between branches or commits. This view of changes to a @@ -70,21 +70,6 @@ merge request: This change overrides the choice you made in your user preferences and persists until you clear your browser's cookies or change this behavior again. -## Merge requests commit navigation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. - -To seamlessly navigate among commits in a merge request: - -1. Select the **Commits** tab. -1. Select a commit to open it in the single-commit view. -1. Navigate through the commits by either: - - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the X and C keyboard shortcuts. - -![Merge requests commit navigation](img/commit_nav_v13_11.png) - ## Incrementally expand merge request diffs By default, the diff shows only the parts of a file which are changed. @@ -106,10 +91,6 @@ specific commit page. ![MR diff](img/merge_request_diff.png) -NOTE: -You can append `?w=1` while on the diffs page of a merge request to ignore any -whitespace changes. - ## Mark files as viewed > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9. @@ -149,3 +130,42 @@ To disable it: ```ruby Feature.disable(:local_file_reviews) ``` + +## Show merge request conflicts in diff + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484) in GitLab 13.5. +> - [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](#enable-or-disable-merge-request-conflicts-in-diff). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +To avoid displaying the changes that are already on target branch in the diff, +we compare the merge request's source branch with HEAD of the target branch. + +When there are conflicts between the source and target branch, we show the +conflicts on the merge request diff as well: + +![Example of a conflict shown in a merge request diff](img/conflict_ui_v14_0.png) + +### Enable or disable merge request conflicts in diff **(FREE SELF)** + +Merge request conflicts in diff 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(:display_merge_conflicts_in_diff) +``` + +To disable it: + +```ruby +Feature.disable(:display_merge_conflicts_in_diff) +``` diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index eaeef12444e..710638128f3 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -63,10 +63,7 @@ git cherry-pick -m 2 7a39eb0 ### Cherry-pick into a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cherry-picking-into-a-project). **(FREE SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/324154) in GitLab 14.0 WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -81,24 +78,10 @@ merge request is from a fork: 1. (Optional) Select **Start a new merge request** if you're ready to create a merge request. 1. Click **Cherry-pick**. -### Enable or disable cherry-picking into a project **(FREE SELF)** +## Related links -Cherry-picking into a project 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(:pick_into_project) -``` - -To disable it: - -```ruby -Feature.disable(:pick_into_project) -``` +- The [Commits API](../../../api/commits.md) enables you to add custom messages + to changes you cherry-pick through the API.