From 48aff82709769b098321c738f3444b9bdaa694c6 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Wed, 21 Oct 2020 07:08:36 +0000 Subject: Add latest changes from gitlab-org/gitlab@13-5-stable-ee --- doc/.vale/gitlab/Acronyms.yml | 2 + doc/.vale/gitlab/Admin.yml | 13 + doc/.vale/gitlab/InclusionAbleism.yml | 14 + doc/.vale/gitlab/InclusionCultural.yml | 16 + doc/.vale/gitlab/InclusionGender.yml | 18 + doc/.vale/gitlab/OutdatedVersions.yml | 2 +- doc/.vale/gitlab/SubstitutionWarning.yml | 3 - doc/.vale/gitlab/Substitutions.yml | 1 + doc/.vale/gitlab/spelling-exceptions.txt | 24 + doc/README.md | 14 +- doc/administration/audit_events.md | 9 +- doc/administration/auditor_users.md | 79 +- doc/administration/auth/README.md | 2 +- doc/administration/auth/ldap/index.md | 42 +- .../auth/ldap/ldap-troubleshooting.md | 2 +- doc/administration/auth/smartcard.md | 3 + doc/administration/compliance.md | 6 + doc/administration/consul.md | 3 + doc/administration/database_load_balancing.md | 10 +- doc/administration/environment_variables.md | 92 +- doc/administration/feature_flags.md | 20 +- doc/administration/geo/disaster_recovery/index.md | 35 +- .../geo/disaster_recovery/planned_failover.md | 2 +- .../geo/disaster_recovery/promotion_runbook.md | 268 +- .../runbooks/planned_failover_multi_node.md | 274 + .../runbooks/planned_failover_single_node.md | 269 + doc/administration/geo/index.md | 14 +- doc/administration/geo/replication/datatypes.md | 119 +- doc/administration/geo/replication/disable_geo.md | 2 +- doc/administration/geo/replication/faq.md | 4 + .../geo/replication/geo_validation_tests.md | 17 +- .../geo/replication/img/geo-ha-diagram.png | Bin 0 -> 43826 bytes .../geo/replication/multiple_servers.md | 5 +- .../geo/replication/troubleshooting.md | 57 +- .../geo/replication/updating_the_geo_nodes.md | 7 +- .../geo/replication/version_specific_updates.md | 12 +- doc/administration/geo/setup/database.md | 12 +- doc/administration/gitaly/index.md | 71 +- doc/administration/gitaly/praefect.md | 25 +- doc/administration/gitaly/reference.md | 4 +- doc/administration/high_availability/README.md | 7 - .../high_availability/alpha_database.md | 5 - doc/administration/high_availability/consul.md | 5 - doc/administration/high_availability/database.md | 5 - doc/administration/high_availability/gitaly.md | 5 - doc/administration/high_availability/gitlab.md | 5 - .../high_availability/img/fully-distributed.png | Bin 46691 -> 0 bytes .../high_availability/img/geo-ha-diagram.png | Bin 43826 -> 0 bytes .../high_availability/img/horizontal.png | Bin 18179 -> 0 bytes .../high_availability/img/hybrid.png | Bin 20693 -> 0 bytes .../high_availability/load_balancer.md | 5 - .../high_availability/monitoring_node.md | 5 - doc/administration/high_availability/nfs.md | 5 - .../high_availability/nfs_host_client_setup.md | 5 - .../high_availability/object_storage.md | 5 - doc/administration/high_availability/pgbouncer.md | 5 - doc/administration/high_availability/redis.md | 5 - .../high_availability/redis_source.md | 5 - doc/administration/high_availability/sidekiq.md | 5 - doc/administration/housekeeping.md | 9 + doc/administration/img/export_audit_log_v13_4.png | Bin 127518 -> 46643 bytes doc/administration/incoming_email.md | 10 +- doc/administration/index.md | 30 +- doc/administration/instance_limits.md | 38 +- doc/administration/instance_review.md | 22 +- doc/administration/integration/plantuml.md | 2 +- doc/administration/integration/terminal.md | 6 + doc/administration/job_artifacts.md | 31 +- doc/administration/job_logs.md | 9 + doc/administration/lfs/index.md | 10 +- doc/administration/libravatar.md | 14 +- doc/administration/load_balancer.md | 3 + doc/administration/logs.md | 40 +- doc/administration/merge_request_diffs.md | 45 +- doc/administration/monitoring/github_imports.md | 2 +- .../gitlab_self_monitoring_project/index.md | 26 +- doc/administration/monitoring/index.md | 2 +- doc/administration/monitoring/ip_whitelist.md | 2 +- .../monitoring/performance/gitlab_configuration.md | 2 +- .../performance/grafana_configuration.md | 4 +- .../monitoring/performance/img/performance_bar.png | Bin 21503 -> 9926 bytes .../img/performance_bar_sql_queries.png | Bin 143074 -> 139550 bytes doc/administration/monitoring/performance/index.md | 4 +- .../monitoring/performance/performance_bar.md | 4 +- .../monitoring/performance/request_profiling.md | 3 +- .../monitoring/prometheus/gitlab_exporter.md | 2 +- .../monitoring/prometheus/gitlab_metrics.md | 25 +- doc/administration/monitoring/prometheus/index.md | 13 +- .../monitoring/prometheus/node_exporter.md | 4 +- .../monitoring/prometheus/pgbouncer_exporter.md | 4 +- .../monitoring/prometheus/postgres_exporter.md | 5 +- .../monitoring/prometheus/redis_exporter.md | 4 +- .../monitoring/prometheus/registry_exporter.md | 2 +- doc/administration/nfs.md | 44 + doc/administration/object_storage.md | 21 +- .../operations/cleaning_up_redis_sessions.md | 6 + .../operations/extra_sidekiq_processes.md | 6 + .../operations/fast_ssh_key_lookup.md | 7 +- .../operations/filesystem_benchmarking.md | 6 + doc/administration/operations/index.md | 6 + .../operations/moving_repositories.md | 6 + doc/administration/operations/puma.md | 6 + doc/administration/operations/rails_console.md | 144 + .../operations/sidekiq_memory_killer.md | 8 +- doc/administration/operations/ssh_certificates.md | 6 + doc/administration/operations/unicorn.md | 6 + doc/administration/packages/container_registry.md | 194 +- doc/administration/packages/dependency_proxy.md | 36 +- doc/administration/packages/index.md | 53 +- doc/administration/pages/index.md | 41 +- doc/administration/pages/source.md | 4 - doc/administration/postgresql/external.md | 6 + doc/administration/postgresql/index.md | 5 +- doc/administration/postgresql/pgbouncer.md | 32 + .../postgresql/replication_and_failover.md | 117 +- doc/administration/postgresql/standalone.md | 14 +- doc/administration/raketasks/check.md | 31 +- doc/administration/raketasks/doctor.md | 5 +- doc/administration/raketasks/github_import.md | 5 +- doc/administration/raketasks/uploads/sanitize.md | 2 +- doc/administration/read_only_gitlab.md | 125 + .../redis/replication_and_failover.md | 6 +- .../redis/replication_and_failover_external.md | 14 +- doc/administration/redis/troubleshooting.md | 6 +- .../reference_architectures/10k_users.md | 560 +- .../reference_architectures/1k_users.md | 28 +- .../reference_architectures/25k_users.md | 560 +- .../reference_architectures/2k_users.md | 217 +- .../reference_architectures/3k_users.md | 437 +- .../reference_architectures/50k_users.md | 560 +- .../reference_architectures/5k_users.md | 433 +- .../reference_architectures/index.md | 2 +- doc/administration/reply_by_email_postfix_setup.md | 10 +- doc/administration/repository_storage_types.md | 4 +- doc/administration/server_hooks.md | 16 - doc/administration/smime_signing_email.md | 4 +- doc/administration/snippets/index.md | 4 +- doc/administration/terraform_state.md | 6 + doc/administration/troubleshooting/debug.md | 24 +- .../troubleshooting/elasticsearch.md | 8 +- .../troubleshooting/gitlab_rails_cheat_sheet.md | 74 +- .../troubleshooting/kubernetes_cheat_sheet.md | 7 +- doc/administration/troubleshooting/log_parsing.md | 4 +- .../navigating_gitlab_via_rails_console.md | 18 +- doc/administration/troubleshooting/sidekiq.md | 2 +- doc/administration/troubleshooting/ssl.md | 4 +- .../troubleshooting/tracing_correlation_id.md | 4 +- doc/administration/uploads.md | 37 +- doc/api/README.md | 96 +- doc/api/admin_sidekiq_queues.md | 1 + doc/api/api_resources.md | 7 +- doc/api/commits.md | 2 +- doc/api/container_registry.md | 49 +- doc/api/epics.md | 8 +- doc/api/experiments.md | 40 + doc/api/feature_flag_user_lists.md | 5 +- doc/api/feature_flags.md | 8 +- doc/api/feature_flags_legacy.md | 6 +- doc/api/geo_nodes.md | 16 +- doc/api/graphql/reference/gitlab_schema.graphql | 2998 +++++++- doc/api/graphql/reference/gitlab_schema.json | 7797 +++++++++++++++++--- doc/api/graphql/reference/index.md | 397 +- doc/api/group_clusters.md | 3 +- doc/api/group_iterations.md | 55 + doc/api/group_milestones.md | 2 +- doc/api/group_wikis.md | 4 +- doc/api/groups.md | 97 +- doc/api/import.md | 4 +- doc/api/instance_level_ci_variables.md | 6 +- doc/api/issue_links.md | 22 +- doc/api/issues.md | 161 +- doc/api/iterations.md | 57 + doc/api/job_artifacts.md | 10 + doc/api/license.md | 4 +- doc/api/lint.md | 190 +- doc/api/members.md | 58 +- doc/api/merge_request_approvals.md | 2 +- doc/api/merge_requests.md | 12 +- doc/api/metrics_dashboard_annotations.md | 7 +- doc/api/metrics_user_starred_dashboards.md | 2 +- doc/api/namespaces.md | 26 + doc/api/openapi/openapi.yaml | 4 +- doc/api/packages.md | 17 +- doc/api/personal_access_tokens.md | 4 +- doc/api/project_badges.md | 2 +- doc/api/project_clusters.md | 3 +- doc/api/project_repository_storage_moves.md | 2 +- doc/api/project_snippets.md | 61 +- doc/api/projects.md | 115 + doc/api/protected_branches.md | 61 + doc/api/releases/index.md | 17 +- doc/api/repositories.md | 3 +- doc/api/resource_iteration_events.md | 29 +- doc/api/runners.md | 47 +- doc/api/search.md | 75 +- doc/api/services.md | 4 +- doc/api/settings.md | 42 +- doc/api/snippets.md | 105 +- doc/api/templates/gitlab_ci_ymls.md | 2 +- doc/api/todos.md | 22 +- doc/api/users.md | 12 +- doc/api/v3_to_v4.md | 2 +- doc/api/vulnerabilities.md | 50 + doc/api/vulnerability_exports.md | 22 +- doc/api/wikis.md | 2 +- .../blueprints/cloud_native_build_logs/index.md | 141 + .../blueprints/cloud_native_gitlab_pages/index.md | 135 + .../blueprints/feature_flags_development/index.md | 140 + doc/architecture/index.md | 9 + doc/articles/artifactory_and_gitlab/index.md | 5 - .../how_to_configure_ldap_gitlab_ce/index.md | 5 - .../how_to_configure_ldap_gitlab_ee/index.md | 5 - doc/articles/how_to_install_git/index.md | 5 - doc/articles/index.md | 5 - .../laravel_with_gitlab_and_envoy/index.md | 5 - .../numerous_undo_possibilities_in_git/index.md | 5 - doc/articles/openshift_and_gitlab/index.md | 3 - doc/articles/runner_autoscale_aws/index.md | 5 - doc/ci/README.md | 9 +- doc/ci/caching/index.md | 6 +- .../bitbucket_integration.md | 2 +- .../ci_cd_for_external_repos/github_integration.md | 2 - doc/ci/ci_cd_for_external_repos/index.md | 1 - doc/ci/cloud_deployment/index.md | 83 +- doc/ci/docker/using_docker_build.md | 24 +- doc/ci/docker/using_docker_images.md | 38 +- doc/ci/docker/using_kaniko.md | 6 +- doc/ci/enable_or_disable_ci.md | 1 - doc/ci/environments/index.md | 111 +- doc/ci/environments/protected_environments.md | 2 - doc/ci/examples/artifactory_and_gitlab/index.md | 15 +- .../authenticating-with-hashicorp-vault/index.md | 17 +- .../end_to_end_testing_webdriverio/index.md | 9 +- .../laravel_with_gitlab_and_envoy/index.md | 15 +- doc/ci/examples/php.md | 23 +- .../test-and-deploy-ruby-application-to-heroku.md | 2 +- .../test_phoenix_app_with_gitlab_ci_cd/index.md | 2 - doc/ci/img/cf_ec2_diagram_v13_5.png | Bin 0 -> 43247 bytes doc/ci/img/ci_lint.png | Bin 37745 -> 11525 bytes doc/ci/img/ci_lint_dry_run.png | Bin 18688 -> 6811 bytes doc/ci/img/gitlab_vault_workflow_v13_4.png | Bin 0 -> 47541 bytes doc/ci/introduction/index.md | 4 +- doc/ci/merge_request_pipelines/index.md | 6 +- .../pipelines_for_merged_results/index.md | 4 +- .../merge_trains/index.md | 1 - doc/ci/metrics_reports.md | 2 - doc/ci/migration/jenkins.md | 4 +- doc/ci/multi_project_pipelines.md | 53 +- doc/ci/parent_child_pipelines.md | 44 +- .../ci_efficiency_pipeline_dag_critical_path.png | Bin 124100 -> 35397 bytes ...fficiency_pipeline_health_grafana_dashboard.png | Bin 241128 -> 55200 bytes doc/ci/pipelines/index.md | 31 +- doc/ci/pipelines/job_artifacts.md | 27 +- doc/ci/pipelines/pipeline_artifacts.md | 18 + doc/ci/pipelines/schedules.md | 5 +- doc/ci/pipelines/settings.md | 65 +- doc/ci/quick_start/README.md | 13 +- doc/ci/review_apps/img/toolbar_feeback_form.png | Bin 24599 -> 0 bytes .../img/toolbar_feedback_form_v13_5.png | Bin 0 -> 13176 bytes doc/ci/review_apps/index.md | 92 +- doc/ci/runners/README.md | 30 +- doc/ci/secrets/index.md | 27 +- doc/ci/services/postgres.md | 45 +- doc/ci/ssh_keys/README.md | 6 +- doc/ci/triggers/README.md | 35 +- doc/ci/unit_test_reports.md | 15 +- doc/ci/variables/README.md | 93 +- doc/ci/variables/deprecated_variables.md | 1 - doc/ci/variables/predefined_variables.md | 5 +- doc/ci/variables/where_variables_can_be_used.md | 12 +- doc/ci/yaml/README.md | 974 +-- .../img/ci_config_visualization_hover_v13_5.png | Bin 0 -> 30986 bytes doc/ci/yaml/img/ci_config_visualization_v13_5.png | Bin 0 -> 30319 bytes doc/ci/yaml/includes.md | 9 +- doc/ci/yaml/visualization.md | 46 + doc/container_registry/README.md | 5 - doc/container_registry/troubleshooting.md | 5 - doc/customization/welcome_message.md | 4 +- doc/development/README.md | 10 +- doc/development/adding_database_indexes.md | 6 + doc/development/adding_service_component.md | 2 +- doc/development/api_graphql_styleguide.md | 95 +- doc/development/api_styleguide.md | 2 +- doc/development/architecture.md | 214 +- doc/development/background_migrations.md | 23 +- doc/development/changelog.md | 11 +- doc/development/chatops_on_gitlabcom.md | 4 +- doc/development/cicd/templates.md | 21 +- doc/development/code_review.md | 5 + doc/development/contributing/community_roles.md | 6 + doc/development/contributing/design.md | 7 + doc/development/contributing/index.md | 7 + doc/development/contributing/issue_workflow.md | 12 + .../contributing/merge_request_workflow.md | 9 +- doc/development/contributing/style_guides.md | 7 + .../database/add_foreign_key_to_existing_column.md | 8 +- .../database/client_side_connection_pool.md | 63 + .../database/database_reviewer_guidelines.md | 6 + doc/development/database/index.md | 9 + doc/development/database/not_null_constraints.md | 8 +- .../database/setting_multiple_values.md | 103 + .../database/strings_and_the_text_data_type.md | 6 + doc/development/database/table_partitioning.md | 259 + doc/development/database_debugging.md | 8 +- doc/development/database_query_comments.md | 6 + doc/development/database_review.md | 12 +- doc/development/db_dump.md | 6 + doc/development/distributed_tracing.md | 7 +- doc/development/documentation/feature_flags.md | 4 +- .../documentation/graphql_styleguide.md | 92 + doc/development/documentation/index.md | 80 +- .../documentation/restful_api_styleguide.md | 180 + .../documentation/site_architecture/global_nav.md | 5 +- .../site_architecture/release_process.md | 5 +- doc/development/documentation/styleguide.md | 390 +- doc/development/elasticsearch.md | 2 +- doc/development/emails.md | 2 +- doc/development/event_tracking/backend.md | 4 +- doc/development/event_tracking/frontend.md | 4 +- doc/development/event_tracking/index.md | 4 +- doc/development/experiment_guide/index.md | 141 +- doc/development/fe_guide/architecture.md | 4 +- doc/development/fe_guide/dependencies.md | 6 +- doc/development/fe_guide/event_tracking.md | 4 +- doc/development/fe_guide/graphql.md | 8 +- doc/development/fe_guide/icons.md | 28 +- doc/development/fe_guide/index.md | 4 + doc/development/fe_guide/keyboard_shortcuts.md | 98 + doc/development/fe_guide/tooling.md | 5 +- doc/development/fe_guide/vuex.md | 5 +- doc/development/feature_categorization/index.md | 40 +- doc/development/feature_flags/controls.md | 39 +- doc/development/feature_flags/development.md | 32 +- doc/development/frontend.md | 7 +- doc/development/geo.md | 8 +- doc/development/geo/framework.md | 52 +- doc/development/go_guide/index.md | 6 +- doc/development/gotchas.md | 15 + doc/development/graphql_guide/index.md | 2 +- doc/development/i18n/externalization.md | 4 +- doc/development/i18n/index.md | 6 +- doc/development/img/architecture_simplified.png | Bin 21239 -> 106339 bytes doc/development/instrumentation.md | 4 +- doc/development/integrations/secure.md | 9 +- .../integrations/secure_partner_integration.md | 8 +- doc/development/internal_api.md | 3 +- doc/development/kubernetes.md | 51 +- doc/development/logging.md | 3 +- doc/development/migration_style_guide.md | 35 +- doc/development/multi_version_compatibility.md | 2 +- .../new_fe_guide/development/accessibility.md | 2 +- doc/development/new_fe_guide/development/index.md | 2 +- doc/development/packages.md | 21 +- doc/development/performance.md | 8 +- doc/development/pipelines.md | 2 - doc/development/policies.md | 10 +- .../product_analytics/event_dictionary.md | 32 + doc/development/product_analytics/index.md | 182 + doc/development/product_analytics/snowplow.md | 429 ++ doc/development/product_analytics/usage_ping.md | 937 +++ doc/development/profiling.md | 3 - doc/development/prometheus.md | 12 +- doc/development/prometheus_metrics.md | 11 +- doc/development/reactive_caching.md | 6 +- doc/development/redis.md | 12 +- doc/development/reference_processing.md | 16 + doc/development/secure_coding_guidelines.md | 43 +- doc/development/shell_scripting_guide/index.md | 4 +- doc/development/sidekiq_style_guide.md | 81 +- doc/development/sql.md | 2 +- doc/development/swapping_tables.md | 6 + doc/development/telemetry/event_dictionary.md | 31 +- doc/development/telemetry/index.md | 181 +- doc/development/telemetry/snowplow.md | 409 +- doc/development/telemetry/usage_ping.md | 886 +-- doc/development/testing_guide/best_practices.md | 37 +- doc/development/testing_guide/ci.md | 3 - .../testing_guide/end_to_end/beginners_guide.md | 4 +- .../testing_guide/end_to_end/best_practices.md | 59 +- .../end_to_end/environment_selection.md | 27 +- .../testing_guide/end_to_end/feature_flags.md | 57 +- .../end_to_end/rspec_metadata_tests.md | 2 +- .../running_tests_that_require_special_setup.md | 4 +- .../testing_guide/end_to_end/style_guide.md | 4 +- doc/development/testing_guide/frontend_testing.md | 2 +- doc/development/what_requires_downtime.md | 4 +- doc/development/wikis.md | 94 + doc/getting-started/subscription.md | 3 - doc/git_hooks/git_hooks.md | 5 - doc/gitlab-basics/README.md | 2 +- doc/gitlab-basics/add-file.md | 15 +- doc/gitlab-basics/create-branch.md | 6 +- doc/gitlab-basics/create-project.md | 30 +- doc/gitlab-basics/start-using-git.md | 21 +- doc/gitlab-geo/README.md | 5 - doc/gitlab-geo/after_setup.md | 5 - doc/gitlab-geo/bring-primary-back.md | 5 - doc/gitlab-geo/configuration.md | 5 - doc/gitlab-geo/configuration_source.md | 5 - doc/gitlab-geo/database.md | 5 - doc/gitlab-geo/database_source.md | 5 - doc/gitlab-geo/disaster-recovery.md | 5 - doc/gitlab-geo/docker_registry.md | 5 - doc/gitlab-geo/faq.md | 5 - doc/gitlab-geo/ha.md | 5 - doc/gitlab-geo/object_storage.md | 5 - doc/gitlab-geo/planned-failover.md | 5 - doc/gitlab-geo/security-review.md | 5 - doc/gitlab-geo/ssh.md | 5 - doc/gitlab-geo/troubleshooting.md | 5 - doc/gitlab-geo/tuning.md | 5 - doc/gitlab-geo/updating_the_geo_nodes.md | 5 - doc/gitlab-geo/using_a_geo_server.md | 5 - doc/hooks/custom_hooks.md | 7 - doc/incoming_email/README.md | 5 - doc/incoming_email/postfix.md | 5 - doc/install/README.md | 102 +- doc/install/aws/index.md | 5 +- doc/install/azure/index.md | 2 +- doc/install/docker.md | 3 + doc/install/google_cloud_platform/index.md | 3 + doc/install/installation.md | 76 +- doc/install/openshift_and_gitlab/index.md | 6 +- doc/install/relative_url.md | 3 + doc/install/requirements.md | 3 + doc/install/structure.md | 2 +- doc/integration/README.md | 15 +- doc/integration/cas.md | 8 +- doc/integration/elasticsearch.md | 260 +- doc/integration/external-issue-tracker.md | 19 +- doc/integration/facebook.md | 2 +- doc/integration/github.md | 26 +- doc/integration/gitlab.md | 7 +- doc/integration/gitpod.md | 19 +- doc/integration/google.md | 7 +- doc/integration/jira_development_panel.md | 25 +- doc/integration/kerberos.md | 51 +- doc/integration/omniauth.md | 28 +- doc/integration/salesforce.md | 2 +- doc/integration/saml.md | 116 +- doc/integration/sourcegraph.md | 2 +- doc/integration/twitter.md | 3 +- doc/intro/README.md | 2 +- doc/logs/logs.md | 5 - doc/operations/error_tracking.md | 12 +- doc/operations/feature_flags.md | 87 +- .../incident_management/alert_details.md | 199 +- .../incident_management/alert_integrations.md | 163 + .../incident_management/alert_notifications.md | 36 + doc/operations/incident_management/alerts.md | 300 +- .../incident_management/generic_alerts.md | 125 +- .../img/alert_detail_activity_feed_v13_5.png | Bin 0 -> 37418 bytes .../img/incident_highlight_bar_v13_5.png | Bin 0 -> 36177 bytes .../img/incident_list_v13_4.png | Bin 16735 -> 0 bytes .../img/incident_list_v13_5.png | Bin 0 -> 43685 bytes .../img/incident_sla_settings_v13_5.png | Bin 0 -> 21480 bytes .../img/integrations_list_v13_5.png | Bin 0 -> 9916 bytes .../img/link_runbooks_to_alerts_v13_5.png | Bin 0 -> 77748 bytes .../img/timeline_view_toggle_v13_5.png | Bin 0 -> 5651 bytes doc/operations/incident_management/incidents.md | 240 +- doc/operations/incident_management/index.md | 79 +- doc/operations/incident_management/integrations.md | 16 + doc/operations/incident_management/status_page.md | 16 +- doc/operations/index.md | 4 +- doc/operations/metrics/alerts.md | 8 +- doc/operations/metrics/dashboards/default.md | 3 +- doc/operations/metrics/dashboards/develop.md | 2 +- .../img/metrics_dashboard_panel_preview_v13_3.png | Bin 67972 -> 45857 bytes doc/operations/metrics/dashboards/index.md | 21 +- doc/operations/metrics/dashboards/panel_types.md | 72 +- doc/operations/metrics/dashboards/settings.md | 2 +- .../metrics/dashboards/templating_variables.md | 2 +- doc/operations/metrics/dashboards/variables.md | 10 +- doc/operations/metrics/dashboards/yaml.md | 16 +- .../metrics/dashboards/yaml_number_format.md | 2 +- doc/operations/metrics/embed.md | 5 +- doc/operations/metrics/embed_grafana.md | 11 +- doc/operations/metrics/index.md | 2 +- doc/operations/product_analytics.md | 4 +- doc/operations/tracing.md | 7 +- doc/pages/README.md | 5 - doc/pages/administration.md | 5 - doc/pages/getting_started_part_one.md | 5 - doc/pages/getting_started_part_three.md | 5 - doc/pages/getting_started_part_two.md | 5 - doc/policy/maintenance.md | 6 +- doc/profile/README.md | 5 - doc/profile/preferences.md | 5 - doc/profile/two_factor_authentication.md | 5 - doc/project_services/bamboo.md | 5 - doc/project_services/bugzilla.md | 5 - doc/project_services/emails_on_push.md | 5 - doc/project_services/hipchat.md | 5 - doc/project_services/irker.md | 5 - doc/project_services/jira.md | 5 - doc/project_services/kubernetes.md | 5 - doc/project_services/mattermost.md | 5 - doc/project_services/mattermost_slash_commands.md | 5 - doc/project_services/project_services.md | 5 - doc/project_services/redmine.md | 5 - doc/project_services/services_templates.md | 5 - doc/project_services/slack.md | 5 - doc/project_services/slack_slash_commands.md | 5 - doc/push_rules/push_rules.md | 40 +- doc/raketasks/README.md | 2 +- doc/raketasks/backup_restore.md | 647 +- doc/raketasks/cleanup.md | 4 +- doc/raketasks/import.md | 4 +- doc/security/asset_proxy.md | 2 +- ...swords_for_integrated_authentication_methods.md | 2 +- ...ject_import_decompressed_archive_size_limits.md | 2 +- doc/security/rack_attack.md | 2 - doc/security/rate_limits.md | 19 + doc/security/two_factor_authentication.md | 13 + doc/ssh/README.md | 6 +- doc/subscriptions/gitlab_com/index.md | 48 +- doc/subscriptions/self_managed/index.md | 33 +- doc/system_hooks/system_hooks.md | 19 +- doc/telemetry/index.md | 4 +- doc/telemetry/snowplow.md | 4 +- doc/topics/autodevops/customize.md | 4 +- doc/topics/autodevops/index.md | 66 +- doc/topics/autodevops/stages.md | 27 +- .../upgrading_auto_deploy_dependencies.md | 262 + doc/topics/autodevops/upgrading_chart.md | 75 +- doc/topics/autodevops/upgrading_postgresql.md | 7 +- doc/topics/cron/index.md | 2 +- doc/topics/git/git_rebase.md | 272 + doc/topics/git/img/git_rebase_v13_5.png | Bin 0 -> 49048 bytes doc/topics/git/index.md | 1 + doc/university/README.md | 8 +- doc/university/training/index.md | 2 +- doc/update/10.0-ce-to-ee.md | 5 - doc/update/10.0-to-10.1.md | 5 - doc/update/10.1-ce-to-ee.md | 5 - doc/update/10.1-to-10.2.md | 5 - doc/update/10.2-ce-to-ee.md | 5 - doc/update/10.2-to-10.3.md | 5 - doc/update/10.3-ce-to-ee.md | 5 - doc/update/10.3-to-10.4.md | 5 - doc/update/10.4-ce-to-ee.md | 5 - doc/update/10.4-to-10.5.md | 5 - doc/update/10.5-ce-to-ee.md | 5 - doc/update/10.5-to-10.6.md | 5 - doc/update/10.6-ce-to-ee.md | 5 - doc/update/10.6-to-10.7.md | 5 - doc/update/10.7-ce-to-ee.md | 5 - doc/update/10.7-to-10.8.md | 5 - doc/update/10.8-ce-to-ee.md | 5 - doc/update/10.8-to-11.0.md | 5 - doc/update/11.0-ce-to-ee.md | 5 - doc/update/11.0-to-11.1.md | 5 - doc/update/11.1-ce-to-ee.md | 5 - doc/update/11.1-to-11.2.md | 5 - doc/update/11.2-ce-to-ee.md | 5 - doc/update/11.2-to-11.3.md | 5 - doc/update/11.3-ce-to-ee.md | 5 - doc/update/11.3-to-11.4.md | 5 - doc/update/11.4-ce-to-ee.md | 5 - doc/update/11.4-to-11.5.md | 5 - doc/update/11.5-ce-to-ee.md | 5 - doc/update/11.5-to-11.6.md | 5 - doc/update/11.6-ce-to-ee.md | 5 - doc/update/11.6-to-11.7.md | 5 - doc/update/11.7-ce-to-ee.md | 5 - doc/update/11.7-to-11.8.md | 5 - doc/update/11.8-ce-to-ee.md | 5 - doc/update/2.6-to-3.0.md | 5 - doc/update/2.9-to-3.0.md | 5 - doc/update/3.0-to-3.1.md | 5 - doc/update/3.1-to-4.0.md | 5 - doc/update/4.0-to-4.1.md | 5 - doc/update/4.1-to-4.2.md | 5 - doc/update/4.2-to-5.0.md | 5 - doc/update/5.0-to-5.1.md | 5 - doc/update/5.1-to-5.2.md | 5 - doc/update/5.1-to-5.4.md | 5 - doc/update/5.1-to-6.0.md | 5 - doc/update/5.2-to-5.3.md | 5 - doc/update/5.3-to-5.4.md | 5 - doc/update/5.4-to-6.0.md | 5 - doc/update/6.0-ce-to-ee.md | 5 - doc/update/6.0-to-6.1.md | 5 - doc/update/6.1-ce-to-ee.md | 5 - doc/update/6.1-to-6.2.md | 5 - doc/update/6.2-ce-to-ee.md | 5 - doc/update/6.2-to-6.3.md | 5 - doc/update/6.3-ce-to-ee.md | 5 - doc/update/6.3-to-6.4.md | 5 - doc/update/6.4-ce-to-ee.md | 5 - doc/update/6.4-to-6.5.md | 5 - doc/update/6.5-ce-to-ee.md | 5 - doc/update/6.5-to-6.6.md | 5 - doc/update/6.6-ce-to-ee.md | 5 - doc/update/6.6-to-6.7.md | 5 - doc/update/6.7-ce-to-ee.md | 5 - doc/update/6.7-to-6.8.md | 5 - doc/update/6.8-ce-to-ee.md | 5 - doc/update/6.8-to-6.9.md | 5 - doc/update/6.9-ce-to-ee.md | 5 - doc/update/6.9-to-7.0.md | 5 - doc/update/6.x-or-7.x-to-7.14.md | 5 - doc/update/7.0-ce-to-ee.md | 5 - doc/update/7.0-to-7.1.md | 5 - doc/update/7.1-ce-to-ee.md | 5 - doc/update/7.1-to-7.2.md | 5 - doc/update/7.10-ce-to-ee.md | 5 - doc/update/7.10-to-7.11.md | 5 - doc/update/7.11-ce-to-ee.md | 5 - doc/update/7.11-to-7.12.md | 5 - doc/update/7.12-ce-to-ee.md | 5 - doc/update/7.12-to-7.13.md | 5 - doc/update/7.13-ce-to-ee.md | 5 - doc/update/7.13-to-7.14.md | 5 - doc/update/7.14-ce-to-ee.md | 5 - doc/update/7.14-to-8.0.md | 5 - doc/update/7.2-to-7.3.md | 5 - doc/update/7.3-ce-to-ee.md | 5 - doc/update/7.3-to-7.4.md | 5 - doc/update/7.4-ce-to-ee.md | 5 - doc/update/7.4-to-7.5.md | 5 - doc/update/7.5-ce-to-ee.md | 5 - doc/update/7.5-to-7.6.md | 5 - doc/update/7.6-ce-to-ee.md | 5 - doc/update/7.6-to-7.7.md | 5 - doc/update/7.7-ce-to-ee.md | 5 - doc/update/7.7-to-7.8.md | 5 - doc/update/7.8-ce-to-ee.md | 5 - doc/update/7.8-to-7.9.md | 5 - doc/update/7.9-ce-to-ee.md | 5 - doc/update/7.9-to-7.10.md | 5 - doc/update/8.0-ce-to-ee.md | 5 - doc/update/8.0-to-8.1.md | 5 - doc/update/8.1-ce-to-ee.md | 5 - doc/update/8.1-to-8.2.md | 5 - doc/update/8.10-ce-to-ee.md | 5 - doc/update/8.10-to-8.11.md | 5 - doc/update/8.11-ce-to-ee.md | 5 - doc/update/8.11-to-8.12.md | 5 - doc/update/8.12-ce-to-ee.md | 5 - doc/update/8.12-to-8.13.md | 5 - doc/update/8.13-ce-to-ee.md | 5 - doc/update/8.13-to-8.14.md | 5 - doc/update/8.14-ce-to-ee.md | 5 - doc/update/8.14-to-8.15.md | 5 - doc/update/8.15-ce-to-ee.md | 5 - doc/update/8.15-to-8.16.md | 5 - doc/update/8.16-ce-to-ee.md | 5 - doc/update/8.16-to-8.17.md | 5 - doc/update/8.17-ce-to-ee.md | 5 - doc/update/8.17-to-9.0.md | 5 - doc/update/8.2-ce-to-ee.md | 5 - doc/update/8.2-to-8.3.md | 5 - doc/update/8.3-ce-to-ee.md | 5 - doc/update/8.3-to-8.4.md | 5 - doc/update/8.4-ce-to-ee.md | 5 - doc/update/8.4-to-8.5.md | 5 - doc/update/8.5-ce-to-ee.md | 5 - doc/update/8.5-to-8.6.md | 5 - doc/update/8.6-ce-to-ee.md | 5 - doc/update/8.6-to-8.7.md | 5 - doc/update/8.7-ce-to-ee.md | 5 - doc/update/8.7-to-8.8.md | 5 - doc/update/8.8-ce-to-ee.md | 5 - doc/update/8.8-to-8.9.md | 5 - doc/update/8.9-ce-to-ee.md | 5 - doc/update/8.9-to-8.10.md | 5 - doc/update/9.0-ce-to-ee.md | 5 - doc/update/9.0-to-9.1.md | 5 - doc/update/9.1-ce-to-ee.md | 5 - doc/update/9.1-to-9.2.md | 5 - doc/update/9.2-ce-to-ee.md | 5 - doc/update/9.2-to-9.3.md | 5 - doc/update/9.3-ce-to-ee.md | 5 - doc/update/9.3-to-9.4.md | 5 - doc/update/9.4-ce-to-ee.md | 5 - doc/update/9.4-to-9.5.md | 5 - doc/update/9.5-ce-to-ee.md | 5 - doc/update/9.5-to-10.0.md | 5 - doc/update/README.md | 4 +- doc/user/admin_area/abuse_reports.md | 18 +- .../admin_area/activating_deactivating_users.md | 2 +- .../admin_area/analytics/img/cohorts_v13_4.png | Bin 92729 -> 31518 bytes .../analytics/img/dev_ops_report_v13_4.png | Bin 167541 -> 51758 bytes doc/user/admin_area/analytics/index.md | 3 +- .../admin_area/analytics/instance_statistics.md | 18 + doc/user/admin_area/approving_users.md | 36 + doc/user/admin_area/credentials_inventory.md | 22 +- doc/user/admin_area/img/admin_wrench.png | Bin 3314 -> 0 bytes .../img/credentials_inventory_ssh_keys_v13_5.png | Bin 0 -> 26813 bytes doc/user/admin_area/index.md | 11 +- doc/user/admin_area/license.md | 112 +- doc/user/admin_area/settings/gitaly_timeouts.md | 40 +- .../settings/img/email_confirmation_v12_7.png | Bin 9837 -> 0 bytes .../admin_area/settings/img/gitaly_timeouts.png | Bin 24654 -> 0 bytes .../settings/img/sign_up_restrictions_v13_5.png | Bin 0 -> 39902 bytes doc/user/admin_area/settings/index.md | 8 +- .../settings/instance_template_repository.md | 2 - .../settings/project_integration_management.md | 45 +- .../admin_area/settings/sign_up_restrictions.md | 11 +- doc/user/admin_area/settings/usage_statistics.md | 2 +- .../analytics/img/mr_throughput_chart_v13_3.png | Bin 62510 -> 17870 bytes .../analytics/img/mr_throughput_table_v13_3.png | Bin 55637 -> 20273 bytes doc/user/analytics/img/new_value_stream_v13_3.png | Bin 82797 -> 31215 bytes doc/user/analytics/img/vsa_filter_bar_v13.3.png | Bin 117834 -> 33694 bytes doc/user/analytics/index.md | 11 +- doc/user/analytics/merge_request_analytics.md | 15 - doc/user/analytics/productivity_analytics.md | 28 +- doc/user/analytics/value_stream_analytics.md | 50 +- doc/user/application_security/api_fuzzing/index.md | 8 +- .../application_security/configuration/index.md | 10 +- .../container_scanning/index.md | 26 +- .../application_security/coverage_fuzzing/index.md | 46 + .../application_security/dast/img/dast_v13_2.png | Bin 6763 -> 0 bytes .../application_security/dast/img/dast_v13_4.png | Bin 0 -> 6558 bytes doc/user/application_security/dast/index.md | 98 +- .../dependency_scanning/index.md | 131 +- .../img/cve_request_communication.png | Bin 45402 -> 17386 bytes .../img/cve_request_communication_publication.png | Bin 66617 -> 24126 bytes .../img/new_cve_request_issue.png | Bin 96795 -> 36847 bytes ...urity_approval_rules_and_enabled_jobs_v13_4.png | Bin 99883 -> 35553 bytes ...ured_security_approval_rules_and_jobs_v13_4.png | Bin 82526 -> 29773 bytes .../img/vulnerability-check_v13_4.png | Bin 75105 -> 25832 bytes .../img/vulnerability_solution.png | Bin 3419 -> 9750 bytes doc/user/application_security/index.md | 29 +- doc/user/application_security/sast/analyzers.md | 43 +- doc/user/application_security/sast/index.md | 206 +- .../application_security/secret_detection/index.md | 130 +- .../img/group_vulnerability_report_v13_4.png | Bin 42099 -> 50648 bytes .../instance_security_center_settings_v13_4.png | Bin 0 -> 30034 bytes .../instance_security_dashboard_empty_v13_4.png | Bin 38731 -> 13264 bytes .../img/instance_security_dashboard_v13_4.png | Bin 62615 -> 29797 bytes .../project_security_dashboard_dismissal_v13_4.png | Bin 0 -> 53541 bytes .../img/project_security_dashboard_v13_0.png | Bin 66337 -> 0 bytes .../img/project_security_dashboard_v13_2.png | Bin 78549 -> 0 bytes .../img/project_security_dashboard_v13_3.png | Bin 168847 -> 0 bytes .../img/project_security_dashboard_v13_5.png | Bin 0 -> 69166 bytes .../img/vulnerability_list_table_v13_4.png | Bin 79904 -> 61329 bytes .../security_dashboard/index.md | 142 +- doc/user/application_security/terminology/index.md | 1 - .../threat_monitoring/index.md | 24 +- .../application_security/vulnerabilities/index.md | 11 + doc/user/clusters/agent/index.md | 231 +- doc/user/clusters/applications.md | 753 +- doc/user/clusters/cost_management.md | 74 + doc/user/clusters/crossplane.md | 1 - doc/user/clusters/environments.md | 5 +- doc/user/clusters/img/kubecost_v13_5.png | Bin 0 -> 34791 bytes .../img/compliance_dashboard_v13_3_1.png | Bin 298542 -> 71374 bytes .../license_compliance/img/license-check_v13_4.png | Bin 74407 -> 25590 bytes doc/user/compliance/license_compliance/index.md | 11 +- doc/user/gitlab_com/index.md | 24 +- doc/user/group/clusters/index.md | 6 +- doc/user/group/contribution_analytics/index.md | 2 - doc/user/group/epics/index.md | 46 +- doc/user/group/index.md | 49 +- doc/user/group/iterations/index.md | 9 + doc/user/group/repositories_analytics/index.md | 27 +- doc/user/group/saml_sso/index.md | 54 +- doc/user/group/saml_sso/scim_setup.md | 36 +- .../img/feature_flags_history_note_info_v13_2.png | Bin 67034 -> 21794 bytes doc/user/img/gitlab_snippet_v13_5.png | Bin 0 -> 20563 bytes .../img/version_history_notes_collapsed_v13_2.png | Bin 27528 -> 7770 bytes doc/user/index.md | 6 +- doc/user/infrastructure/index.md | 42 +- doc/user/instance/clusters/index.md | 4 +- doc/user/markdown.md | 92 +- .../composer_repository/img/project_id_v13_5.png | Bin 0 -> 9264 bytes doc/user/packages/composer_repository/index.md | 315 +- .../conan_repository/img/conan_package_view.png | Bin 46391 -> 0 bytes doc/user/packages/conan_repository/index.md | 382 +- ...container_registry_group_repositories_v13_1.png | Bin 45865 -> 0 bytes .../img/container_registry_hover_path_13_4.png | Bin 0 -> 13597 bytes .../img/container_registry_repositories_v13_1.png | Bin 46734 -> 0 bytes ...registry_repositories_with_quickstart_v13_1.png | Bin 51791 -> 0 bytes ...container_registry_repository_details_v13.0.png | Bin 32673 -> 0 bytes doc/user/packages/container_registry/index.md | 342 +- .../img/group_dependency_proxy.png | Bin 29334 -> 0 bytes doc/user/packages/dependency_proxy/index.md | 92 +- doc/user/packages/generic_packages/index.md | 139 + doc/user/packages/go_proxy/index.md | 2 +- doc/user/packages/index.md | 1 + .../img/maven_package_view_v12_6.png | Bin 83954 -> 0 bytes doc/user/packages/maven_repository/index.md | 98 +- doc/user/packages/npm_registry/index.md | 26 + doc/user/packages/nuget_repository/index.md | 38 +- doc/user/packages/package_registry/index.md | 12 +- doc/user/packages/pypi_repository/index.md | 35 +- doc/user/packages/workflows/monorepo.md | 28 +- doc/user/packages/workflows/project_registry.md | 18 +- doc/user/permissions.md | 75 +- doc/user/profile/account/create_accounts.md | 6 +- doc/user/profile/index.md | 9 +- doc/user/profile/personal_access_tokens.md | 6 +- doc/user/profile/preferences.md | 10 +- doc/user/project/autocomplete_characters.md | 4 + doc/user/project/badges.md | 2 +- doc/user/project/clusters/add_eks_clusters.md | 44 +- doc/user/project/clusters/add_remove_clusters.md | 87 +- doc/user/project/clusters/index.md | 82 +- doc/user/project/clusters/kubernetes_pod_logs.md | 3 +- doc/user/project/clusters/runbooks/index.md | 4 +- doc/user/project/clusters/securing.md | 2 +- doc/user/project/clusters/serverless/aws.md | 16 +- doc/user/project/clusters/serverless/index.md | 51 +- doc/user/project/code_intelligence.md | 6 +- doc/user/project/code_owners.md | 7 +- doc/user/project/deploy_boards.md | 4 +- doc/user/project/deploy_keys/index.md | 2 +- doc/user/project/description_templates.md | 7 +- doc/user/project/file_lock.md | 6 +- .../img/issue_board_default_lists_v13_4.png | Bin 0 -> 14866 bytes .../project/img/issue_board_welcome_message.png | Bin 13519 -> 0 bytes doc/user/project/img/labels_key_value_v12_1.png | Bin 55495 -> 0 bytes doc/user/project/img/labels_key_value_v13_5.png | Bin 0 -> 24731 bytes doc/user/project/img/labels_prioritized_v12_1.png | Bin 51751 -> 0 bytes doc/user/project/img/labels_prioritized_v13_5.png | Bin 0 -> 26117 bytes .../project/img/labels_subscriptions_v12_1.png | Bin 48037 -> 0 bytes .../project/img/labels_subscriptions_v13_5.png | Bin 0 -> 11375 bytes doc/user/project/import/bitbucket.md | 3 - doc/user/project/import/bitbucket_server.md | 46 +- doc/user/project/import/gemnasium.md | 2 +- doc/user/project/import/github.md | 39 +- .../project/import/img/manifest_status_v13_3.png | Bin 90811 -> 31313 bytes doc/user/project/import/index.md | 4 +- doc/user/project/import/manifest.md | 2 +- doc/user/project/import/perforce.md | 2 +- doc/user/project/import/repo_by_url.md | 4 +- doc/user/project/index.md | 6 +- doc/user/project/integrations/irker.md | 8 +- doc/user/project/integrations/jira.md | 4 +- doc/user/project/integrations/overview.md | 2 +- doc/user/project/integrations/prometheus.md | 44 +- .../integrations/prometheus_library/cloudwatch.md | 2 +- .../integrations/prometheus_library/haproxy.md | 2 +- .../integrations/prometheus_library/index.md | 2 +- .../integrations/prometheus_library/kubernetes.md | 4 +- .../integrations/prometheus_library/nginx.md | 2 +- .../prometheus_library/nginx_ingress.md | 6 +- .../prometheus_library/nginx_ingress_vts.md | 2 +- .../project/integrations/services_templates.md | 44 +- doc/user/project/integrations/slack.md | 2 +- doc/user/project/integrations/webhooks.md | 7 +- doc/user/project/issue_board.md | 97 +- doc/user/project/issues/crosslinking_issues.md | 2 +- doc/user/project/issues/design_management.md | 71 +- doc/user/project/issues/due_dates.md | 2 +- .../issues/img/design_todo_button_v13_4.png | Bin 166635 -> 0 bytes .../issues/img/design_todo_button_v13_5.png | Bin 0 -> 79978 bytes .../issues/img/designs_reordering_v13_3.gif | Bin 7068938 -> 0 bytes doc/user/project/issues/index.md | 5 +- doc/user/project/issues/issue_data_and_actions.md | 10 +- doc/user/project/issues/managing_issues.md | 1 + .../issues/multiple_assignees_for_issues.md | 2 - doc/user/project/issues/related_issues.md | 23 +- doc/user/project/labels.md | 68 +- .../merge_requests/accessibility_testing.md | 2 +- .../project/merge_requests/allow_collaboration.md | 5 +- doc/user/project/merge_requests/getting_started.md | 42 + .../merge_requests/img/commit_nav_v13_4.png | Bin 0 -> 21170 bytes .../merge_requests/load_performance_testing.md | 4 +- .../merge_requests/merge_request_approvals.md | 27 +- doc/user/project/merge_requests/revert_changes.md | 2 +- .../reviewing_and_managing_merge_requests.md | 4 +- .../project/merge_requests/squash_and_merge.md | 4 +- .../merge_requests/test_coverage_visualization.md | 101 +- .../work_in_progress_merge_requests.md | 13 +- .../milestones/burndown_and_burnup_charts.md | 142 + doc/user/project/milestones/burndown_charts.md | 88 +- .../img/burndown_and_burnup_charts_v13_5.png | Bin 0 -> 55865 bytes doc/user/project/milestones/img/burndown_chart.png | Bin 48403 -> 0 bytes .../milestones/img/burndown_chart_fixed_v13_5.png | Bin 0 -> 32250 bytes .../milestones/img/burndown_chart_legacy_v13_5.png | Bin 0 -> 28180 bytes .../milestones/img/burndown_chart_v13_5.png | Bin 0 -> 48403 bytes .../project/milestones/img/burnup_chart_v13_5.png | Bin 0 -> 29283 bytes doc/user/project/milestones/index.md | 4 +- doc/user/project/new_ci_build_permissions_model.md | 5 +- .../dns_concepts.md | 4 + .../custom_domains_ssl_tls_certification/index.md | 10 +- .../lets_encrypt_integration.md | 3 +- .../getting_started/new_or_existing_website.md | 2 +- .../getting_started/pages_forked_sample_project.md | 2 +- doc/user/project/pages/getting_started_part_one.md | 9 +- .../project/pages/getting_started_part_three.md | 4 + doc/user/project/pages/index.md | 21 + doc/user/project/pages/introduction.md | 11 +- .../project/pages/lets_encrypt_for_gitlab_pages.md | 5 +- doc/user/project/pages/pages_access_control.md | 17 +- doc/user/project/pages/redirects.md | 36 +- doc/user/project/protected_branches.md | 4 +- doc/user/project/quick_actions.md | 15 +- doc/user/project/releases/index.md | 38 +- doc/user/project/repository/forking_workflow.md | 2 +- .../img/repository_mirroring_push_settings.png | Bin 23955 -> 92335 bytes doc/user/project/repository/index.md | 4 +- .../repository/reducing_the_repo_size_using_git.md | 14 +- .../project/repository/repository_mirroring.md | 5 +- .../repository/x509_signed_commits/index.md | 2 +- .../requirements/img/requirement_create_v13_5.png | Bin 0 -> 89654 bytes .../requirements/img/requirement_view_v13_5.png | Bin 0 -> 90238 bytes .../requirements/img/requirements_list_v13_1.png | Bin 68346 -> 0 bytes .../requirements/img/requirements_list_v13_5.png | Bin 0 -> 81211 bytes doc/user/project/requirements/index.md | 41 +- doc/user/project/service_desk.md | 4 +- doc/user/project/settings/index.md | 20 +- doc/user/project/settings/project_access_tokens.md | 55 +- .../img/front_matter_ui_v13_4.png | Bin 0 -> 36431 bytes doc/user/project/static_site_editor/index.md | 169 +- doc/user/project/web_ide/index.md | 63 +- doc/user/project/wiki/img/wiki_sidebar.png | Bin 3178 -> 0 bytes doc/user/project/wiki/img/wiki_sidebar_v13_5.png | Bin 0 -> 16039 bytes doc/user/project/wiki/index.md | 46 +- doc/user/search/advanced_global_search.md | 4 +- doc/user/search/advanced_search_syntax.md | 9 +- doc/user/search/img/basic_search.png | Bin 0 -> 88486 bytes doc/user/search/img/basic_search_results.png | Bin 0 -> 19901 bytes doc/user/search/index.md | 83 +- doc/user/snippets.md | 46 +- doc/user/todos.md | 79 +- doc/user/upgrade_email_bypass.md | 4 +- doc/web_hooks/web_hooks.md | 5 - doc/workflow/README.md | 5 - doc/workflow/add-user/add-user.md | 5 - doc/workflow/authorization_for_merge_requests.md | 5 - doc/workflow/award_emoji.md | 5 - doc/workflow/cherry_pick_changes.md | 5 - doc/workflow/ff_merge.md | 5 - doc/workflow/file_finder.md | 5 - doc/workflow/forking_workflow.md | 5 - doc/workflow/git_annex.md | 5 - doc/workflow/git_lfs.md | 5 - doc/workflow/gitlab_flow.md | 5 - doc/workflow/groups.md | 5 - doc/workflow/importing/README.md | 5 - .../importing/import_projects_from_bitbucket.md | 5 - .../importing/import_projects_from_fogbugz.md | 5 - .../importing/import_projects_from_gitea.md | 5 - .../importing/import_projects_from_github.md | 5 - .../importing/import_projects_from_gitlab_com.md | 5 - doc/workflow/importing/migrating_from_svn.md | 5 - doc/workflow/issue_weight.md | 5 - doc/workflow/labels.md | 7 - doc/workflow/lfs/lfs_administration.md | 5 - .../lfs/manage_large_binaries_with_git_lfs.md | 5 - .../lfs/migrate_from_git_annex_to_git_lfs.md | 5 - doc/workflow/merge_request_approvals.md | 5 - doc/workflow/merge_requests.md | 5 - doc/workflow/merge_when_build_succeeds.md | 5 - doc/workflow/milestones.md | 5 - doc/workflow/notifications.md | 5 - doc/workflow/project_features.md | 5 - doc/workflow/protected_branches.md | 5 - doc/workflow/rebase_before_merge.md | 5 - doc/workflow/releases.md | 5 - doc/workflow/repository_mirroring.md | 5 - doc/workflow/revert_changes.md | 5 - doc/workflow/share_projects_with_other_groups.md | 5 - doc/workflow/share_with_group.md | 5 - doc/workflow/shortcuts.md | 5 - doc/workflow/time_tracking.md | 5 - doc/workflow/timezone.md | 5 - doc/workflow/todos.md | 5 - doc/workflow/web_editor.md | 5 - doc/workflow/wip_merge_requests.md | 5 - doc/workflow/workflow.md | 5 - 965 files changed, 26427 insertions(+), 12595 deletions(-) create mode 100644 doc/.vale/gitlab/Admin.yml create mode 100644 doc/.vale/gitlab/InclusionAbleism.yml create mode 100644 doc/.vale/gitlab/InclusionCultural.yml create mode 100644 doc/.vale/gitlab/InclusionGender.yml create mode 100644 doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md create mode 100644 doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md create mode 100644 doc/administration/geo/replication/img/geo-ha-diagram.png delete mode 100644 doc/administration/high_availability/README.md delete mode 100644 doc/administration/high_availability/alpha_database.md delete mode 100644 doc/administration/high_availability/consul.md delete mode 100644 doc/administration/high_availability/database.md delete mode 100644 doc/administration/high_availability/gitaly.md delete mode 100644 doc/administration/high_availability/gitlab.md delete mode 100644 doc/administration/high_availability/img/fully-distributed.png delete mode 100644 doc/administration/high_availability/img/geo-ha-diagram.png delete mode 100644 doc/administration/high_availability/img/horizontal.png delete mode 100644 doc/administration/high_availability/img/hybrid.png delete mode 100644 doc/administration/high_availability/load_balancer.md delete mode 100644 doc/administration/high_availability/monitoring_node.md delete mode 100644 doc/administration/high_availability/nfs.md delete mode 100644 doc/administration/high_availability/nfs_host_client_setup.md delete mode 100644 doc/administration/high_availability/object_storage.md delete mode 100644 doc/administration/high_availability/pgbouncer.md delete mode 100644 doc/administration/high_availability/redis.md delete mode 100644 doc/administration/high_availability/redis_source.md delete mode 100644 doc/administration/high_availability/sidekiq.md create mode 100644 doc/administration/operations/rails_console.md create mode 100644 doc/administration/read_only_gitlab.md create mode 100644 doc/api/experiments.md create mode 100644 doc/api/group_iterations.md create mode 100644 doc/api/iterations.md create mode 100644 doc/architecture/blueprints/cloud_native_build_logs/index.md create mode 100644 doc/architecture/blueprints/cloud_native_gitlab_pages/index.md create mode 100644 doc/architecture/blueprints/feature_flags_development/index.md create mode 100644 doc/architecture/index.md delete mode 100644 doc/articles/artifactory_and_gitlab/index.md delete mode 100644 doc/articles/how_to_configure_ldap_gitlab_ce/index.md delete mode 100644 doc/articles/how_to_configure_ldap_gitlab_ee/index.md delete mode 100644 doc/articles/how_to_install_git/index.md delete mode 100644 doc/articles/index.md delete mode 100644 doc/articles/laravel_with_gitlab_and_envoy/index.md delete mode 100644 doc/articles/numerous_undo_possibilities_in_git/index.md delete mode 100644 doc/articles/openshift_and_gitlab/index.md delete mode 100644 doc/articles/runner_autoscale_aws/index.md create mode 100644 doc/ci/img/cf_ec2_diagram_v13_5.png create mode 100644 doc/ci/img/gitlab_vault_workflow_v13_4.png create mode 100644 doc/ci/pipelines/pipeline_artifacts.md delete mode 100644 doc/ci/review_apps/img/toolbar_feeback_form.png create mode 100644 doc/ci/review_apps/img/toolbar_feedback_form_v13_5.png create mode 100644 doc/ci/yaml/img/ci_config_visualization_hover_v13_5.png create mode 100644 doc/ci/yaml/img/ci_config_visualization_v13_5.png create mode 100644 doc/ci/yaml/visualization.md delete mode 100644 doc/container_registry/README.md delete mode 100644 doc/container_registry/troubleshooting.md create mode 100644 doc/development/database/client_side_connection_pool.md create mode 100644 doc/development/database/setting_multiple_values.md create mode 100644 doc/development/database/table_partitioning.md create mode 100644 doc/development/documentation/graphql_styleguide.md create mode 100644 doc/development/documentation/restful_api_styleguide.md create mode 100644 doc/development/fe_guide/keyboard_shortcuts.md create mode 100644 doc/development/product_analytics/event_dictionary.md create mode 100644 doc/development/product_analytics/index.md create mode 100644 doc/development/product_analytics/snowplow.md create mode 100644 doc/development/product_analytics/usage_ping.md create mode 100644 doc/development/wikis.md delete mode 100644 doc/getting-started/subscription.md delete mode 100644 doc/git_hooks/git_hooks.md delete mode 100644 doc/gitlab-geo/README.md delete mode 100644 doc/gitlab-geo/after_setup.md delete mode 100644 doc/gitlab-geo/bring-primary-back.md delete mode 100644 doc/gitlab-geo/configuration.md delete mode 100644 doc/gitlab-geo/configuration_source.md delete mode 100644 doc/gitlab-geo/database.md delete mode 100644 doc/gitlab-geo/database_source.md delete mode 100644 doc/gitlab-geo/disaster-recovery.md delete mode 100644 doc/gitlab-geo/docker_registry.md delete mode 100644 doc/gitlab-geo/faq.md delete mode 100644 doc/gitlab-geo/ha.md delete mode 100644 doc/gitlab-geo/object_storage.md delete mode 100644 doc/gitlab-geo/planned-failover.md delete mode 100644 doc/gitlab-geo/security-review.md delete mode 100644 doc/gitlab-geo/ssh.md delete mode 100644 doc/gitlab-geo/troubleshooting.md delete mode 100644 doc/gitlab-geo/tuning.md delete mode 100644 doc/gitlab-geo/updating_the_geo_nodes.md delete mode 100644 doc/gitlab-geo/using_a_geo_server.md delete mode 100644 doc/hooks/custom_hooks.md delete mode 100644 doc/incoming_email/README.md delete mode 100644 doc/incoming_email/postfix.md delete mode 100644 doc/logs/logs.md create mode 100644 doc/operations/incident_management/alert_integrations.md create mode 100644 doc/operations/incident_management/alert_notifications.md create mode 100644 doc/operations/incident_management/img/alert_detail_activity_feed_v13_5.png create mode 100644 doc/operations/incident_management/img/incident_highlight_bar_v13_5.png delete mode 100644 doc/operations/incident_management/img/incident_list_v13_4.png create mode 100644 doc/operations/incident_management/img/incident_list_v13_5.png create mode 100644 doc/operations/incident_management/img/incident_sla_settings_v13_5.png create mode 100644 doc/operations/incident_management/img/integrations_list_v13_5.png create mode 100644 doc/operations/incident_management/img/link_runbooks_to_alerts_v13_5.png create mode 100644 doc/operations/incident_management/img/timeline_view_toggle_v13_5.png create mode 100644 doc/operations/incident_management/integrations.md delete mode 100644 doc/pages/README.md delete mode 100644 doc/pages/administration.md delete mode 100644 doc/pages/getting_started_part_one.md delete mode 100644 doc/pages/getting_started_part_three.md delete mode 100644 doc/pages/getting_started_part_two.md delete mode 100644 doc/profile/README.md delete mode 100644 doc/profile/preferences.md delete mode 100644 doc/profile/two_factor_authentication.md delete mode 100644 doc/project_services/bamboo.md delete mode 100644 doc/project_services/bugzilla.md delete mode 100644 doc/project_services/emails_on_push.md delete mode 100644 doc/project_services/hipchat.md delete mode 100644 doc/project_services/irker.md delete mode 100644 doc/project_services/jira.md delete mode 100644 doc/project_services/kubernetes.md delete mode 100644 doc/project_services/mattermost.md delete mode 100644 doc/project_services/mattermost_slash_commands.md delete mode 100644 doc/project_services/project_services.md delete mode 100644 doc/project_services/redmine.md delete mode 100644 doc/project_services/services_templates.md delete mode 100644 doc/project_services/slack.md delete mode 100644 doc/project_services/slack_slash_commands.md create mode 100644 doc/topics/autodevops/upgrading_auto_deploy_dependencies.md create mode 100644 doc/topics/git/git_rebase.md create mode 100644 doc/topics/git/img/git_rebase_v13_5.png delete mode 100644 doc/update/10.0-ce-to-ee.md delete mode 100644 doc/update/10.0-to-10.1.md delete mode 100644 doc/update/10.1-ce-to-ee.md delete mode 100644 doc/update/10.1-to-10.2.md delete mode 100644 doc/update/10.2-ce-to-ee.md delete mode 100644 doc/update/10.2-to-10.3.md delete mode 100644 doc/update/10.3-ce-to-ee.md delete mode 100644 doc/update/10.3-to-10.4.md delete mode 100644 doc/update/10.4-ce-to-ee.md delete mode 100644 doc/update/10.4-to-10.5.md delete mode 100644 doc/update/10.5-ce-to-ee.md delete mode 100644 doc/update/10.5-to-10.6.md delete mode 100644 doc/update/10.6-ce-to-ee.md delete mode 100644 doc/update/10.6-to-10.7.md delete mode 100644 doc/update/10.7-ce-to-ee.md delete mode 100644 doc/update/10.7-to-10.8.md delete mode 100644 doc/update/10.8-ce-to-ee.md delete mode 100644 doc/update/10.8-to-11.0.md delete mode 100644 doc/update/11.0-ce-to-ee.md delete mode 100644 doc/update/11.0-to-11.1.md delete mode 100644 doc/update/11.1-ce-to-ee.md delete mode 100644 doc/update/11.1-to-11.2.md delete mode 100644 doc/update/11.2-ce-to-ee.md delete mode 100644 doc/update/11.2-to-11.3.md delete mode 100644 doc/update/11.3-ce-to-ee.md delete mode 100644 doc/update/11.3-to-11.4.md delete mode 100644 doc/update/11.4-ce-to-ee.md delete mode 100644 doc/update/11.4-to-11.5.md delete mode 100644 doc/update/11.5-ce-to-ee.md delete mode 100644 doc/update/11.5-to-11.6.md delete mode 100644 doc/update/11.6-ce-to-ee.md delete mode 100644 doc/update/11.6-to-11.7.md delete mode 100644 doc/update/11.7-ce-to-ee.md delete mode 100644 doc/update/11.7-to-11.8.md delete mode 100644 doc/update/11.8-ce-to-ee.md delete mode 100644 doc/update/2.6-to-3.0.md delete mode 100644 doc/update/2.9-to-3.0.md delete mode 100644 doc/update/3.0-to-3.1.md delete mode 100644 doc/update/3.1-to-4.0.md delete mode 100644 doc/update/4.0-to-4.1.md delete mode 100644 doc/update/4.1-to-4.2.md delete mode 100644 doc/update/4.2-to-5.0.md delete mode 100644 doc/update/5.0-to-5.1.md delete mode 100644 doc/update/5.1-to-5.2.md delete mode 100644 doc/update/5.1-to-5.4.md delete mode 100644 doc/update/5.1-to-6.0.md delete mode 100644 doc/update/5.2-to-5.3.md delete mode 100644 doc/update/5.3-to-5.4.md delete mode 100644 doc/update/5.4-to-6.0.md delete mode 100644 doc/update/6.0-ce-to-ee.md delete mode 100644 doc/update/6.0-to-6.1.md delete mode 100644 doc/update/6.1-ce-to-ee.md delete mode 100644 doc/update/6.1-to-6.2.md delete mode 100644 doc/update/6.2-ce-to-ee.md delete mode 100644 doc/update/6.2-to-6.3.md delete mode 100644 doc/update/6.3-ce-to-ee.md delete mode 100644 doc/update/6.3-to-6.4.md delete mode 100644 doc/update/6.4-ce-to-ee.md delete mode 100644 doc/update/6.4-to-6.5.md delete mode 100644 doc/update/6.5-ce-to-ee.md delete mode 100644 doc/update/6.5-to-6.6.md delete mode 100644 doc/update/6.6-ce-to-ee.md delete mode 100644 doc/update/6.6-to-6.7.md delete mode 100644 doc/update/6.7-ce-to-ee.md delete mode 100644 doc/update/6.7-to-6.8.md delete mode 100644 doc/update/6.8-ce-to-ee.md delete mode 100644 doc/update/6.8-to-6.9.md delete mode 100644 doc/update/6.9-ce-to-ee.md delete mode 100644 doc/update/6.9-to-7.0.md delete mode 100644 doc/update/6.x-or-7.x-to-7.14.md delete mode 100644 doc/update/7.0-ce-to-ee.md delete mode 100644 doc/update/7.0-to-7.1.md delete mode 100644 doc/update/7.1-ce-to-ee.md delete mode 100644 doc/update/7.1-to-7.2.md delete mode 100644 doc/update/7.10-ce-to-ee.md delete mode 100644 doc/update/7.10-to-7.11.md delete mode 100644 doc/update/7.11-ce-to-ee.md delete mode 100644 doc/update/7.11-to-7.12.md delete mode 100644 doc/update/7.12-ce-to-ee.md delete mode 100644 doc/update/7.12-to-7.13.md delete mode 100644 doc/update/7.13-ce-to-ee.md delete mode 100644 doc/update/7.13-to-7.14.md delete mode 100644 doc/update/7.14-ce-to-ee.md delete mode 100644 doc/update/7.14-to-8.0.md delete mode 100644 doc/update/7.2-to-7.3.md delete mode 100644 doc/update/7.3-ce-to-ee.md delete mode 100644 doc/update/7.3-to-7.4.md delete mode 100644 doc/update/7.4-ce-to-ee.md delete mode 100644 doc/update/7.4-to-7.5.md delete mode 100644 doc/update/7.5-ce-to-ee.md delete mode 100644 doc/update/7.5-to-7.6.md delete mode 100644 doc/update/7.6-ce-to-ee.md delete mode 100644 doc/update/7.6-to-7.7.md delete mode 100644 doc/update/7.7-ce-to-ee.md delete mode 100644 doc/update/7.7-to-7.8.md delete mode 100644 doc/update/7.8-ce-to-ee.md delete mode 100644 doc/update/7.8-to-7.9.md delete mode 100644 doc/update/7.9-ce-to-ee.md delete mode 100644 doc/update/7.9-to-7.10.md delete mode 100644 doc/update/8.0-ce-to-ee.md delete mode 100644 doc/update/8.0-to-8.1.md delete mode 100644 doc/update/8.1-ce-to-ee.md delete mode 100644 doc/update/8.1-to-8.2.md delete mode 100644 doc/update/8.10-ce-to-ee.md delete mode 100644 doc/update/8.10-to-8.11.md delete mode 100644 doc/update/8.11-ce-to-ee.md delete mode 100644 doc/update/8.11-to-8.12.md delete mode 100644 doc/update/8.12-ce-to-ee.md delete mode 100644 doc/update/8.12-to-8.13.md delete mode 100644 doc/update/8.13-ce-to-ee.md delete mode 100644 doc/update/8.13-to-8.14.md delete mode 100644 doc/update/8.14-ce-to-ee.md delete mode 100644 doc/update/8.14-to-8.15.md delete mode 100644 doc/update/8.15-ce-to-ee.md delete mode 100644 doc/update/8.15-to-8.16.md delete mode 100644 doc/update/8.16-ce-to-ee.md delete mode 100644 doc/update/8.16-to-8.17.md delete mode 100644 doc/update/8.17-ce-to-ee.md delete mode 100644 doc/update/8.17-to-9.0.md delete mode 100644 doc/update/8.2-ce-to-ee.md delete mode 100644 doc/update/8.2-to-8.3.md delete mode 100644 doc/update/8.3-ce-to-ee.md delete mode 100644 doc/update/8.3-to-8.4.md delete mode 100644 doc/update/8.4-ce-to-ee.md delete mode 100644 doc/update/8.4-to-8.5.md delete mode 100644 doc/update/8.5-ce-to-ee.md delete mode 100644 doc/update/8.5-to-8.6.md delete mode 100644 doc/update/8.6-ce-to-ee.md delete mode 100644 doc/update/8.6-to-8.7.md delete mode 100644 doc/update/8.7-ce-to-ee.md delete mode 100644 doc/update/8.7-to-8.8.md delete mode 100644 doc/update/8.8-ce-to-ee.md delete mode 100644 doc/update/8.8-to-8.9.md delete mode 100644 doc/update/8.9-ce-to-ee.md delete mode 100644 doc/update/8.9-to-8.10.md delete mode 100644 doc/update/9.0-ce-to-ee.md delete mode 100644 doc/update/9.0-to-9.1.md delete mode 100644 doc/update/9.1-ce-to-ee.md delete mode 100644 doc/update/9.1-to-9.2.md delete mode 100644 doc/update/9.2-ce-to-ee.md delete mode 100644 doc/update/9.2-to-9.3.md delete mode 100644 doc/update/9.3-ce-to-ee.md delete mode 100644 doc/update/9.3-to-9.4.md delete mode 100644 doc/update/9.4-ce-to-ee.md delete mode 100644 doc/update/9.4-to-9.5.md delete mode 100644 doc/update/9.5-ce-to-ee.md delete mode 100644 doc/update/9.5-to-10.0.md create mode 100644 doc/user/admin_area/analytics/instance_statistics.md create mode 100644 doc/user/admin_area/approving_users.md delete mode 100644 doc/user/admin_area/img/admin_wrench.png create mode 100644 doc/user/admin_area/img/credentials_inventory_ssh_keys_v13_5.png delete mode 100644 doc/user/admin_area/settings/img/email_confirmation_v12_7.png delete mode 100644 doc/user/admin_area/settings/img/gitaly_timeouts.png create mode 100644 doc/user/admin_area/settings/img/sign_up_restrictions_v13_5.png delete mode 100644 doc/user/application_security/dast/img/dast_v13_2.png create mode 100644 doc/user/application_security/dast/img/dast_v13_4.png create mode 100644 doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png create mode 100644 doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png delete mode 100644 doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png delete mode 100644 doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_2.png delete mode 100644 doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png create mode 100644 doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png create mode 100644 doc/user/clusters/cost_management.md create mode 100644 doc/user/clusters/img/kubecost_v13_5.png create mode 100644 doc/user/img/gitlab_snippet_v13_5.png create mode 100644 doc/user/packages/composer_repository/img/project_id_v13_5.png delete mode 100644 doc/user/packages/conan_repository/img/conan_package_view.png delete mode 100644 doc/user/packages/container_registry/img/container_registry_group_repositories_v13_1.png create mode 100644 doc/user/packages/container_registry/img/container_registry_hover_path_13_4.png delete mode 100644 doc/user/packages/container_registry/img/container_registry_repositories_v13_1.png delete mode 100644 doc/user/packages/container_registry/img/container_registry_repositories_with_quickstart_v13_1.png delete mode 100644 doc/user/packages/container_registry/img/container_registry_repository_details_v13.0.png delete mode 100644 doc/user/packages/dependency_proxy/img/group_dependency_proxy.png create mode 100644 doc/user/packages/generic_packages/index.md delete mode 100644 doc/user/packages/maven_repository/img/maven_package_view_v12_6.png create mode 100644 doc/user/project/img/issue_board_default_lists_v13_4.png delete mode 100644 doc/user/project/img/issue_board_welcome_message.png delete mode 100644 doc/user/project/img/labels_key_value_v12_1.png create mode 100644 doc/user/project/img/labels_key_value_v13_5.png delete mode 100644 doc/user/project/img/labels_prioritized_v12_1.png create mode 100644 doc/user/project/img/labels_prioritized_v13_5.png delete mode 100644 doc/user/project/img/labels_subscriptions_v12_1.png create mode 100644 doc/user/project/img/labels_subscriptions_v13_5.png delete mode 100644 doc/user/project/issues/img/design_todo_button_v13_4.png create mode 100644 doc/user/project/issues/img/design_todo_button_v13_5.png delete mode 100644 doc/user/project/issues/img/designs_reordering_v13_3.gif create mode 100644 doc/user/project/merge_requests/img/commit_nav_v13_4.png create mode 100644 doc/user/project/milestones/burndown_and_burnup_charts.md create mode 100644 doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png delete mode 100644 doc/user/project/milestones/img/burndown_chart.png create mode 100644 doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png create mode 100644 doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png create mode 100644 doc/user/project/milestones/img/burndown_chart_v13_5.png create mode 100644 doc/user/project/milestones/img/burnup_chart_v13_5.png create mode 100644 doc/user/project/requirements/img/requirement_create_v13_5.png create mode 100644 doc/user/project/requirements/img/requirement_view_v13_5.png delete mode 100644 doc/user/project/requirements/img/requirements_list_v13_1.png create mode 100644 doc/user/project/requirements/img/requirements_list_v13_5.png create mode 100644 doc/user/project/static_site_editor/img/front_matter_ui_v13_4.png delete mode 100644 doc/user/project/wiki/img/wiki_sidebar.png create mode 100644 doc/user/project/wiki/img/wiki_sidebar_v13_5.png create mode 100644 doc/user/search/img/basic_search.png create mode 100644 doc/user/search/img/basic_search_results.png delete mode 100644 doc/web_hooks/web_hooks.md delete mode 100644 doc/workflow/README.md delete mode 100644 doc/workflow/add-user/add-user.md delete mode 100644 doc/workflow/authorization_for_merge_requests.md delete mode 100644 doc/workflow/award_emoji.md delete mode 100644 doc/workflow/cherry_pick_changes.md delete mode 100644 doc/workflow/ff_merge.md delete mode 100644 doc/workflow/file_finder.md delete mode 100644 doc/workflow/forking_workflow.md delete mode 100644 doc/workflow/git_annex.md delete mode 100644 doc/workflow/git_lfs.md delete mode 100644 doc/workflow/gitlab_flow.md delete mode 100644 doc/workflow/groups.md delete mode 100644 doc/workflow/importing/README.md delete mode 100644 doc/workflow/importing/import_projects_from_bitbucket.md delete mode 100644 doc/workflow/importing/import_projects_from_fogbugz.md delete mode 100644 doc/workflow/importing/import_projects_from_gitea.md delete mode 100644 doc/workflow/importing/import_projects_from_github.md delete mode 100644 doc/workflow/importing/import_projects_from_gitlab_com.md delete mode 100644 doc/workflow/importing/migrating_from_svn.md delete mode 100644 doc/workflow/issue_weight.md delete mode 100644 doc/workflow/labels.md delete mode 100644 doc/workflow/lfs/lfs_administration.md delete mode 100644 doc/workflow/lfs/manage_large_binaries_with_git_lfs.md delete mode 100644 doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md delete mode 100644 doc/workflow/merge_request_approvals.md delete mode 100644 doc/workflow/merge_requests.md delete mode 100644 doc/workflow/merge_when_build_succeeds.md delete mode 100644 doc/workflow/milestones.md delete mode 100644 doc/workflow/notifications.md delete mode 100644 doc/workflow/project_features.md delete mode 100644 doc/workflow/protected_branches.md delete mode 100644 doc/workflow/rebase_before_merge.md delete mode 100644 doc/workflow/releases.md delete mode 100644 doc/workflow/repository_mirroring.md delete mode 100644 doc/workflow/revert_changes.md delete mode 100644 doc/workflow/share_projects_with_other_groups.md delete mode 100644 doc/workflow/share_with_group.md delete mode 100644 doc/workflow/shortcuts.md delete mode 100644 doc/workflow/time_tracking.md delete mode 100644 doc/workflow/timezone.md delete mode 100644 doc/workflow/todos.md delete mode 100644 doc/workflow/web_editor.md delete mode 100644 doc/workflow/wip_merge_requests.md delete mode 100644 doc/workflow/workflow.md (limited to 'doc') diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml index d26ce9810d7..53690138300 100644 --- a/doc/.vale/gitlab/Acronyms.yml +++ b/doc/.vale/gitlab/Acronyms.yml @@ -44,6 +44,7 @@ exceptions: - IBM - IDE - IID + - IMAP - IRC - ISO - JSON @@ -65,6 +66,7 @@ exceptions: - POST - PUT - RAM + - REST - RPC - RSA - RSS diff --git a/doc/.vale/gitlab/Admin.yml b/doc/.vale/gitlab/Admin.yml new file mode 100644 index 00000000000..27a703c30c3 --- /dev/null +++ b/doc/.vale/gitlab/Admin.yml @@ -0,0 +1,13 @@ +--- +# Warning: gitlab.Admin +# +# You should not use "admin", but "Admin Area" is OK. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use "administration", "administrator", "administer", or "Admin Area" instead of "admin" or "admin area".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html +level: warning +ignorecase: true +swap: + 'admin ?\w*': '(?:Admin Area|[Aa]dminist(ration|rator|er))' diff --git a/doc/.vale/gitlab/InclusionAbleism.yml b/doc/.vale/gitlab/InclusionAbleism.yml new file mode 100644 index 00000000000..29b26547130 --- /dev/null +++ b/doc/.vale/gitlab/InclusionAbleism.yml @@ -0,0 +1,14 @@ +--- +# Suggestion: gitlab.InclusionAbleism +# +# Suggests alternatives for words that foster ableism. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use inclusive language. Consider "%s" instead of "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language +level: suggestion +ignorecase: true +swap: + sanity (?:check|test): check for completeness + dummy: placeholder, sample, fake diff --git a/doc/.vale/gitlab/InclusionCultural.yml b/doc/.vale/gitlab/InclusionCultural.yml new file mode 100644 index 00000000000..5bfad84f100 --- /dev/null +++ b/doc/.vale/gitlab/InclusionCultural.yml @@ -0,0 +1,16 @@ +--- +# Warning: gitlab.InclusionCultural +# +# Suggests alternatives for words that are culturally inappropriate. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use inclusive language. Consider "%s" instead of "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language +level: warning +ignorecase: true +swap: + blacklist(?:ed|ing|s)?: denylist + whitelist(?:ed|ing|s)?: allowlist + master: primary, main + slave: secondary diff --git a/doc/.vale/gitlab/InclusionGender.yml b/doc/.vale/gitlab/InclusionGender.yml new file mode 100644 index 00000000000..389d76d7a24 --- /dev/null +++ b/doc/.vale/gitlab/InclusionGender.yml @@ -0,0 +1,18 @@ +--- +# Suggestion: gitlab.InclusionGender +# +# Suggests alternatives for words that are gender-specific. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use inclusive language. Consider "%s" instead of "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#inclusive-language +level: suggestion +ignorecase: true +swap: + mankind: humanity, people + manpower: GitLab team members + he: they + his: their + she: they + hers: their diff --git a/doc/.vale/gitlab/OutdatedVersions.yml b/doc/.vale/gitlab/OutdatedVersions.yml index 1bc0bf58f90..2ce61ee5798 100644 --- a/doc/.vale/gitlab/OutdatedVersions.yml +++ b/doc/.vale/gitlab/OutdatedVersions.yml @@ -7,7 +7,7 @@ extends: existence message: 'Can this reference to "%s" be refactored?' link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#importance-of-referencing-gitlab-versions-and-tiers -level: warning +level: suggestion nonword: true ignorecase: true tokens: diff --git a/doc/.vale/gitlab/SubstitutionWarning.yml b/doc/.vale/gitlab/SubstitutionWarning.yml index 5324a48e38c..68313a37e7d 100644 --- a/doc/.vale/gitlab/SubstitutionWarning.yml +++ b/doc/.vale/gitlab/SubstitutionWarning.yml @@ -11,8 +11,6 @@ link: https://about.gitlab.com/handbook/communication/#top-misused-terms level: warning ignorecase: true swap: - admin: administrator - blacklist(ed|ing)?: denylist code base: codebase config: configuration distro: distribution @@ -20,4 +18,3 @@ swap: filesystem: file system info: information repo: repository - whitelist(ed|ing)?: allowlist diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml index 77536ea0b33..704c64f1fbd 100644 --- a/doc/.vale/gitlab/Substitutions.yml +++ b/doc/.vale/gitlab/Substitutions.yml @@ -13,6 +13,7 @@ ignorecase: true swap: frontmatter: front matter GitLabber: GitLab team member + GitLab-shell: GitLab Shell gitlab omnibus: Omnibus GitLab param: parameter params: parameters diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index bf816afdfab..c0a85fc6b70 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -61,6 +61,7 @@ buildpacks bundler bundlers burndown +burnup cacheable CAS CentOS @@ -142,8 +143,10 @@ Facebook failover failovers failsafe +Falco fastlane favicon +Figma Filebeat Fio firewalled @@ -166,6 +169,7 @@ Gitleaks Gitter globals Gmail +Gollum Google Gosec Gradle @@ -220,6 +224,7 @@ Kibana Kinesis Knative Kramdown +Kubecost kubectl Kubernetes Kubesec @@ -253,6 +258,7 @@ memoize memoized memoizing Memorystore +mergeability mergeable Microsoft middleware @@ -275,6 +281,7 @@ mockups ModSecurity monorepo monorepos +multiline mutex nameserver nameservers @@ -298,6 +305,7 @@ OmniAuth onboarding OpenID OpenShift +Opsgenie Packagist parallelization parallelizations @@ -305,6 +313,7 @@ passwordless Patroni performant PgBouncer +Phabricator phaser phasers Pipfile @@ -345,6 +354,7 @@ Python Qualys Rackspace Raspbian +Rdoc reachability rebase rebased @@ -365,6 +375,8 @@ reindex reindexed reindexes reindexing +reinitialize +reinitializing relicensing remediations repmgr @@ -382,6 +394,7 @@ reusability reverified reverifies reverify +RHEL rollout rollouts rsync @@ -423,7 +436,10 @@ smartcard smartcards SMTP Sobelow +Solarized Sourcegraph +sparkline +sparklines spidering Splunk SpotBugs @@ -439,6 +455,8 @@ subfolder subfolders subgraph subgraphs +subkey +subkeys sublicense sublicensed sublicenses @@ -455,8 +473,10 @@ substring substrings subtree subtrees +sudo syslog tcpdump +Thanos Tiller timecop todos @@ -479,6 +499,7 @@ unarchived unarchives unarchiving unassign +unassigning unassigns uncheck unchecked @@ -510,6 +531,9 @@ unprioritized unprotect unprotected unprotects +unprovision +unprovisioned +unprovisions unpublish unpublished unpublishes diff --git a/doc/README.md b/doc/README.md index efae2cdd3ff..09638bb4ce8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -85,14 +85,14 @@ The following sections provide links to documentation for each DevOps stage: ### Manage -GitLab provides statistics and insight into ways you can maximize the value of GitLab in your organization. +GitLab provides statistics and insights into ways you can maximize the value of GitLab in your organization. The following documentation relates to the DevOps **Manage** stage: | Manage topics | Description | |:--------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [Authentication and
Authorization](administration/auth/README.md) **(CORE ONLY)** | Supported authentication and authorization providers. | -| [GitLab Value Stream Analytics](user/project/cycle_analytics.md) | Measure the time it takes to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have. | +| [GitLab Value Stream Analytics](user/analytics/value_stream_analytics.md) | Measure the time it takes to go from an [idea to production](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have. | | [Instance-level Analytics](user/admin_area/analytics/index.md) | Discover statistics on how many GitLab features you use and user activity. |
@@ -121,7 +121,7 @@ The following documentation relates to the DevOps **Plan** stage: | [Milestones](user/project/milestones/index.md) | Set milestones for delivery of issues and merge requests, with optional due date. | | [Project Issue Board](user/project/issue_board.md) | Display issues on a Scrum or Kanban board. | | [Quick Actions](user/project/quick_actions.md) | Shortcuts for common actions on issues or merge requests, replacing the need to click buttons or use dropdowns in GitLab's UI. | -| [Related Issues](user/project/issues/related_issues.md) **(STARTER)** | Create a relationship between issues. | +| [Related Issues](user/project/issues/related_issues.md) | Create a relationship between issues. | | [Requirements Management](user/project/requirements/index.md) **(ULTIMATE)** | Check your products against a set of criteria. | | [Roadmap](user/group/roadmap/index.md) **(ULTIMATE)** | Visualize epic timelines. | | [Service Desk](user/project/service_desk.md) | A simple way to allow people to create issues in your GitLab instance without needing their own user account. | @@ -218,7 +218,7 @@ The following documentation relates to the DevOps **Create** stage: | [GitLab GraphQL API](api/graphql/index.md) | Integrate with GitLab using our GraphQL API. | | [GitLab Integration](integration/README.md) | Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication. | | [GitLab Webhooks](user/project/integrations/webhooks.md) | Let GitLab notify you when new code has been pushed to your project. | -| [Jira Development Panel](integration/jira_development_panel.md) **(PREMIUM)** | See GitLab information in the Jira Development Panel. | +| [Jira Development Panel](integration/jira_development_panel.md) | See GitLab information in the Jira Development Panel. | | [Integrations](user/project/integrations/overview.md) | Integrate a project with external services, such as CI and chat. | | [Trello Power-Up](integration/trello_power_up.md) | Integrate with GitLab's Trello Power-Up. | @@ -267,9 +267,7 @@ The following documentation relates to the DevOps **Package** stage: |:----------------------------------------------------------------|:-------------------------------------------------------| | [Container Registry](user/packages/container_registry/index.md) | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. | | [Dependency Proxy](user/packages/dependency_proxy/index.md) **(PREMIUM)** | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. | -| [Conan Repository](user/packages/conan_repository/index.md) | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | -| [Maven Repository](user/packages/maven_repository/index.md) | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | -| [NPM Registry](user/packages/npm_registry/index.md) | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | +| [Package Registry](user/packages/package_registry/index.md) | Use GitLab as a private or public registry for a variety of common package managers, including [NPM](user/packages/npm_registry/index.md), [Maven](user/packages/maven_repository/index.md), [PyPI](user/packages/pypi_repository/index.md), and others. You can also store generic files. |
@@ -295,7 +293,7 @@ The following documentation relates to the DevOps **Secure** stage: | [Dependency Scanning](user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](user/application_security/dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | | [Group Security Dashboard](user/application_security/security_dashboard/index.md#group-security-dashboard) **(ULTIMATE)** | View vulnerabilities in all the projects in a group and its subgroups. | -| [Instance Security Dashboard](user/application_security/security_dashboard/index.md#instance-security-dashboard) **(ULTIMATE)** | View vulnerabilities in all the projects you're interested in. | +| [Instance Security Center](user/application_security/security_dashboard/index.md#instance-security-center) **(ULTIMATE)** | View vulnerabilities in all the projects you're interested in. | | [License Compliance](user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | | [Pipeline Security](user/application_security/security_dashboard/index.md#pipeline-security) **(ULTIMATE)** | View the security reports for your project's pipelines. | | [Project Security Dashboard](user/application_security/security_dashboard/index.md#project-security-dashboard) **(ULTIMATE)** | View the latest security reports for your project. | diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 099346b2b0b..ac972e2e33e 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab offers a way to view the changes made within the GitLab server for owners and administrators on a [paid plan](https://about.gitlab.com/pricing/). GitLab system administrators can also take advantage of the logs located on the -filesystem. See [the logs system documentation](logs.md) for more details. +file system. See [the logs system documentation](logs.md) for more details. ## Overview @@ -108,7 +108,7 @@ Server-wide audit logging introduces the ability to observe user actions across the entire instance of your GitLab server, making it easy to understand who changed what and when for audit purposes. -To view the server-wide admin log, visit **Admin Area > Monitoring > Audit Log**. +To view the server-wide administrator log, visit **Admin Area > Monitoring > Audit Log**. In addition to the group and project events, the following user actions are also recorded: @@ -126,6 +126,7 @@ recorded: - User was added ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8) - User was blocked via Admin Area ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/251) in GitLab 12.8) - User was blocked via API ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25872) in GitLab 12.9) +- Failed second-factor authentication attempt ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16826) in GitLab 13.5) It's possible to filter particular actions by choosing an audit data type from the filter dropdown box. You can further filter by specific group, project, or user @@ -151,7 +152,7 @@ on adding these events into GitLab: The current architecture of audit events is not prepared to receive a very high amount of records. It may make the user interface for your project or audit logs very busy, and the disk space consumed by the -`audit_events` PostgreSQL table will increase considerably. It's disabled by default +`audit_events` PostgreSQL table may increase considerably. It's disabled by default to prevent performance degradations on GitLab instances with very high Git write traffic. In an upcoming release, Audit Logs for Git push events will be enabled @@ -172,6 +173,7 @@ the steps bellow. ```ruby Feature.enable(:repository_push_audit_event) + ``` ## Export to CSV **(PREMIUM ONLY)** @@ -183,6 +185,7 @@ the steps bellow. CAUTION: **Warning:** This feature might not be available to you. Check the **version history** note above for details. +If available, you can enable it with a [feature flag](#enable-or-disable-audit-log-export-to-csv). Export to CSV allows customers to export the current filter view of your audit log as a CSV file, diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index ace210183b2..c41065abd17 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -1,34 +1,39 @@ -# Auditor users **(PREMIUM ONLY)** +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- ->[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/998) in [GitLab Premium](https://about.gitlab.com/pricing/) 8.17. +# Auditor users **(PREMIUM ONLY)** Auditor users are given read-only access to all projects, groups, and other resources on the GitLab instance. ## Overview -Auditor users can have full access to their own resources (projects, groups, -snippets, etc.), and read-only access to **all** other resources, except the -Admin Area. To put another way, they are just regular users (who can be added -to projects, create personal snippets, create milestones on their groups, etc.) -who also happen to have read-only access to all projects on the system that -they haven't been explicitly [given access](../user/permissions.md) to. +Auditor users are able to have both full access to their own resources +(including projects, groups, and snippets) and read-only access to _all_ other +resources, except the [Admin Area](../user/admin_area/index.md). These user +accounts are regular users who can be added to projects, create personal +snippets, and create milestones on their groups, while also having read-only +access to all projects on the server to which they haven't been explicitly +[given access](../user/permissions.md). The Auditor role is _not_ a read-only version of the Admin role. Auditor users -will not be able to access the project/group settings pages, or the Admin Area. +can't access the project or group settings pages, or the Admin Area. -To sum up, assuming you have logged-in as an Auditor user: +Assuming you have signed in as an Auditor user: - For a project the Auditor is not member of, the Auditor should have - read-only access. If the project is public or internal, they would have the - same access as the users that are not members of that project/group. + read-only access. If the project is public or internal, they have the same + access as users that aren't members of that project or group. - For a project the Auditor owns, the Auditor should have full access to everything. -- For a project the Auditor has been added to as a member, the Auditor should - have the same access as the [permissions](../user/permissions.md) they were given to. For example, if - they were added as a Developer, they could then push commits or comment on - issues. -- The Auditor cannot view the Admin Area, or perform any admin actions. +- For a project to which the Auditor is added as a member, the Auditor should + have the same access as their given [permissions](../user/permissions.md). + For example, if they were added as a Developer, they can push commits or + comment on issues. +- The Auditor can't view the Admin Area, or perform any admin actions. For more information about what an Auditor can or can't do, see the [Permissions and restrictions of an Auditor user](#permissions-and-restrictions-of-an-auditor-user) @@ -36,33 +41,37 @@ section. ## Use cases -1. Your compliance department wants to run tests against the entire GitLab base - to ensure users are complying with password, credit card, and other sensitive - data policies. With Auditor users, this can be achieved very easily without - resulting to tactics like giving a user admin rights or having to use the API - to add them to all projects. -1. If particular users need visibility or access to most of all projects in - your GitLab instance, instead of manually adding the user to all projects, - you can simply create an Auditor user and share the credentials with those - that you want to grant access to. +The following use cases describe some situations where Auditor users could be +helpful: + +- Your compliance department wants to run tests against the entire GitLab base + to ensure users are complying with password, credit card, and other sensitive + data policies. With Auditor users, this can be achieved very without having + to give them user admin rights or using the API to add them to all projects. +- If particular users need visibility or access to most of all projects in + your GitLab instance, instead of manually adding the user to all projects, + you can create an Auditor user and then share the credentials with those users + to which you want to grant access. ## Adding an Auditor user +To create a new Auditor user: + 1. Create a new user or edit an existing one by navigating to - **Admin Area > Users**. You will find the option of the access level under + **Admin Area > Users**. You will find the option of the access level in the 'Access' section. ![Admin Area Form](img/auditor_access_form.png) -1. Click **Save changes** or **Create user** for the changes to take effect. +1. Select **Save changes** or **Create user** for the changes to take effect. -To revoke the Auditor permissions from a user, simply make them a Regular user -following the same steps as above. +To revoke Auditor permissions from a user, make them a regular user by +following the previous steps. ## Permissions and restrictions of an Auditor user An Auditor user should be able to access all projects and groups of a GitLab -instance, with the following permissions/restrictions: +instance, with the following permissions and restrictions: - Has read-only access to the API - Can access projects that are: @@ -70,15 +79,15 @@ instance, with the following permissions/restrictions: - Public - Internal - Can read all files in a repository -- Can read issues / MRs +- Can read issues and MRs - Can read project snippets - Cannot be Admin and Auditor at the same time - Cannot access the Admin Area -- In a group / project they're not a member of: +- In a group or project they're not a member of: - Cannot access project settings - Cannot access group settings - Cannot commit to repository - - Cannot create / comment on issues / MRs - - Cannot create/modify files from the Web UI + - Cannot create or comment on issues and MRs + - Cannot create or modify files from the Web UI - Cannot merge a merge request - Cannot create project snippets diff --git a/doc/administration/auth/README.md b/doc/administration/auth/README.md index 926a4abab7d..cf82454cfd2 100644 --- a/doc/administration/auth/README.md +++ b/doc/administration/auth/README.md @@ -18,7 +18,7 @@ providers: - [Azure](../../integration/azure.md) - [Bitbucket Cloud](../../integration/bitbucket.md) - [CAS](../../integration/cas.md) -- [Crowd](../../integration/crowd.md) +- [Crowd](crowd.md) - [Facebook](../../integration/facebook.md) - [GitHub](../../integration/github.md) - [GitLab.com](../../integration/gitlab.md) diff --git a/doc/administration/auth/ldap/index.md b/doc/administration/auth/ldap/index.md index 1dac098ec0c..3df85babc94 100644 --- a/doc/administration/auth/ldap/index.md +++ b/doc/administration/auth/ldap/index.md @@ -12,6 +12,7 @@ GitLab integrates with LDAP to support user authentication. This integration works with most LDAP-compliant directory servers, including: - Microsoft Active Directory + - [Microsoft Active Directory Trusts](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) are not supported. - Apple Open Directory - Open LDAP - 389 Server @@ -21,9 +22,6 @@ Users added through LDAP take a [licensed seat](../../../subscriptions/self_mana GitLab Enterprise Editions (EE) include enhanced integration, including group membership syncing as well as multiple LDAP servers support. -NOTE: **Note:** -[Microsoft Active Directory Trusts](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10)) are not supported. - ## Overview [LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) @@ -55,9 +53,8 @@ are already logged in or are using Git over SSH will still be able to access GitLab for up to one hour. Manually block the user in the GitLab Admin Area to immediately block all access. -NOTE: **Note:** GitLab Enterprise Edition Starter supports a -[configurable sync time](#adjusting-ldap-user-sync-schedule). +[configurable sync time](#adjusting-ldap-user-sync-schedule). **(STARTER)** ## Git password authentication **(CORE ONLY)** @@ -100,7 +97,6 @@ library. `start_tls` corresponds to StartTLS, not to be confused with regular TL Normally, if you specify `simple_tls` it will be on port 636, while `start_tls` (StartTLS) would be on port 389. `plain` also operates on port 389. Removed values: `tls` was replaced with `start_tls` and `ssl` was replaced with `simple_tls`. -NOTE: **Note:** LDAP users must have an email address set, regardless of whether it is used to sign-in. ### Example Configurations **(CORE ONLY)** @@ -120,7 +116,6 @@ gitlab_rails['ldap_servers'] = { 'verify_certificates' => true, 'bind_dn' => '_the_full_dn_of_the_user_you_will_bind_with', 'password' => '_the_password_of_the_bind_user', - 'encryption' => 'plain', 'verify_certificates' => true, 'tls_options' => { 'ca_file' => '', @@ -430,8 +425,7 @@ gitlab_rails['ldap_servers'] = { } ``` -NOTE: **Note:** -Any number of LDAP servers can be configured. However, make sure to use a unique naming convention for the `label` section of each entry as this will be the display name of the tab shown on the sign-in page. +If you configure multiple LDAP servers, use a unique naming convention for the `label` section of each entry. That label is used as the display name of the tab shown on the sign-in page. ## User sync **(STARTER ONLY)** @@ -445,11 +439,10 @@ The process executes the following access checks: blocked/disabled state). This will only be checked if `active_directory: true` is set in the LDAP configuration. -NOTE: **Note:** In Active Directory, a user is marked as disabled/blocked if the user account control attribute (`userAccountControl:1.2.840.113556.1.4.803`) -has bit 2 set. See -for more information. +has bit 2 set. +For more information, see The user will be set to `ldap_blocked` state in GitLab if the above conditions fail. This means the user will not be able to sign-in or push/pull code. @@ -460,8 +453,10 @@ The process will also update the following user information: - If `sync_ssh_keys` is set, SSH public keys. - If Kerberos is enabled, Kerberos identity. -NOTE: **Note:** -The LDAP sync process updates existing users while new users are created on first sign in. +The LDAP sync process: + +- Updates existing users. +- Creates new users on first sign in. ### Adjusting LDAP user sync schedule **(STARTER ONLY)** @@ -469,11 +464,13 @@ NOTE: **Note:** These are cron formatted values. You can use a crontab generator to create these values, for example . -By default, GitLab will run a worker once per day at 01:30 a.m. server time to +By default, GitLab runs a worker once per day at 01:30 a.m. server time to check and update GitLab users against LDAP. You can manually configure LDAP user sync times by setting the -following configuration values. The example below shows how to set LDAP user +following configuration values, in cron format. If needed, you can +use a [crontab generator](http://crontabgenerator.com). +The example below shows how to set LDAP user sync to run once every 12 hours at the top of the hour. **Omnibus installations** @@ -512,7 +509,7 @@ GitLab group membership to be automatically updated based on LDAP group members. The `group_base` configuration should be a base LDAP 'container', such as an 'organization' or 'organizational unit', that contains LDAP groups that should be available to GitLab. For example, `group_base` could be -`ou=groups,dc=example,dc=com`. In the config file it will look like the +`ou=groups,dc=example,dc=com`. In the configuration file it will look like the following. **Omnibus configuration** @@ -617,14 +614,12 @@ To enable it you need to: ### Adjusting LDAP group sync schedule **(STARTER ONLY)** -NOTE: **Note:** -These are cron formatted values. You can use a crontab generator to create -these values, for example [Crontab Generator](http://www.crontabgenerator.com/). - By default, GitLab runs a group sync process every hour, on the hour. +The values shown are in cron format. If needed, you can use a +[Crontab Generator](http://www.crontabgenerator.com). CAUTION: **Important:** -It's recommended that you do not start the sync process too frequently as this +Do not start the sync process too frequently as this could lead to multiple syncs running concurrently. This is primarily a concern for installations with a large number of LDAP users. Please review the [LDAP group sync benchmark metrics](#benchmarks) to see how @@ -727,7 +722,8 @@ Other LDAP servers should work, too. Active Directory also supports nested groups. Group sync will recursively resolve membership if `active_directory: true` is set in the configuration file. -NOTE: **Note:** +##### Nested group memberships + Nested group memberships are resolved only if the nested group is found within the configured `group_base`. For example, if GitLab sees a nested group with DN `cn=nested_group,ou=special_groups,dc=example,dc=com` but diff --git a/doc/administration/auth/ldap/ldap-troubleshooting.md b/doc/administration/auth/ldap/ldap-troubleshooting.md index 3d3ac124ac4..c6558bf1791 100644 --- a/doc/administration/auth/ldap/ldap-troubleshooting.md +++ b/doc/administration/auth/ldap/ldap-troubleshooting.md @@ -682,7 +682,7 @@ The rails console is a valuable tool to help debug LDAP problems. It allows you directly interact with the application by running commands and seeing how GitLab responds to them. -Please refer to [this guide](../../troubleshooting/debug.md#starting-a-rails-console-session) +Please refer to [this guide](../../operations/rails_console.md#starting-a-rails-console-session) for instructions on how to use the rails console. #### Enable debug output diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index 0ecf3ca090d..a696d0499a4 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index 237261f2567..44270283308 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Compliance features You can configure the following GitLab features to help ensure that your GitLab instance meets common compliance standards. Click a feature name for further documentation. diff --git a/doc/administration/consul.md b/doc/administration/consul.md index ae22d8bd4d0..4eed020c284 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/administration/database_load_balancing.md b/doc/administration/database_load_balancing.md index 36ef905fd90..e88f88a0427 100644 --- a/doc/administration/database_load_balancing.md +++ b/doc/administration/database_load_balancing.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Database Load Balancing **(PREMIUM ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1283) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0. @@ -128,7 +134,7 @@ production: disconnect_timeout: 120 ``` -Here the `discover:` section specifies the configuration details to use for +Here, the `discover:` section specifies the configuration details to use for service discovery. ### Configuration @@ -139,7 +145,7 @@ The following options can be set: |----------------------|---------------------------------------------------------------------------------------------------|-----------| | `nameserver` | The nameserver to use for looking up the DNS record. | localhost | | `record` | The record to look up. This option is required for service discovery to work. | | -| `record_type` | Optional record type to look up, this can be either A or SRV (since GitLab 12.3) | A | +| `record_type` | Optional record type to look up, this can be either A or SRV (GitLab 12.3 and later) | A | | `port` | The port of the nameserver. | 8600 | | `interval` | The minimum time in seconds between checking the DNS record. | 60 | | `disconnect_timeout` | The time in seconds after which an old connection is closed, after the list of hosts was updated. | 120 | diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md index d48a47e9645..25bfc3c132d 100644 --- a/doc/administration/environment_variables.md +++ b/doc/administration/environment_variables.md @@ -1,77 +1,75 @@ --- -stage: Verify -group: Continuous Integration +stage: Enablement +group: Distribution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- -# Environment Variables +# Environment variables GitLab exposes certain environment variables which can be used to override their defaults values. -People usually configure GitLab via `/etc/gitlab/gitlab.rb` for Omnibus +People usually configure GitLab with `/etc/gitlab/gitlab.rb` for Omnibus installations, or `gitlab.yml` for installations from source. -Below you will find the supported environment variables which you can use to -override certain values. +You can use the following environment variables to override certain values: ## Supported environment variables -Variable | Type | Description --------- | ---- | ----------- -`ENABLE_BOOTSNAP` | string | Enables Bootsnap for speeding up initial Rails boot (`1` to enable) -`GITLAB_CDN_HOST` | string | Sets the base URL for a CDN to serve static assets (e.g. `//mycdnsubdomain.fictional-cdn.com`) -`GITLAB_ROOT_PASSWORD` | string | Sets the password for the `root` user on installation -`GITLAB_HOST` | string | The full URL of the GitLab server (including `http://` or `https://`) -`RAILS_ENV` | string | The Rails environment; can be one of `production`, `development`, `staging` or `test` -`DATABASE_URL` | string | The database URL; is of the form: `postgresql://localhost/blog_development` -`GITLAB_EMAIL_FROM` | string | The e-mail address used in the "From" field in e-mails sent by GitLab -`GITLAB_EMAIL_DISPLAY_NAME` | string | The name used in the "From" field in e-mails sent by GitLab -`GITLAB_EMAIL_REPLY_TO` | string | The e-mail address used in the "Reply-To" field in e-mails sent by GitLab -`GITLAB_EMAIL_SUBJECT_SUFFIX` | string | The e-mail subject suffix used in e-mails sent by GitLab -`GITLAB_UNICORN_MEMORY_MIN` | integer | The minimum memory threshold (in bytes) for the Unicorn worker killer -`GITLAB_UNICORN_MEMORY_MAX` | integer | The maximum memory threshold (in bytes) for the Unicorn worker killer -`GITLAB_SHARED_RUNNERS_REGISTRATION_TOKEN` | string | Sets the initial registration token used for runners -`UNSTRUCTURED_RAILS_LOG` | string | Enables the unstructured log in addition to JSON logs (defaults to `true`) +| Variable | Type | Description | +|--------------------------------------------|---------|---------------------------------------------------------------------------------------------------------| +| `DATABASE_URL` | string | The database URL; is of the form: `postgresql://localhost/blog_development`. | +| `ENABLE_BOOTSNAP` | string | Enables Bootsnap for speeding up initial Rails boot (`1` to enable). | +| `GITLAB_CDN_HOST` | string | Sets the base URL for a CDN to serve static assets (for example, `//mycdnsubdomain.fictional-cdn.com`). | +| `GITLAB_EMAIL_DISPLAY_NAME` | string | The name used in the **From** field in emails sent by GitLab. | +| `GITLAB_EMAIL_FROM` | string | The email address used in the **From** field in emails sent by GitLab. | +| `GITLAB_EMAIL_REPLY_TO` | string | The email address used in the **Reply-To** field in emails sent by GitLab. | +| `GITLAB_EMAIL_SUBJECT_SUFFIX` | string | The email subject suffix used in emails sent by GitLab. | +| `GITLAB_HOST` | string | The full URL of the GitLab server (including `http://` or `https://`). | +| `GITLAB_ROOT_PASSWORD` | string | Sets the password for the `root` user on installation. | +| `GITLAB_SHARED_RUNNERS_REGISTRATION_TOKEN` | string | Sets the initial registration token used for runners. | +| `GITLAB_UNICORN_MEMORY_MAX` | integer | The maximum memory threshold (in bytes) for the [unicorn-worker-killer](operations/unicorn.md#unicorn-worker-killer). | +| `GITLAB_UNICORN_MEMORY_MIN` | integer | The minimum memory threshold (in bytes) for the [unicorn-worker-killer](operations/unicorn.md#unicorn-worker-killer). | +| `RAILS_ENV` | string | The Rails environment; can be one of `production`, `development`, `staging`, or `test`. | +| `UNSTRUCTURED_RAILS_LOG` | string | Enables the unstructured log in addition to JSON logs (defaults to `true`). | ## Complete database variables -The recommended way of specifying your database connection information is to set -the `DATABASE_URL` environment variable. This variable only holds connection -information (`adapter`, `database`, `username`, `password`, `host` and `port`), -but not behavior information (`encoding`, `pool`). If you don't want to use -`DATABASE_URL` and/or want to set database behavior information, you will have -to either: +The recommended method for specifying your database connection information is +to set the `DATABASE_URL` environment variable. This variable contains +connection information (`adapter`, `database`, `username`, `password`, `host`, +and `port`), but no behavior information (`encoding` or `pool`). If you don't +want to use `DATABASE_URL`, or want to set database behavior information, +either: -- copy our template file: `cp config/database.yml.env config/database.yml`, or -- set a value for some `GITLAB_DATABASE_XXX` variables +- Copy the template file, `cp config/database.yml.env config/database.yml`. +- Set a value for some `GITLAB_DATABASE_XXX` variables. The list of `GITLAB_DATABASE_XXX` variables that you can set is: -Variable | Default value | Overridden by `DATABASE_URL`? --------- | ------------- | ----------------------------- -`GITLAB_DATABASE_ADAPTER` | `postgresql` | Yes -`GITLAB_DATABASE_DATABASE` | `gitlab_#{ENV['RAILS_ENV']` | Yes -`GITLAB_DATABASE_USERNAME` | `root` | Yes -`GITLAB_DATABASE_PASSWORD` | None | Yes -`GITLAB_DATABASE_HOST` | `localhost` | Yes -`GITLAB_DATABASE_PORT` | `5432` | Yes -`GITLAB_DATABASE_ENCODING` | `unicode` | No -`GITLAB_DATABASE_POOL` | `10` | No +| Variable | Default value | Overridden by `DATABASE_URL`? | +|-----------------------------|--------------------------------|-------------------------------| +| `GITLAB_DATABASE_ADAPTER` | `postgresql` | **{check-circle}** Yes | +| `GITLAB_DATABASE_DATABASE` | `gitlab_#{ENV['RAILS_ENV']` | **{check-circle}** Yes | +| `GITLAB_DATABASE_ENCODING` | `unicode` | **{dotted-circle}** No | +| `GITLAB_DATABASE_HOST` | `localhost` | **{check-circle}** Yes | +| `GITLAB_DATABASE_PASSWORD` | _none_ | **{check-circle}** Yes | +| `GITLAB_DATABASE_POOL` | `10` | **{dotted-circle}** No | +| `GITLAB_DATABASE_PORT` | `5432` | **{check-circle}** Yes | +| `GITLAB_DATABASE_USERNAME` | `root` | **{check-circle}** Yes | ## Adding more variables -We welcome merge requests to make more settings configurable via variables. -Please make changes in the `config/initializers/1_settings.rb` file and stick -to the naming scheme `GITLAB_#{name in 1_settings.rb in upper case}`. +We welcome merge requests to make more settings configurable by using variables. +Make changes to the `config/initializers/1_settings.rb` file, and use the +naming scheme `GITLAB_#{name in 1_settings.rb in upper case}`. ## Omnibus configuration -To set environment variables, follow [these -instructions](https://docs.gitlab.com/omnibus/settings/environment-variables.html). +To set environment variables, follow [these instructions](https://docs.gitlab.com/omnibus/settings/environment-variables.html). It's possible to preconfigure the GitLab Docker image by adding the environment variable `GITLAB_OMNIBUS_CONFIG` to the `docker run` command. -For more information see the [Pre-configure Docker container](https://docs.gitlab.com/omnibus/docker/#pre-configure-docker-container) -section in the Omnibus documentation. +For more information, see the [Pre-configure Docker container](https://docs.gitlab.com/omnibus/docker/#pre-configure-docker-container) +section of the Omnibus GitLab documentation. diff --git a/doc/administration/feature_flags.md b/doc/administration/feature_flags.md index a8a14063f26..4129677f134 100644 --- a/doc/administration/feature_flags.md +++ b/doc/administration/feature_flags.md @@ -65,7 +65,7 @@ For installations from the source: sudo -u git -H bundle exec rails console -e production ``` -For details, see [starting a Rails console session](troubleshooting/debug.md#starting-a-rails-console-session). +For details, see [starting a Rails console session](operations/rails_console.md#starting-a-rails-console-session). ### Enable or disable the feature @@ -79,10 +79,10 @@ To enable a feature, run: Feature.enable(:) ``` -Example, to enable Evidence Collection: +Example, to enable a fictional feature flag named `my_awesome_feature`: ```ruby -Feature.enable(:release_evidence_collection) +Feature.enable(:my_awesome_feature) ``` To disable a feature, run: @@ -91,10 +91,10 @@ To disable a feature, run: Feature.disable(:) ``` -Example, to disable Evidence Collection: +Example, to disable a fictional feature flag named `my_awesome_feature`: ```ruby -Feature.disable(:release_evidence_collection) +Feature.disable(:my_awesome_feature) ``` Some feature flags can be enabled or disabled on a per project basis: @@ -112,18 +112,18 @@ Feature.enable(:product_analytics, Project.find(1234)) `Feature.enable` and `Feature.disable` always return `nil`, this is not an indication that the command failed: ```ruby -irb(main):001:0> Feature.enable(:release_evidence_collection) +irb(main):001:0> Feature.enable(:my_awesome_feature) => nil ``` -To check if a flag is enabled or disabled you can use `Feature.enabled?` or `Feature.disabled?`: +To check if a flag is enabled or disabled you can use `Feature.enabled?` or `Feature.disabled?`. For example, for a fictional feature flag named `my_awesome_feature`: ```ruby -Feature.enable(:release_evidence_collection) +Feature.enable(:my_awesome_feature) => nil -Feature.enabled?(:release_evidence_collection) +Feature.enabled?(:my_awesome_feature) => true -Feature.disabled?(:release_evidence_collection) +Feature.disabled?(:my_awesome_feature) => false ``` diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 8862776ee1b..32b3558a51f 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -11,11 +11,11 @@ Geo replicates your database, your Git repositories, and few other assets. We will support and replicate more data in the future, that will enable you to failover with minimal effort, in a disaster situation. -See [Geo current limitations](../index.md#current-limitations) for more information. +See [Geo limitations](../index.md#limitations) for more information. CAUTION: **Warning:** Disaster recovery for multi-secondary configurations is in **Alpha**. -For the latest updates, check the [Disaster Recovery epic for complete maturity](https://gitlab.com/groups/gitlab-org/-/epics/590). +For the latest updates, check the [Disaster Recovery epic for complete maturity](https://gitlab.com/groups/gitlab-org/-/epics/590). Multi-secondary configurations require the complete re-synchronization and re-configuration of all non-promoted secondaries and will cause downtime. @@ -84,8 +84,8 @@ must disable the **primary** node. single recommendation. You may need to: - Reconfigure the load balancers. - - Change DNS records (for example, point the primary DNS record to the **secondary** - node in order to stop usage of the **primary** node). + - Change DNS records (for example, point the primary DNS record to the + **secondary** node to stop usage of the **primary** node). - Stop the virtual servers. - Block traffic through a firewall. - Revoke object storage permissions from the **primary** node. @@ -98,16 +98,16 @@ must disable the **primary** node. Note the following when promoting a secondary: -- If replication was paused on the secondary node, for example as a part of upgrading, - while you were running a version of GitLab lower than 13.4, you _must_ - [enable the node via the database](../replication/troubleshooting.md#while-promoting-the-secondary-i-got-an-error-activerecordrecordinvalid) +- If replication was paused on the secondary node (for example as a part of + upgrading, while you were running a version of GitLab earlier than 13.4), you + _must_ [enable the node by using the database](../replication/troubleshooting.md#message-activerecordrecordinvalid-validation-failed-enabled-geo-primary-node-cannot-be-disabled) before proceeding. - A new **secondary** should not be added at this time. If you want to add a new **secondary**, do this after you have completed the entire process of promoting the **secondary** to the **primary**. - If you encounter an `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken` - error during this process, please read - [the troubleshooting advice](../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-node). + error message during this process, for more information, see this + [troubleshooting advice](../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-node). #### Promoting a **secondary** node running on a single machine @@ -120,6 +120,10 @@ Note the following when promoting a secondary: 1. Edit `/etc/gitlab/gitlab.rb` to reflect its new status as **primary** by removing any lines that enabled the `geo_secondary_role`: + Users of GitLab 13.5 or later can skip this step, due to the appropriate + roles being enabled or disabled during the promotion in the following + step. + ```ruby ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. geo_secondary_role['enable'] = true @@ -129,7 +133,10 @@ Note the following when promoting a secondary: ``` 1. Promote the **secondary** node to the **primary** node. - + +DANGER: **Danger:** +In GitLab 13.2 and later versions, promoting a secondary node to a primary while the secondary is paused fails. We are [investigating the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/225173). Do not pause replication before promoting a secondary. If the node is paused, please resume before promoting. + To promote the secondary node to primary along with preflight checks: ```shell @@ -139,7 +146,7 @@ Note the following when promoting a secondary: If you have already run the [preflight checks](planned_failover.md#preflight-checks) separately or don't want to run them, you can skip preflight checks with: ```shell - gitlab-ctl promote-to-primary-node --skip-preflight-check + gitlab-ctl promote-to-primary-node --skip-preflight-checks ``` You can also promote the secondary node to primary **without any further confirmation**, even when preflight checks fail: @@ -159,6 +166,9 @@ conjunction with multiple servers, as it can only perform changes on a **secondary** with only a single machine. Instead, you must do this manually. +DANGER: **Danger:** +In GitLab 13.2 and later versions, promoting a secondary node to a primary while the secondary is paused fails. We are [investigating the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/225173). Do not pause replication before promoting a secondary. If the node is paused, please resume before promoting. + 1. SSH in to the database node in the **secondary** and trigger PostgreSQL to promote to read-write: @@ -201,6 +211,9 @@ an external PostgreSQL database, as it can only perform changes on a **secondary node with GitLab and the database on the same machine. As a result, a manual process is required: +DANGER: **Danger:** +In GitLab 13.2 and later versions, promoting a secondary node to a primary while the secondary is paused fails. We are [investigating the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/225173). Do not pause replication before promoting a secondary. If the node is paused, please resume before promoting. + 1. Promote the replica database associated with the **secondary** site. This will set the database to read-write: - Amazon RDS - [Promoting a Read Replica to Be a Standalone DB Instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Promote) diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index 9b9c386652c..1238c4d8e2a 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -27,7 +27,7 @@ have a high degree of confidence in being able to perform them accurately. ## Not all data is automatically replicated -If you are using any GitLab features that Geo [doesn't support](../index.md#current-limitations), +If you are using any GitLab features that Geo [doesn't support](../index.md#limitations), you must make separate provisions to ensure that the **secondary** node has an up-to-date copy of any data associated with that feature. This may extend the required scheduled maintenance period significantly. diff --git a/doc/administration/geo/disaster_recovery/promotion_runbook.md b/doc/administration/geo/disaster_recovery/promotion_runbook.md index fb2353513df..7eb6ef01aee 100644 --- a/doc/administration/geo/disaster_recovery/promotion_runbook.md +++ b/doc/administration/geo/disaster_recovery/promotion_runbook.md @@ -1,269 +1,5 @@ --- -stage: Enablement -group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers -type: howto +redirect_to: runbooks/planned_failover_single_node.md --- -CAUTION: **Caution:** -This runbook is in **alpha**. For complete, production-ready documentation, see the -[disaster recovery documentation](index.md). - -# Disaster Recovery (Geo) promotion runbooks **(PREMIUM ONLY)** - -## Geo planned failover runbook 1 - -| Component | Configuration | -| ----------- | --------------- | -| PostgreSQL | Omnibus-managed | -| Geo site | Single-node | -| Secondaries | One | - -This runbook will guide you through a planned failover of a single-node Geo site -with one secondary. The following general architecture is assumed: - -```mermaid -graph TD - subgraph main[Geo deployment] - subgraph Primary[Primary site] - Node_1[(GitLab node)] - end - subgraph Secondary1[Secondary site] - Node_2[(GitLab node)] - end - end -``` - -This guide will result in the following: - -1. An offline primary. -1. A promoted secondary that is now the new primary. - -What is not covered: - -1. Re-adding the old **primary** as a secondary. -1. Adding a new secondary. - -### Preparation - -NOTE: **Note:** -Before following any of those steps, make sure you have `root` access to the -**secondary** to promote it, since there isn't provided an automated way to -promote a Geo replica and perform a failover. - -On the **secondary** node, navigate to the **Admin Area > Geo** dashboard to -review its status. Replicated objects (shown in green) should be close to 100%, -and there should be no failures (shown in red). If a large proportion of -objects aren't yet replicated (shown in gray), consider giving the node more -time to complete. - -![Replication status](img/replication-status.png) - -If any objects are failing to replicate, this should be investigated before -scheduling the maintenance window. After a planned failover, anything that -failed to replicate will be **lost**. - -You can use the -[Geo status API](../../../api/geo_nodes.md#retrieve-project-sync-or-verification-failures-that-occurred-on-the-current-node) -to review failed objects and the reasons for failure. -A common cause of replication failures is the data being missing on the -**primary** node - you can resolve these failures by restoring the data from backup, -or removing references to the missing data. - -The maintenance window won't end until Geo replication and verification is -completely finished. To keep the window as short as possible, you should -ensure these processes are close to 100% as possible during active use. - -If the **secondary** node is still replicating data from the **primary** node, -follow these steps to avoid unnecessary data loss: - -1. Until a [read-only mode](https://gitlab.com/gitlab-org/gitlab/-/issues/14609) - is implemented, updates must be prevented from happening manually to the - **primary**. Note that your **secondary** node still needs read-only - access to the **primary** node during the maintenance window: - - 1. At the scheduled time, using your cloud provider or your node's firewall, block - all HTTP, HTTPS and SSH traffic to/from the **primary** node, **except** for your IP and - the **secondary** node's IP. - - For instance, you can run the following commands on the **primary** node: - - ```shell - sudo iptables -A INPUT -p tcp -s --destination-port 22 -j ACCEPT - sudo iptables -A INPUT -p tcp -s --destination-port 22 -j ACCEPT - sudo iptables -A INPUT --destination-port 22 -j REJECT - - sudo iptables -A INPUT -p tcp -s --destination-port 80 -j ACCEPT - sudo iptables -A INPUT -p tcp -s --destination-port 80 -j ACCEPT - sudo iptables -A INPUT --tcp-dport 80 -j REJECT - - sudo iptables -A INPUT -p tcp -s --destination-port 443 -j ACCEPT - sudo iptables -A INPUT -p tcp -s --destination-port 443 -j ACCEPT - sudo iptables -A INPUT --tcp-dport 443 -j REJECT - ``` - - From this point, users will be unable to view their data or make changes on the - **primary** node. They will also be unable to log in to the **secondary** node. - However, existing sessions will work for the remainder of the maintenance period, and - public data will be accessible throughout. - - 1. Verify the **primary** node is blocked to HTTP traffic by visiting it in browser via - another IP. The server should refuse connection. - - 1. Verify the **primary** node is blocked to Git over SSH traffic by attempting to pull an - existing Git repository with an SSH remote URL. The server should refuse - connection. - - 1. On the **primary** node, disable non-Geo periodic background jobs by navigating - to **Admin Area > Monitoring > Background Jobs > Cron**, clicking `Disable All`, - and then clicking `Enable` for the `geo_sidekiq_cron_config_worker` cron job. - This job will re-enable several other cron jobs that are essential for planned - failover to complete successfully. - -1. Finish replicating and verifying all data: - - CAUTION: **Caution:** - Not all data is automatically replicated. Read more about - [what is excluded](planned_failover.md#not-all-data-is-automatically-replicated). - - 1. If you are manually replicating any - [data not managed by Geo](../replication/datatypes.md#limitations-on-replicationverification), - trigger the final replication process now. - 1. On the **primary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues** - and wait for all queues except those with `geo` in the name to drop to 0. - These queues contain work that has been submitted by your users; failing over - before it is completed will cause the work to be lost. - 1. On the **primary** node, navigate to **Admin Area > Geo** and wait for the - following conditions to be true of the **secondary** node you are failing over to: - - All replication meters to each 100% replicated, 0% failures. - - All verification meters reach 100% verified, 0% failures. - - Database replication lag is 0ms. - - The Geo log cursor is up to date (0 events behind). - - 1. On the **secondary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues** - and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. - 1. On the **secondary** node, use [these instructions](../../raketasks/check.md) - to verify the integrity of CI artifacts, LFS objects, and uploads in file - storage. - - At this point, your **secondary** node will contain an up-to-date copy of everything the - **primary** node has, meaning nothing will be lost when you fail over. - -1. In this final step, you need to permanently disable the **primary** node. - - CAUTION: **Caution:** - When the **primary** node goes offline, there may be data saved on the **primary** node - that has not been replicated to the **secondary** node. This data should be treated - as lost if you proceed. - - TIP: **Tip:** - If you plan to [update the **primary** domain DNS record](index.md#step-4-optional-updating-the-primary-domain-dns-record), - you may wish to lower the TTL now to speed up propagation. - - When performing a failover, we want to avoid a split-brain situation where - writes can occur in two different GitLab instances. So to prepare for the - failover, you must disable the **primary** node: - - - If you have SSH access to the **primary** node, stop and disable GitLab: - - ```shell - sudo gitlab-ctl stop - ``` - - Prevent GitLab from starting up again if the server unexpectedly reboots: - - ```shell - sudo systemctl disable gitlab-runsvdir - ``` - - NOTE: **Note:** - (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being - started if the machine reboots isn't available (see [Omnibus GitLab issue #3058](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3058)). - It may be safest to uninstall the GitLab package completely with `sudo yum remove gitlab-ee`. - - NOTE: **Note:** - (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu - or any other distribution based on the Upstart init system, you can prevent GitLab - from starting if the machine reboots as `root` with - `initctl stop gitlab-runsvvdir && echo 'manual' > /etc/init/gitlab-runsvdir.override && initctl reload-configuration`. - - - If you do not have SSH access to the **primary** node, take the machine offline and - prevent it from rebooting. Since there are many ways you may prefer to accomplish - this, we will avoid a single recommendation. You may need to: - - - Reconfigure the load balancers. - - Change DNS records (for example, point the **primary** DNS record to the **secondary** - node in order to stop usage of the **primary** node). - - Stop the virtual servers. - - Block traffic through a firewall. - - Revoke object storage permissions from the **primary** node. - - Physically disconnect a machine. - -### Promoting the **secondary** node - -Note the following when promoting a secondary: - -- A new **secondary** should not be added at this time. If you want to add a new - **secondary**, do this after you have completed the entire process of promoting - the **secondary** to the **primary**. -- If you encounter an `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken` - error during this process, read - [the troubleshooting advice](../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-node). - -To promote the secondary node: - -1. SSH in to your **secondary** node and login as root: - - ```shell - sudo -i - ``` - -1. Edit `/etc/gitlab/gitlab.rb` to reflect its new status as **primary** by - removing any lines that enabled the `geo_secondary_role`: - - ```ruby - ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. - geo_secondary_role['enable'] = true - - ## In 11.5+ documentation, the role was enabled as follows. Remove this line. - roles ['geo_secondary_role'] - ``` - -1. Run the following command to list out all preflight checks and automatically - check if replication and verification are complete before scheduling a planned - failover to ensure the process will go smoothly: - - ```shell - gitlab-ctl promotion-preflight-checks - ``` - -1. Promote the **secondary**: - - ```shell - gitlab-ctl promote-to-primary-node - ``` - - If you have already run the [preflight checks](planned_failover.md#preflight-checks) - or don't want to run them, you can skip them: - - ```shell - gitlab-ctl promote-to-primary-node --skip-preflight-check - ``` - - You can also promote the secondary node to primary **without any further confirmation**, even when preflight checks fail: - - ```shell - sudo gitlab-ctl promote-to-primary-node --force - ``` - -1. Verify you can connect to the newly promoted **primary** node using the URL used - previously for the **secondary** node. - - If successful, the **secondary** node has now been promoted to the **primary** node. - -### Next steps - -To regain geographic redundancy as quickly as possible, you should -[add a new **secondary** node](../setup/index.md). To -do that, you can re-add the old **primary** as a new secondary and bring it back -online. +This document was moved to [another location](runbooks/planned_failover_single_node.md). diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md new file mode 100644 index 00000000000..1e3bac0b354 --- /dev/null +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md @@ -0,0 +1,274 @@ +--- +stage: Enablement +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: howto +--- + +CAUTION: **Caution:** +This runbook is in **alpha**. For complete, production-ready documentation, see the +[disaster recovery documentation](../index.md). + +# Disaster Recovery (Geo) promotion runbooks **(PREMIUM ONLY)** + +## Geo planned failover for a multi-node configuration + +| Component | Configuration | +|-------------|-----------------| +| PostgreSQL | Omnibus-managed | +| Geo site | Multi-node | +| Secondaries | One | + +This runbook will guide you through a planned failover of a multi-node Geo site +with one secondary. The following [2000 user reference architecture](../../../../administration/reference_architectures/2k_users.md) is assumed: + +```mermaid +graph TD + subgraph main[Geo deployment] + subgraph Primary[Primary site, multi-node] + Node_1[Rails node 1] + Node_2[Rails node 2] + Node_3[PostgreSQL node] + Node_4[Gitaly node] + Node_5[Redis node] + Node_6[Monitoring node] + end + subgraph Secondary[Secondary site, multi-node] + Node_7[Rails node 1] + Node_8[Rails node 2] + Node_9[PostgreSQL node] + Node_10[Gitaly node] + Node_11[Redis node] + Node_12[Monitoring node] + end + end +``` + +The load balancer node and optional NFS server are omitted for clarity. + +This guide will result in the following: + +1. An offline primary. +1. A promoted secondary that is now the new primary. + +What is not covered: + +1. Re-adding the old **primary** as a secondary. +1. Adding a new secondary. + +### Preparation + +NOTE: **Note:** +Before following any of those steps, make sure you have `root` access to the +**secondary** to promote it, since there isn't provided an automated way to +promote a Geo replica and perform a failover. + +On the **secondary** node, navigate to the **Admin Area > Geo** dashboard to +review its status. Replicated objects (shown in green) should be close to 100%, +and there should be no failures (shown in red). If a large proportion of +objects aren't yet replicated (shown in gray), consider giving the node more +time to complete. + +![Replication status](../img/replication-status.png) + +If any objects are failing to replicate, this should be investigated before +scheduling the maintenance window. After a planned failover, anything that +failed to replicate will be **lost**. + +You can use the +[Geo status API](../../../../api/geo_nodes.md#retrieve-project-sync-or-verification-failures-that-occurred-on-the-current-node) +to review failed objects and the reasons for failure. +A common cause of replication failures is the data being missing on the +**primary** node - you can resolve these failures by restoring the data from backup, +or removing references to the missing data. + +The maintenance window won't end until Geo replication and verification is +completely finished. To keep the window as short as possible, you should +ensure these processes are close to 100% as possible during active use. + +If the **secondary** node is still replicating data from the **primary** node, +follow these steps to avoid unnecessary data loss: + +1. Until a [read-only mode](https://gitlab.com/gitlab-org/gitlab/-/issues/14609) + is implemented, updates must be prevented from happening manually to the + **primary**. Note that your **secondary** node still needs read-only + access to the **primary** node during the maintenance window: + + 1. At the scheduled time, using your cloud provider or your node's firewall, block + all HTTP, HTTPS and SSH traffic to/from the **primary** node, **except** for your IP and + the **secondary** node's IP. + + For instance, you can run the following commands on the **primary** node: + + ```shell + sudo iptables -A INPUT -p tcp -s --destination-port 22 -j ACCEPT + sudo iptables -A INPUT -p tcp -s --destination-port 22 -j ACCEPT + sudo iptables -A INPUT --destination-port 22 -j REJECT + + sudo iptables -A INPUT -p tcp -s --destination-port 80 -j ACCEPT + sudo iptables -A INPUT -p tcp -s --destination-port 80 -j ACCEPT + sudo iptables -A INPUT --tcp-dport 80 -j REJECT + + sudo iptables -A INPUT -p tcp -s --destination-port 443 -j ACCEPT + sudo iptables -A INPUT -p tcp -s --destination-port 443 -j ACCEPT + sudo iptables -A INPUT --tcp-dport 443 -j REJECT + ``` + + From this point, users will be unable to view their data or make changes on the + **primary** node. They will also be unable to log in to the **secondary** node. + However, existing sessions will work for the remainder of the maintenance period, and + public data will be accessible throughout. + + 1. Verify the **primary** node is blocked to HTTP traffic by visiting it in browser via + another IP. The server should refuse connection. + + 1. Verify the **primary** node is blocked to Git over SSH traffic by attempting to pull an + existing Git repository with an SSH remote URL. The server should refuse + connection. + + 1. On the **primary** node, disable non-Geo periodic background jobs by navigating + to **Admin Area > Monitoring > Background Jobs > Cron**, clicking `Disable All`, + and then clicking `Enable` for the `geo_sidekiq_cron_config_worker` cron job. + This job will re-enable several other cron jobs that are essential for planned + failover to complete successfully. + +1. Finish replicating and verifying all data: + + CAUTION: **Caution:** + Not all data is automatically replicated. Read more about + [what is excluded](../planned_failover.md#not-all-data-is-automatically-replicated). + + 1. If you are manually replicating any + [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), + trigger the final replication process now. + 1. On the **primary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues** + and wait for all queues except those with `geo` in the name to drop to 0. + These queues contain work that has been submitted by your users; failing over + before it is completed will cause the work to be lost. + 1. On the **primary** node, navigate to **Admin Area > Geo** and wait for the + following conditions to be true of the **secondary** node you are failing over to: + - All replication meters to each 100% replicated, 0% failures. + - All verification meters reach 100% verified, 0% failures. + - Database replication lag is 0ms. + - The Geo log cursor is up to date (0 events behind). + + 1. On the **secondary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues** + and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. + 1. On the **secondary** node, use [these instructions](../../../raketasks/check.md) + to verify the integrity of CI artifacts, LFS objects, and uploads in file + storage. + + At this point, your **secondary** node will contain an up-to-date copy of everything the + **primary** node has, meaning nothing will be lost when you fail over. + +1. In this final step, you need to permanently disable the **primary** node. + + CAUTION: **Caution:** + When the **primary** node goes offline, there may be data saved on the **primary** node + that has not been replicated to the **secondary** node. This data should be treated + as lost if you proceed. + + TIP: **Tip:** + If you plan to [update the **primary** domain DNS record](../index.md#step-4-optional-updating-the-primary-domain-dns-record), + you may wish to lower the TTL now to speed up propagation. + + When performing a failover, we want to avoid a split-brain situation where + writes can occur in two different GitLab instances. So to prepare for the + failover, you must disable the **primary** node: + + - If you have SSH access to the **primary** node, stop and disable GitLab: + + ```shell + sudo gitlab-ctl stop + ``` + + Prevent GitLab from starting up again if the server unexpectedly reboots: + + ```shell + sudo systemctl disable gitlab-runsvdir + ``` + + NOTE: **Note:** + (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being + started if the machine reboots isn't available (see [Omnibus GitLab issue #3058](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3058)). + It may be safest to uninstall the GitLab package completely with `sudo yum remove gitlab-ee`. + + NOTE: **Note:** + (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu + or any other distribution based on the Upstart init system, you can prevent GitLab + from starting if the machine reboots as `root` with + `initctl stop gitlab-runsvvdir && echo 'manual' > /etc/init/gitlab-runsvdir.override && initctl reload-configuration`. + + - If you do not have SSH access to the **primary** node, take the machine offline and + prevent it from rebooting. Since there are many ways you may prefer to accomplish + this, we will avoid a single recommendation. You may need to: + + - Reconfigure the load balancers. + - Change DNS records (for example, point the **primary** DNS record to the + **secondary** node to stop using the **primary** node). + - Stop the virtual servers. + - Block traffic through a firewall. + - Revoke object storage permissions from the **primary** node. + - Physically disconnect a machine. + +### Promoting the **secondary** node + +NOTE: **Note:** +A new **secondary** should not be added at this time. If you want to add a new +**secondary**, do this after you have completed the entire process of promoting +the **secondary** to the **primary**. + +CAUTION: **Caution:** +If you encounter an `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken` error during this process, read +[the troubleshooting advice](../../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-node). + +The `gitlab-ctl promote-to-primary-node` command cannot be used yet in +conjunction with multiple servers, as it can only +perform changes on a **secondary** with only a single machine. Instead, you must +do this manually. + +DANGER: **Danger:** +In GitLab 13.2 and later versions, promoting a secondary node to a primary while the secondary is paused fails. We are [investigating the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/225173). Do not pause replication before promoting a secondary. If the node is paused, please resume before promoting. + +1. SSH in to the PostgreSQL node in the **secondary** and trigger PostgreSQL to + promote to read-write: + + ```shell + sudo gitlab-pg-ctl promote + ``` + + In GitLab 12.8 and earlier, see [Message: `sudo: gitlab-pg-ctl: command not found`](../../replication/troubleshooting.md#message-sudo-gitlab-pg-ctl-command-not-found). + +1. Edit `/etc/gitlab/gitlab.rb` on every machine in the **secondary** to + reflect its new status as **primary** by removing any lines that enabled the + `geo_secondary_role`: + + ```ruby + ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. + geo_secondary_role['enable'] = true + + ## In 11.5+ documentation, the role was enabled as follows. Remove this line. + roles ['geo_secondary_role'] + ``` + + After making these changes [Reconfigure GitLab](../../../restart_gitlab.md#omnibus-gitlab-reconfigure) each + machine so the changes take effect. + +1. Promote the **secondary** to **primary**. SSH into a single Rails node + server and execute: + + ```shell + sudo gitlab-rake geo:set_secondary_as_primary + ``` + +1. Verify you can connect to the newly promoted **primary** using the URL used + previously for the **secondary**. + +1. Success! The **secondary** has now been promoted to **primary**. + +### Next steps + +To regain geographic redundancy as quickly as possible, you should +[add a new **secondary** node](../../setup/index.md). To +do that, you can re-add the old **primary** as a new secondary and bring it back +online. diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md new file mode 100644 index 00000000000..5e847030077 --- /dev/null +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md @@ -0,0 +1,269 @@ +--- +stage: Enablement +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +type: howto +--- + +CAUTION: **Caution:** +This runbook is in **alpha**. For complete, production-ready documentation, see the +[disaster recovery documentation](../index.md). + +# Disaster Recovery (Geo) promotion runbooks **(PREMIUM ONLY)** + +## Geo planned failover for a single-node configuration + +| Component | Configuration | +|-------------|-----------------| +| PostgreSQL | Omnibus-managed | +| Geo site | Single-node | +| Secondaries | One | + +This runbook will guide you through a planned failover of a single-node Geo site +with one secondary. The following general architecture is assumed: + +```mermaid +graph TD + subgraph main[Geo deployment] + subgraph Primary[Primary site] + Node_1[(GitLab node)] + end + subgraph Secondary1[Secondary site] + Node_2[(GitLab node)] + end + end +``` + +This guide will result in the following: + +1. An offline primary. +1. A promoted secondary that is now the new primary. + +What is not covered: + +1. Re-adding the old **primary** as a secondary. +1. Adding a new secondary. + +### Preparation + +NOTE: **Note:** +Before following any of those steps, make sure you have `root` access to the +**secondary** to promote it, since there isn't provided an automated way to +promote a Geo replica and perform a failover. + +On the **secondary** node, navigate to the **Admin Area > Geo** dashboard to +review its status. Replicated objects (shown in green) should be close to 100%, +and there should be no failures (shown in red). If a large proportion of +objects aren't yet replicated (shown in gray), consider giving the node more +time to complete. + +![Replication status](../img/replication-status.png) + +If any objects are failing to replicate, this should be investigated before +scheduling the maintenance window. After a planned failover, anything that +failed to replicate will be **lost**. + +You can use the +[Geo status API](../../../../api/geo_nodes.md#retrieve-project-sync-or-verification-failures-that-occurred-on-the-current-node) +to review failed objects and the reasons for failure. +A common cause of replication failures is the data being missing on the +**primary** node - you can resolve these failures by restoring the data from backup, +or removing references to the missing data. + +The maintenance window won't end until Geo replication and verification is +completely finished. To keep the window as short as possible, you should +ensure these processes are close to 100% as possible during active use. + +If the **secondary** node is still replicating data from the **primary** node, +follow these steps to avoid unnecessary data loss: + +1. Until a [read-only mode](https://gitlab.com/gitlab-org/gitlab/-/issues/14609) + is implemented, updates must be prevented from happening manually to the + **primary**. Note that your **secondary** node still needs read-only + access to the **primary** node during the maintenance window: + + 1. At the scheduled time, using your cloud provider or your node's firewall, block + all HTTP, HTTPS and SSH traffic to/from the **primary** node, **except** for your IP and + the **secondary** node's IP. + + For instance, you can run the following commands on the **primary** node: + + ```shell + sudo iptables -A INPUT -p tcp -s --destination-port 22 -j ACCEPT + sudo iptables -A INPUT -p tcp -s --destination-port 22 -j ACCEPT + sudo iptables -A INPUT --destination-port 22 -j REJECT + + sudo iptables -A INPUT -p tcp -s --destination-port 80 -j ACCEPT + sudo iptables -A INPUT -p tcp -s --destination-port 80 -j ACCEPT + sudo iptables -A INPUT --tcp-dport 80 -j REJECT + + sudo iptables -A INPUT -p tcp -s --destination-port 443 -j ACCEPT + sudo iptables -A INPUT -p tcp -s --destination-port 443 -j ACCEPT + sudo iptables -A INPUT --tcp-dport 443 -j REJECT + ``` + + From this point, users will be unable to view their data or make changes on the + **primary** node. They will also be unable to log in to the **secondary** node. + However, existing sessions will work for the remainder of the maintenance period, and + public data will be accessible throughout. + + 1. Verify the **primary** node is blocked to HTTP traffic by visiting it in browser via + another IP. The server should refuse connection. + + 1. Verify the **primary** node is blocked to Git over SSH traffic by attempting to pull an + existing Git repository with an SSH remote URL. The server should refuse + connection. + + 1. On the **primary** node, disable non-Geo periodic background jobs by navigating + to **Admin Area > Monitoring > Background Jobs > Cron**, clicking `Disable All`, + and then clicking `Enable` for the `geo_sidekiq_cron_config_worker` cron job. + This job will re-enable several other cron jobs that are essential for planned + failover to complete successfully. + +1. Finish replicating and verifying all data: + + CAUTION: **Caution:** + Not all data is automatically replicated. Read more about + [what is excluded](../planned_failover.md#not-all-data-is-automatically-replicated). + + 1. If you are manually replicating any + [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), + trigger the final replication process now. + 1. On the **primary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues** + and wait for all queues except those with `geo` in the name to drop to 0. + These queues contain work that has been submitted by your users; failing over + before it is completed will cause the work to be lost. + 1. On the **primary** node, navigate to **Admin Area > Geo** and wait for the + following conditions to be true of the **secondary** node you are failing over to: + - All replication meters to each 100% replicated, 0% failures. + - All verification meters reach 100% verified, 0% failures. + - Database replication lag is 0ms. + - The Geo log cursor is up to date (0 events behind). + + 1. On the **secondary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues** + and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. + 1. On the **secondary** node, use [these instructions](../../../raketasks/check.md) + to verify the integrity of CI artifacts, LFS objects, and uploads in file + storage. + + At this point, your **secondary** node will contain an up-to-date copy of everything the + **primary** node has, meaning nothing will be lost when you fail over. + +1. In this final step, you need to permanently disable the **primary** node. + + CAUTION: **Caution:** + When the **primary** node goes offline, there may be data saved on the **primary** node + that has not been replicated to the **secondary** node. This data should be treated + as lost if you proceed. + + TIP: **Tip:** + If you plan to [update the **primary** domain DNS record](../index.md#step-4-optional-updating-the-primary-domain-dns-record), + you may wish to lower the TTL now to speed up propagation. + + When performing a failover, we want to avoid a split-brain situation where + writes can occur in two different GitLab instances. So to prepare for the + failover, you must disable the **primary** node: + + - If you have SSH access to the **primary** node, stop and disable GitLab: + + ```shell + sudo gitlab-ctl stop + ``` + + Prevent GitLab from starting up again if the server unexpectedly reboots: + + ```shell + sudo systemctl disable gitlab-runsvdir + ``` + + NOTE: **Note:** + (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being + started if the machine reboots isn't available (see [Omnibus GitLab issue #3058](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3058)). + It may be safest to uninstall the GitLab package completely with `sudo yum remove gitlab-ee`. + + NOTE: **Note:** + (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu + or any other distribution based on the Upstart init system, you can prevent GitLab + from starting if the machine reboots as `root` with + `initctl stop gitlab-runsvvdir && echo 'manual' > /etc/init/gitlab-runsvdir.override && initctl reload-configuration`. + + - If you do not have SSH access to the **primary** node, take the machine offline and + prevent it from rebooting. Since there are many ways you may prefer to accomplish + this, we will avoid a single recommendation. You may need to: + + - Reconfigure the load balancers. + - Change DNS records (for example, point the **primary** DNS record to the + **secondary** node to stop using the **primary** node). + - Stop the virtual servers. + - Block traffic through a firewall. + - Revoke object storage permissions from the **primary** node. + - Physically disconnect a machine. + +### Promoting the **secondary** node + +Note the following when promoting a secondary: + +- A new **secondary** should not be added at this time. If you want to add a new + **secondary**, do this after you have completed the entire process of promoting + the **secondary** to the **primary**. +- If you encounter an `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken` + error during this process, read + [the troubleshooting advice](../../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-node). + +To promote the secondary node: + +1. SSH in to your **secondary** node and login as root: + + ```shell + sudo -i + ``` + +1. Edit `/etc/gitlab/gitlab.rb` to reflect its new status as **primary** by + removing any lines that enabled the `geo_secondary_role`: + + ```ruby + ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. + geo_secondary_role['enable'] = true + + ## In 11.5+ documentation, the role was enabled as follows. Remove this line. + roles ['geo_secondary_role'] + ``` + +1. Run the following command to list out all preflight checks and automatically + check if replication and verification are complete before scheduling a planned + failover to ensure the process will go smoothly: + + ```shell + gitlab-ctl promotion-preflight-checks + ``` + +1. Promote the **secondary**: + + ```shell + gitlab-ctl promote-to-primary-node + ``` + + If you have already run the [preflight checks](../planned_failover.md#preflight-checks) + or don't want to run them, you can skip them: + + ```shell + gitlab-ctl promote-to-primary-node --skip-preflight-check + ``` + + You can also promote the secondary node to primary **without any further confirmation**, even when preflight checks fail: + + ```shell + sudo gitlab-ctl promote-to-primary-node --force + ``` + +1. Verify you can connect to the newly promoted **primary** node using the URL used + previously for the **secondary** node. + + If successful, the **secondary** node has now been promoted to the **primary** node. + +### Next steps + +To regain geographic redundancy as quickly as possible, you should +[add a new **secondary** node](../../setup/index.md). To +do that, you can re-add the old **primary** as a new secondary and bring it back +online. diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 6fdf213ac78..8767940816b 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -39,7 +39,7 @@ Implementing Geo provides the following benefits: In addition, it: -- Can be used for cloning and fetching projects, in addition to reading any data available in the GitLab web interface (see [current limitations](#current-limitations)). +- Can be used for cloning and fetching projects, in addition to reading any data available in the GitLab web interface (see [limitations](#limitations)). - Overcomes slow connections between distant offices, saving time by improving speed for distributed teams. - Helps reducing the loading time for automated tasks, custom integrations, and internal workflows. - Can quickly fail over to a **secondary** node in a [disaster recovery](disaster_recovery/index.md) scenario. @@ -67,9 +67,9 @@ Keep in mind that: - **Secondary** nodes talk to the **primary** node to: - Get user data for logins (API). - Replicate repositories, LFS Objects, and Attachments (HTTPS + JWT). -- Since GitLab Premium 10.0, the **primary** node no longer talks to **secondary** nodes to notify for changes (API). +- In GitLab Premium 10.0 and later, the **primary** node no longer talks to **secondary** nodes to notify for changes (API). - Pushing directly to a **secondary** node (for both HTTP and SSH, including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in [GitLab Premium](https://about.gitlab.com/pricing/#self-managed) 11.3. -- There are [limitations](#current-limitations) in the current implementation. +- There are [limitations](#limitations) when using Geo. ### Architecture @@ -195,6 +195,9 @@ For information on how to update your Geo nodes to the latest GitLab version, se > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35913) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +DANGER: **Danger:** +In GitLab 13.2 and later versions, promoting a secondary node to a primary while the secondary is paused fails. We are [investigating the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/225173). Do not pause replication before promoting a secondary. If the node is paused, please resume before promoting. + In some circumstances, like during [upgrades](replication/updating_the_geo_nodes.md) or a [planned failover](disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. Pausing and resuming replication is done via a command line tool from the secondary node. @@ -247,7 +250,7 @@ For more information on removing a Geo node, see [Removing **secondary** Geo nod To find out how to disable Geo, see [Disabling Geo](replication/disable_geo.md). -## Current limitations +## Limitations CAUTION: **Caution:** This list of limitations only reflects the latest version of GitLab. If you are using an older version, extra limitations may be in place. @@ -261,6 +264,7 @@ This list of limitations only reflects the latest version of GitLab. If you are - Object pools for forked project deduplication work only on the **primary** node, and are duplicated on the **secondary** node. - [External merge request diffs](../merge_request_diffs.md) will not be replicated if they are on-disk, and viewing merge requests will fail. However, external MR diffs in object storage **are** supported. The default configuration (in-database) does work. - GitLab Runners cannot register with a **secondary** node. Support for this is [planned for the future](https://gitlab.com/gitlab-org/gitlab/-/issues/3294). +- Geo **secondary** nodes can not be configured to [use high-availability configurations of PostgreSQL](https://gitlab.com/groups/gitlab-org/-/epics/2536). ### Limitations on replication/verification @@ -278,7 +282,7 @@ For answers to common questions, see the [Geo FAQ](replication/faq.md). ## Log files -Since GitLab 9.5, Geo stores structured log messages in a `geo.log` file. For Omnibus installations, this file is at `/var/log/gitlab/gitlab-rails/geo.log`. +In GitLab 9.5 and later, Geo stores structured log messages in a `geo.log` file. For Omnibus installations, this file is at `/var/log/gitlab/gitlab-rails/geo.log`. This file contains information about when Geo attempts to sync repositories and files. Each line in the file contains a separate JSON entry that can be ingested into. For example, Elasticsearch or Splunk. diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 166a724f9c1..d1fa2d503be 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -23,30 +23,34 @@ We currently distinguish between three different data types: See the list below of each feature or component we replicate, its corresponding data type, replication, and verification methods: -| Type | Feature / component | Replication method | Verification method | -|:---------|:----------------------------------------------|:--------------------------------------|:-----------------------| -| Database | Application data in PostgreSQL | Native | Native | -| Database | Redis | _N/A_ (*1*) | _N/A_ | -| Database | Elasticsearch | Native | Native | -| Database | Personal snippets | PostgreSQL Replication | PostgreSQL Replication | -| Database | Project snippets | PostgreSQL Replication | PostgreSQL Replication | -| Database | SSH public keys | PostgreSQL Replication | PostgreSQL Replication | -| Git | Project repository | Geo with Gitaly | Gitaly Checksum | -| Git | Project wiki repository | Geo with Gitaly | Gitaly Checksum | -| Git | Project designs repository | Geo with Gitaly | Gitaly Checksum | -| Git | Object pools for forked project deduplication | Geo with Gitaly | _Not implemented_ | -| Blobs | User uploads _(filesystem)_ | Geo with API | _Not implemented_ | -| Blobs | User uploads _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | LFS objects _(filesystem)_ | Geo with API | _Not implemented_ | -| Blobs | LFS objects _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | CI job artifacts _(filesystem)_ | Geo with API | _Not implemented_ | -| Blobs | CI job artifacts _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | Archived CI build traces _(filesystem)_ | Geo with API | _Not implemented_ | -| Blobs | Archived CI build traces _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | Container registry _(filesystem)_ | Geo with API/Docker API | _Not implemented_ | -| Blobs | Container registry _(object storage)_ | Geo with API/Managed/Docker API (*2*) | _Not implemented_ | -| Blobs | Package registry _(filesystem)_ | Geo with API | _Not implemented_ | -| Blobs | Package registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Type | Feature / component | Replication method | Verification method | +|:---------|:------------------------------------------------|:--------------------------------------|:-----------------------| +| Database | Application data in PostgreSQL | Native | Native | +| Database | Redis | _N/A_ (*1*) | _N/A_ | +| Database | Elasticsearch | Native | Native | +| Database | Personal snippets | PostgreSQL Replication | PostgreSQL Replication | +| Database | Project snippets | PostgreSQL Replication | PostgreSQL Replication | +| Database | SSH public keys | PostgreSQL Replication | PostgreSQL Replication | +| Git | Project repository | Geo with Gitaly | Gitaly Checksum | +| Git | Project wiki repository | Geo with Gitaly | Gitaly Checksum | +| Git | Project designs repository | Geo with Gitaly | Gitaly Checksum | +| Git | Object pools for forked project deduplication | Geo with Gitaly | _Not implemented_ | +| Blobs | User uploads _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | User uploads _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | LFS objects _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | LFS objects _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | CI job artifacts _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | CI job artifacts _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Archived CI build traces _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | Archived CI build traces _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Container registry _(filesystem)_ | Geo with API/Docker API | _Not implemented_ | +| Blobs | Container registry _(object storage)_ | Geo with API/Managed/Docker API (*2*) | _Not implemented_ | +| Blobs | Package registry _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | Package registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Versioned Terraform State _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | Versioned Terraform State _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | External Merge Request Diffs _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | External Merge Request Diffs _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | - (*1*): Redis replication can be used as part of HA with Redis sentinel. It's not used between Geo nodes. - (*2*): Object storage replication can be performed by Geo or by your object storage provider/appliance @@ -160,39 +164,34 @@ replicating data from those features will cause the data to be **lost**. If you wish to use those features on a **secondary** node, or to execute a failover successfully, you must replicate their data using some other means. -| Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | Notes | -|:------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------|:----------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------| -| Application data in PostgreSQL | **Yes** (10.2) | **Yes** (10.2) | | -| Project repository | **Yes** (10.2) | **Yes** (10.7) | | -| Project wiki repository | **Yes** (10.2) | **Yes** (10.7) | | -| Project designs repository | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | | -| Uploads | **Yes** (10.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Verified only on transfer, or manually (*1*) | -| LFS objects | **Yes** (10.2) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8922) | Verified only on transfer, or manually (*1*). Unavailable for new LFS objects in 11.11.x and 12.0.x (*2*). | -| CI job artifacts (other than traces) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Verified only manually (*1*) | -| Archived traces | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Verified only on transfer, or manually (*1*) | -| Personal snippets | **Yes** (10.2) | **Yes** (10.2) | | -| [Versioned snippets](../../../user/snippets.md#versioned-snippets) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2810) | | -| Project snippets | **Yes** (10.2) | **Yes** (10.2) | | -| Object pools for forked project deduplication | **Yes** | No | | -| [Server-side Git hooks](../../server_hooks.md) | No | No | | -| [Elasticsearch integration](../../../integration/elasticsearch.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | | -| [GitLab Pages](../../pages/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/589) | No | | -| [Container Registry](../../packages/container_registry.md) | **Yes** (12.3) | No | | -| [NPM Registry](../../../user/packages/npm_registry/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | -| [Maven Repository](../../../user/packages/maven_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | -| [Conan Repository](../../../user/packages/conan_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | -| [NuGet Repository](../../../user/packages/nuget_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | -| [PyPi Repository](../../../user/packages/pypi_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | -| [Composer Repository](../../../user/packages/composer_repository/index.md) | **Yes** (13.2) | No | Behind feature flag `geo_package_file_replication`, enabled by default | -| [External merge request diffs](../../merge_request_diffs.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/33817) | No | | -| [Terraform State](../../terraform_state.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/3112)(*3*) | No | | -| [Vulnerability Export](../../../user/application_security/security_dashboard/#export-vulnerabilities) | [No](https://gitlab.com/groups/gitlab-org/-/epics/3111)(*3*) | No | | -| Content in object storage | **Yes** (12.4) | No | | - -- (*1*): The integrity can be verified manually using - [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing - the output between them. -- (*2*): GitLab versions 11.11.x and 12.0.x are affected by [a bug that prevents any new - LFS objects from replicating](https://gitlab.com/gitlab-org/gitlab/-/issues/32696). -- (*3*): If you are using Object Storage, the replication can be performed by the - Object Storage provider if supported. Please see [Geo with Object Storage](object_storage.md) +| Feature | Replicated (added in GitLab version) | Verified (added in GitLab version) | Object Storage replication (please see [Geo with Object Storage](object_storage.md)) | Notes | +|:---------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------|:----------------------------------------------------------|:-------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Application data in PostgreSQL](../../postgresql/index.md) | **Yes** (10.2) | **Yes** (10.2) | No | | +| [Project repository](../../..//user/project/repository/) | **Yes** (10.2) | **Yes** (10.7) | No | | +| [Project wiki repository](../../../user/project/wiki/) | **Yes** (10.2) | **Yes** (10.7) | No | | +| [Uploads](../../uploads.md) | **Yes** (10.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | No | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them. | +| [LFS objects](../../lfs/index.md) | **Yes** (10.2) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8922) | Via Object Storage provider if supported. Native Geo support (Beta). | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them. GitLab versions 11.11.x and 12.0.x are affected by [a bug that prevents any new LFS objects from replicating](https://gitlab.com/gitlab-org/gitlab/-/issues/32696). | +| [Personal snippets](../../../user/snippets.md#personal-snippets) | **Yes** (10.2) | **Yes** (10.2) | No | | +| [Project snippets](../../../user/snippets.md#project-snippets) | **Yes** (10.2) | **Yes** (10.2) | No | | +| [CI job artifacts (other than Job Logs)](../../../ci/pipelines/job_artifacts.md) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Via Object Storage provider if supported. Native Geo support (Beta) . | Verified only manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them | +| [Job logs](../../job_logs.md) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Via Object Storage provider if supported. Native Geo support (Beta). | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them | +| [Object pools for forked project deduplication](../../../development/git_object_deduplication.md) | **Yes** | No | No | | +| [Container Registry](../../packages/container_registry.md) | **Yes** (12.3) | No | No | Disabled by default. See [instructions](./docker_registry.md) to enable. | +| [Content in object storage (beta)](object_storage.md) | **Yes** (12.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/13845) | No | | +| [Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | Via Object Storage provider if supported. Native Geo support (Beta). | | +| [NPM Registry](../../../user/packages/npm_registry/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Maven Repository](../../../user/packages/maven_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Conan Repository](../../../user/packages/conan_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [NuGet Repository](../../../user/packages/nuget_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [PyPI Repository](../../../user/packages/pypi_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Composer Repository](../../../user/packages/composer_repository/index.md) | **Yes** (13.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Generic packages](../../../user/packages/generic_packages/index.md) | **Yes** (13.5) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default | +| [Versioned Terraform State](../../terraform_state.md) | **Yes** (13.5) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_terraform_state_version_replication`, enabled by default | +| [External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | No | Behind feature flag `geo_merge_request_diff_replication`, enabled by default | | +| [Versioned snippets](../../../user/snippets.md#versioned-snippets) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [No](https://gitlab.com/groups/gitlab-org/-/epics/2810) | No | | +| [Server-side Git hooks](../../server_hooks.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1867) | No | No | | +| [Elasticsearch integration](../../../integration/elasticsearch.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/1186) | No | No | | +| [GitLab Pages](../../pages/index.md) | [No](https://gitlab.com/groups/gitlab-org/-/epics/589) | No | No | | +| [CI Pipeline Artifacts](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/pipeline_artifact.rb) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/238464) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Persists additional artifacts after a pipeline completes | +| [Dependency proxy images](../../../user/packages/dependency_proxy/index.md) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/259694) | No | No | Blocked on [Geo: Secondary Mimicry](https://gitlab.com/groups/gitlab-org/-/epics/1528). Note that replication of this cache is not needed for Disaster Recovery purposes because it can be recreated from external sources. | +| [Vulnerability Export](../../../user/application_security/security_dashboard/#export-vulnerabilities) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/3111) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Not planned because they are ephemeral and sensitive. They can be regenerated on demand. | diff --git a/doc/administration/geo/replication/disable_geo.md b/doc/administration/geo/replication/disable_geo.md index aed8e5fc3bc..14a11d9c1e3 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_geo.md @@ -29,7 +29,7 @@ anymore on these nodes. You can follow our docs to [remove your secondary Geo no If the current node that you want to keep using is a secondary node, you need to first promote it to primary. You can use our steps on [how to promote a secondary node](../disaster_recovery/#step-3-promoting-a-secondary-node) -in order to do that. +to do that. ## Remove the primary node from the UI diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index 3892d73b465..f7f391b360e 100644 --- a/doc/administration/geo/replication/faq.md +++ b/doc/administration/geo/replication/faq.md @@ -67,3 +67,7 @@ That's totally fine. We use HTTP(s) to fetch repository changes from the **prima ## Is this possible to set up a Docker Registry for a **secondary** node that mirrors the one on the **primary** node? Yes. See [Docker Registry for a **secondary** node](docker_registry.md). + +## Can I login to a secondary node? + +Yes, but secondary nodes receive all authentication data (like user accounts and logins) from the primary instance. This means you will be re-directed to the primary for authentication and routed back afterwards. diff --git a/doc/administration/geo/replication/geo_validation_tests.md b/doc/administration/geo/replication/geo_validation_tests.md index 8247b8c6336..c28688930b5 100644 --- a/doc/administration/geo/replication/geo_validation_tests.md +++ b/doc/administration/geo/replication/geo_validation_tests.md @@ -114,6 +114,22 @@ The following are GitLab upgrade validation tests we performed. The following are PostgreSQL upgrade validation tests we performed. +### September 2020 + +[Verify PostgreSQL 12 upgrade for Geo installations](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5454): + +- Description: With PostgreSQL 12 available as an opt-in version in GitLab 13.3, we tested upgrading + existing Geo installations from PostgreSQL 11 to 12. We also re-tested fresh installations of GitLab + with Geo after fixes were made to support PostgreSQL 12. These tests were done using a + [nightly build](https://packages.gitlab.com/gitlab/nightly-builds/packages/ubuntu/bionic/gitlab-ee_13.3.6+rnightly.169516.d5209202-0_amd64.deb) + of GitLab 13.4. +- Outcome: Tests were successful for Geo deployments with a single database node on the primary and secondary. + We encountered known issues with repmgr and Patroni managed PostgreSQL clusters on the Geo primary. Using + PostgreSQL 12 with a database cluster on the primary is not recommended until the issues are resolved. +- Known issues for PostgreSQL clusters: + - [Ensure Patroni detects PostgreSQL update](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5423) + - [Allow configuring permanent replication slots in patroni](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5628) + ### August 2020 [Verify Geo installation with PostgreSQL 12](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5453): @@ -168,5 +184,4 @@ The following are additional validation tests we performed. [Test Gitaly Cluster on a Geo Deployment](https://gitlab.com/gitlab-org/gitlab/-/issues/223210): - Description: Tested a Geo deployment with Gitaly clusters configured on both the primary and secondary Geo sites. Triggered automatic Gitaly cluster failover on the primary Geo site, and ran end-to-end Geo tests. Then triggered Gitaly cluster failover on the secondary Geo site, and re-ran the end-to-end Geo tests. - - Outcome: Successful end-to-end tests before and after Gitaly cluster failover on the primary site, and before and after Gitaly cluster failover on the secondary site. diff --git a/doc/administration/geo/replication/img/geo-ha-diagram.png b/doc/administration/geo/replication/img/geo-ha-diagram.png new file mode 100644 index 00000000000..da5d612827c Binary files /dev/null and b/doc/administration/geo/replication/img/geo-ha-diagram.png differ diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md index cba41c375a3..7d65d2165c5 100644 --- a/doc/administration/geo/replication/multiple_servers.md +++ b/doc/administration/geo/replication/multiple_servers.md @@ -13,7 +13,7 @@ described, it is possible to adapt these instructions to your needs. ## Architecture overview -![Geo multi-node diagram](../../high_availability/img/geo-ha-diagram.png) +![Geo multi-node diagram](img/geo-ha-diagram.png) _[diagram source - GitLab employees only](https://docs.google.com/drawings/d/1z0VlizKiLNXVVVaERFwgsIOuEgjcUqDTWPdQYsE7Z4c/edit)_ @@ -133,7 +133,7 @@ Configure the following services, again using the non-Geo multi-node documentation: - [Configuring Redis for GitLab](../../redis/replication_and_failover.md#example-configuration-for-the-gitlab-application) for multiple nodes. -- [Gitaly](../../high_availability/gitaly.md), which will store data that is +- [Gitaly](../../gitaly/index.md), which will store data that is synchronized from the **primary** node. NOTE: **Note:** @@ -422,7 +422,6 @@ application servers above, with some changes to run only the `sidekiq` service: ## alertmanager['enable'] = false consul['enable'] = false - geo_logcursor['enable'] = false gitaly['enable'] = false gitlab_exporter['enable'] = false gitlab_workhorse['enable'] = false diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index f6d6f39fb19..b62c5c6f460 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -386,6 +386,15 @@ This happens when you have added IP addresses without a subnet mask in `postgres To fix this, add the subnet mask in `/etc/gitlab/gitlab.rb` under `postgresql['md5_auth_cidr_addresses']` to respect the CIDR format (i.e. `1.2.3.4/32`). +### Message: `Found data in the gitlabhq_production database!` when running `gitlab-ctl replicate-geo-database` + +This happens if data is detected in the `projects` table. When one or more projects are detected, the operation +is aborted to prevent accidental data loss. To bypass this message, pass the `--force` option to the command. + +In GitLab 13.4, a seed project is added when GitLab is first installed. This makes it necessary to pass `--force` even +on a new Geo secondary node. There is an [issue to account for seed projects](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5618) +when checking the database. + ### Very large repositories never successfully synchronize on the **secondary** node GitLab places a timeout on all repository clones, including project imports @@ -483,8 +492,8 @@ to start again from scratch, there are a few steps that can help you: gitlab-ctl start geo-postgresql ``` - Reconfigure in order to recreate the folders and make sure permissions and ownership - are correctly + Reconfigure to recreate the folders and make sure permissions and ownership + are correct: ```shell gitlab-ctl reconfigure @@ -605,46 +614,18 @@ or `gitlab-ctl promote-to-primary-node`, either: ### Message: ActiveRecord::RecordInvalid: Validation failed: Enabled Geo primary node cannot be disabled -This error may occur if you have paused replication from the original primary node before attempting to promote this node. -To double check this, you can do the following: - -- Get the current secondary node's ID using: - - ```shell - sudo gitlab-rails runner 'puts GeoNode.current_node.id' - ``` - -- Double check that the node is active through the database by running the following - on the secondary node, replacing `ID_FROM_ABOVE`: - - ```shell - sudo gitlab-rails dbconsole - - SELECT enabled FROM geo_nodes WHERE id = ID_FROM_ABOVE; - ``` - -- If the above returned `f` it means that the replication was paused. - You can re-enable it through an `UPDATE` statement in the database: - - ```shell - sudo gitlab-rails dbconsole - - UPDATE geo_nodes SET enabled = 't' WHERE id = ID_FROM_ABOVE; - ``` - -### While Promoting the secondary, I got an error `ActiveRecord::RecordInvalid` - If you disabled a secondary node, either with the [replication pause task](../index.md#pausing-and-resuming-replication) -(13.2) or via the UI (13.1 and earlier), you must first re-enable the -node before you can continue. This is fixed in 13.4. +(13.2) or by using the user interface (13.1 and earlier), you must first +re-enable the node before you can continue. This is fixed in 13.4. -From `gitlab-psql`, execute the following, replacing `` -with the URL for your secondary server starting with `http` or `https` and ending with a `/`. +Run the following command, replacing `https:///` with the URL +for your secondary server, using either `http` or `https`, and ensuring that you +end the URL with a slash (`/`): ```shell -SECONDARY_URL="https:///" -DATABASE_NAME="gitlabhq_production" -sudo gitlab-psql -d "$DATABASE_NAME" -c "UPDATE geo_nodes SET enabled = true WHERE url = '$SECONDARY_URL';" +sudo gitlab-rails dbconsole + +UPDATE geo_nodes SET enabled = true WHERE url = 'https:///' AND enabled = false;" ``` This should update 1 row. diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md index b78aeb06ebf..1af2b8d0b88 100644 --- a/doc/administration/geo/replication/updating_the_geo_nodes.md +++ b/doc/administration/geo/replication/updating_the_geo_nodes.md @@ -21,14 +21,17 @@ Updating Geo nodes involves performing: NOTE: **Note:** These general update steps are not intended for [high-availability deployments](https://docs.gitlab.com/omnibus/update/README.html#multi-node--ha-deployment), and will cause downtime. If you want to avoid downtime, consider using [zero downtime updates](https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates). +DANGER: **Danger:** +In GitLab 13.2 and later versions, promoting a secondary node to a primary while the secondary is paused fails. We are [investigating the issue](https://gitlab.com/gitlab-org/gitlab/-/issues/225173). Do not pause replication before promoting a secondary. If the node is paused, please resume before promoting. + To update the Geo nodes when a new GitLab version is released, update **primary** and all **secondary** nodes: 1. **Optional:** [Pause replication on each **secondary** node.](../index.md#pausing-and-resuming-replication) 1. Log into the **primary** node. -1. [Update GitLab on the **primary** node using Omnibus](https://docs.gitlab.com/omnibus/update/README.html). +1. [Update GitLab on the **primary** node using Omnibus's Geo-specific steps](https://docs.gitlab.com/omnibus/update/README.html#geo-deployment). 1. Log into each **secondary** node. -1. [Update GitLab on each **secondary** node using Omnibus](https://docs.gitlab.com/omnibus/update/README.html). +1. [Update GitLab on each **secondary** node using Omnibus's Geo-specific steps](https://docs.gitlab.com/omnibus/update/README.html#geo-deployment). 1. If you paused replication in step 1, [resume replication on each **secondary**](../index.md#pausing-and-resuming-replication) 1. [Test](#check-status-after-updating) **primary** and **secondary** nodes, and check version in each. diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md index 1ae246e3e61..85c869eff92 100644 --- a/doc/administration/geo/replication/version_specific_updates.md +++ b/doc/administration/geo/replication/version_specific_updates.md @@ -397,7 +397,7 @@ existing repositories was added in GitLab 10.1. ## Updating to GitLab 10.0 -Since GitLab 10.0, we require all **Geo** systems to [use SSH key lookups via +In GitLab 10.0 and later, we require all **Geo** systems to [use SSH key lookups via the database](../../operations/fast_ssh_key_lookup.md) to avoid having to maintain consistency of the `authorized_keys` file for SSH access. Failing to do this will prevent users from being able to clone via SSH. @@ -447,8 +447,8 @@ Omnibus is the following: > **IMPORTANT**: With GitLab 9.0, the PostgreSQL version is updated to 9.6 and manual steps are -required in order to update the **secondary** nodes and keep the Streaming -Replication working. Downtime is required, so plan ahead. +required to update the **secondary** nodes and keep the Streaming Replication +working. Downtime is required, so plan ahead. The following steps apply only if you update from a 8.17 GitLab version to 9.0+. For previous versions, update to GitLab 8.17 first before attempting to @@ -611,9 +611,9 @@ is prepended with the relevant node for better clarity: ### Update tracking database on **secondary** node -After updating a **secondary** node, you might need to run migrations on -the tracking database. The tracking database was added in GitLab 9.1, -and it is required since 10.0. +After updating a **secondary** node, you might need to run migrations on the +tracking database. The tracking database was added in GitLab 9.1, and is +required in GitLab 10.0 and later. 1. Run database migrations on tracking database: diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index aefa8a0e399..09b9c71aeb7 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -17,9 +17,10 @@ NOTE: **Note:** The stages of the setup process must be completed in the documented order. Before attempting the steps in this stage, [complete all prior stages](../setup/index.md#using-omnibus-gitlab). -This document describes the minimal steps you have to take in order to -replicate your **primary** GitLab database to a **secondary** node's database. You may -have to change some values according to your database setup, how big it is, etc. +This document describes the minimal steps you have to take to replicate your +**primary** GitLab database to a **secondary** node's database. You may have to +change some values, based on attributes including your database's setup and +size. You are encouraged to first read through all the steps before executing them in your testing/production environment. @@ -433,6 +434,11 @@ data before running `pg_basebackup`. NOTE: **Note:** Replication slot names must only contain lowercase letters, numbers, and the underscore character. + NOTE: **Note:** + In GitLab 13.4, a seed project is added when GitLab is first installed. This makes it necessary to pass `--force` even + on a new Geo secondary node. There is an [issue to account for seed projects](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5618) + when checking the database. + When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator` user in the first step. diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index e6b137bac29..59a6f2596da 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -90,10 +90,10 @@ When running Gitaly on its own server, note the following regarding GitLab versi leveraged for redundancy on block-level Git data, but only has to be mounted on the Gitaly servers. - From GitLab 11.8 to 12.2, it is possible to use Elasticsearch in a Gitaly setup that doesn't use - NFS. In order to use Elasticsearch in these versions, the + NFS. To use Elasticsearch in these versions, the [repository indexer](../../integration/elasticsearch.md#elasticsearch-repository-indexer) must be enabled in your GitLab configuration. -- [Since GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/issues/6481), the new indexer is +- [In GitLab 12.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/6481), the new indexer is the default and no configuration is required. ### Network architecture @@ -317,7 +317,7 @@ disable enforcement. For more information, see the documentation on configuring ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -1. Run `sudo /opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml` +1. Run `sudo /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml` to confirm that Gitaly can perform callbacks to the GitLab internal API. **For installations from source** @@ -364,7 +364,7 @@ disable enforcement. For more information, see the documentation on configuring ``` 1. Save the files and [restart GitLab](../restart_gitlab.md#installations-from-source). -1. Run `sudo -u git /home/git/gitlab-shell/bin/check -config /home/git/gitlab-shell/config.yml` +1. Run `sudo -u git /home/git/gitaly/gitaly-hooks check /home/git/gitaly/config.toml` to confirm that Gitaly can perform callbacks to the GitLab internal API. ### Configure Gitaly clients @@ -382,10 +382,10 @@ if previously enabled manually. Gitaly makes the following assumptions: - Your `gitaly1.internal` Gitaly server can be reached at `gitaly1.internal:8075` from your Gitaly - clients, and that Gitaly server can read and write to `/mnt/gitlab/default` and + clients, and that Gitaly server can read, write, and set permissions on `/mnt/gitlab/default` and `/mnt/gitlab/storage1`. - Your `gitaly2.internal` Gitaly server can be reached at `gitaly2.internal:8075` from your Gitaly - clients, and that Gitaly server can read and write to `/mnt/gitlab/storage2`. + clients, and that Gitaly server can read, write, and set permissions on `/mnt/gitlab/storage2`. - Your `gitaly1.internal` and `gitaly2.internal` Gitaly servers can reach each other. You can't define Gitaly servers with some as a local Gitaly server @@ -406,8 +406,8 @@ server (with `gitaly_address`) unless you setup with special ``` 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). -1. Run `sudo gitlab-rake gitlab:gitaly:check` to confirm the Gitaly client can connect to Gitaly - servers. +1. Run `sudo gitlab-rake gitlab:gitaly:check` on the Gitaly client (for example, the + Rails application) to confirm it can connect to Gitaly servers. 1. Tail the logs to see the requests: ```shell @@ -424,17 +424,17 @@ server (with `gitaly_address`) unless you setup with special storages: default: gitaly_address: tcp://gitaly1.internal:8075 - path: /some/dummy/path + path: /some/local/path storage1: gitaly_address: tcp://gitaly1.internal:8075 - path: /some/dummy/path + path: /some/local/path storage2: gitaly_address: tcp://gitaly2.internal:8075 - path: /some/dummy/path + path: /some/local/path ``` NOTE: **Note:** - `/some/dummy/path` should be set to a local folder that exists, however no data will be stored in + `/some/local/path` should be set to a local folder that exists, however no data will be stored in this folder. This will no longer be necessary after [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. @@ -482,6 +482,14 @@ git_data_dirs({ 'storage1' => { 'gitaly_address' => 'tcp://gitlab.internal:8075', 'path' => '/mnt/gitlab/git-data' }, 'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' }, }) + +# Make Gitaly accept connections on all network interfaces +gitaly['listen_addr'] = "0.0.0.0:8075" + +# Or for TLS +gitaly['tls_listen_addr'] = "0.0.0.0:9999" +gitaly['certificate_path'] = "/etc/gitlab/ssl/cert.pem" +gitaly['key_path'] = "/etc/gitlab/ssl/key.pem" ``` `path` can only be included for storage shards on the local Gitaly server. @@ -532,20 +540,12 @@ corresponding to each Gitaly server must be installed on that Gitaly server. Additionally, the certificate (or its certificate authority) must be installed on all: -- Gitaly servers, including the Gitaly server using the certificate. +- Gitaly servers. - Gitaly clients that communicate with it. -The process is documented in the -[GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates) -and repeated below. - Note the following: -- The certificate must specify the address you use to access the Gitaly server. If you are: - - Addressing the Gitaly server by a hostname, you can either use the Common Name field for this, - or add it as a Subject Alternative Name. - - Addressing the Gitaly server by its IP address, you must add it as a Subject Alternative Name to - the certificate. [gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). +- The certificate must specify the address you use to access the Gitaly server. You must add the hostname or IP address as a Subject Alternative Name to the certificate. - You can configure Gitaly servers with both an unencrypted listening address `listen_addr` and an encrypted listening address `tls_listen_addr` at the same time. This allows you to gradually transition from unencrypted to encrypted traffic if necessary. @@ -631,17 +631,17 @@ To configure Gitaly with TLS: storages: default: gitaly_address: tls://gitaly1.internal:9999 - path: /some/dummy/path + path: /some/local/path storage1: gitaly_address: tls://gitaly1.internal:9999 - path: /some/dummy/path + path: /some/local/path storage2: gitaly_address: tls://gitaly2.internal:9999 - path: /some/dummy/path + path: /some/local/path ``` NOTE: **Note:** - `/some/dummy/path` should be set to a local folder that exists, however no data will be stored + `/some/local/path` should be set to a local folder that exists, however no data will be stored in this folder. This will no longer be necessary after [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. @@ -711,6 +711,15 @@ Gitaly Go process. Some examples of things that are implemented in `gitaly-ruby` - RPCs that deal with wikis. - RPCs that create commits on behalf of a user, such as merge commits. +We recommend: + +- At least 300MB memory per worker. +- No more than one worker per core. + +NOTE: **Note:** +`gitaly-ruby` is planned to be eventually removed. To track progress, see the +[Remove the Gitaly-Ruby sidecar](https://gitlab.com/groups/gitlab-org/-/epics/2862) epic. + ### Configure number of `gitaly-ruby` workers `gitaly-ruby` has much less capacity than Gitaly implemented in Go. If your Gitaly server has to handle lots of @@ -1021,6 +1030,9 @@ The second facet presents the only real solution. For this, we developed ## Troubleshooting Gitaly +Check [Gitaly timeouts](../../user/admin_area/settings/gitaly_timeouts.md) when troubleshooting +Gitaly. + ### Checking versions when using standalone Gitaly servers When using standalone Gitaly servers, you must make sure they are the same version @@ -1242,13 +1254,6 @@ unset http_proxy unset https_proxy ``` -### Gitaly not listening on new address after reconfiguring - -When updating the `gitaly['listen_addr']` or `gitaly['prometheus_listen_addr']` -values, Gitaly may continue to listen on the old address after a `sudo gitlab-ctl reconfigure`. - -When this occurs, performing a `sudo gitlab-ctl restart` will resolve the issue. This will no longer be necessary after [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/2521) is resolved. - ### Permission denied errors appearing in Gitaly logs when accessing repositories from a standalone Gitaly server If this error occurs even though file permissions are correct, it's likely that diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 876904a2093..d091ae5895a 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -182,7 +182,7 @@ failure. For greater fault tolerance, the following options are available: - For Geo instances, either: - Set up a separate [PostgreSQL instance](https://www.postgresql.org/docs/11/high-availability.html). - Use a cloud-managed PostgreSQL service. AWS - [Relational Database Service](https://aws.amazon.com/rds/)) is recommended. + [Relational Database Service](https://aws.amazon.com/rds/) is recommended. To complete this section you will need: @@ -356,7 +356,7 @@ application server, or a Gitaly node. If you want to use a TLS client certificate, the options below can be used: ```ruby - # Connect to PostreSQL using a TLS client certificate + # Connect to PostgreSQL using a TLS client certificate # praefect['database_sslcert'] = '/path/to/client-cert' # praefect['database_sslkey'] = '/path/to/client-key' @@ -547,14 +547,14 @@ To configure Praefect with TLS: storages: default: gitaly_address: tls://praefect1.internal:3305 - path: /some/dummy/path + path: /some/local/path storage1: gitaly_address: tls://praefect2.internal:3305 - path: /some/dummy/path + path: /some/local/path ``` NOTE: **Note:** - `/some/dummy/path` should be set to a local folder that exists, however no + `/some/local/path` should be set to a local folder that exists, however no data will be stored in this folder. This will no longer be necessary after [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. @@ -873,10 +873,10 @@ Particular attention should be shown to: gitlab-ctl reconfigure ``` -1. Verify each `gitlab-shell` on each Gitaly node can reach GitLab. On each Gitaly node run: +1. Verify on each Gitaly node the Git Hooks can reach GitLab. On each Gitaly node run: ```shell - /opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml + /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml ``` 1. Verify that GitLab can reach Praefect: @@ -943,16 +943,17 @@ cluster. ## Distributed reads > - Introduced in GitLab 13.1 in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) with feature flag `gitaly_distributed_reads` set to disabled. -> - [Made generally available](https://gitlab.com/gitlab-org/gitaly/-/issues/2951) in GitLab 13.3. +> - [Made generally available and enabled by default](https://gitlab.com/gitlab-org/gitaly/-/issues/2951) in GitLab 13.3. +> - [Disabled by default](https://gitlab.com/gitlab-org/gitaly/-/issues/3178) in GitLab 13.5. Praefect supports distribution of read operations across Gitaly nodes that are configured for the virtual node. -The feature is enabled by default. To disable distributed reads, the `gitaly_distributed_reads` -[feature flag](../feature_flags.md) must be disabled in a Ruby console: +The feature is disabled by default. To enable distributed reads, the `gitaly_distributed_reads` +[feature flag](../feature_flags.md) must be enabled in a Ruby console: ```ruby -Feature.disable(:gitaly_distributed_reads) +Feature.enable(:gitaly_distributed_reads) ``` If enabled, all RPCs marked with `ACCESSOR` option like @@ -993,6 +994,8 @@ information, see the [strong consistency epic](https://gitlab.com/groups/gitlab- To enable strong consistency: +- In GitLab 13.5, you must use Git v2.28.0 or higher on Gitaly nodes to enable + strong consistency. - In GitLab 13.4 and later, the strong consistency voting strategy has been improved. Instead of requiring all nodes to agree, only the primary and half of the secondaries need to agree. This strategy is enabled by default. To diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 0c211c220d7..53001b946d8 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -138,8 +138,8 @@ Most of the time we use `git cat-file --batch` processes for that. For better performance, Gitaly can re-use these `git cat-file` processes across RPC calls. Previously used processes are kept around in a ["Git cat-file cache"](https://about.gitlab.com/blog/2019/07/08/git-performance-on-nfs/#enter-cat-file-cache). -In order to control how much system resources this uses, we have a maximum number -of cat-file processes that can go into the cache. +To control how much system resources this uses, we have a maximum number of +cat-file processes that can go into the cache. The default limit is 100 `cat-file`s, which constitute a pair of `git cat-file --batch` and `git cat-file --batch-check` processes. If diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md deleted file mode 100644 index d36b029cbb3..00000000000 --- a/doc/administration/high_availability/README.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -redirect_to: ../reference_architectures/index.md ---- - -# Reference Architectures - -This document was moved to [another location](../reference_architectures/index.md). diff --git a/doc/administration/high_availability/alpha_database.md b/doc/administration/high_availability/alpha_database.md deleted file mode 100644 index 99c28e5c7a6..00000000000 --- a/doc/administration/high_availability/alpha_database.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'database.md' ---- - -This document was moved to [another location](../postgresql/index.md). diff --git a/doc/administration/high_availability/consul.md b/doc/administration/high_availability/consul.md deleted file mode 100644 index 362d6ee8ba7..00000000000 --- a/doc/administration/high_availability/consul.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../consul.md ---- - -This document was moved to [another location](../consul.md). diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md deleted file mode 100644 index 784e496d10e..00000000000 --- a/doc/administration/high_availability/database.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../postgresql/index.md' ---- - -This document was moved to [another location](../postgresql/index.md). diff --git a/doc/administration/high_availability/gitaly.md b/doc/administration/high_availability/gitaly.md deleted file mode 100644 index a1e8fe3b488..00000000000 --- a/doc/administration/high_availability/gitaly.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../gitaly/index.md ---- - -This document was moved to [another location](../gitaly/index.md). diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md deleted file mode 100644 index 748373c8941..00000000000 --- a/doc/administration/high_availability/gitlab.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../reference_architectures/index.md ---- - -This document was moved to [another location](../reference_architectures/index.md). diff --git a/doc/administration/high_availability/img/fully-distributed.png b/doc/administration/high_availability/img/fully-distributed.png deleted file mode 100644 index c3cd2bf24f0..00000000000 Binary files a/doc/administration/high_availability/img/fully-distributed.png and /dev/null differ diff --git a/doc/administration/high_availability/img/geo-ha-diagram.png b/doc/administration/high_availability/img/geo-ha-diagram.png deleted file mode 100644 index da5d612827c..00000000000 Binary files a/doc/administration/high_availability/img/geo-ha-diagram.png and /dev/null differ diff --git a/doc/administration/high_availability/img/horizontal.png b/doc/administration/high_availability/img/horizontal.png deleted file mode 100644 index 75d08e1097a..00000000000 Binary files a/doc/administration/high_availability/img/horizontal.png and /dev/null differ diff --git a/doc/administration/high_availability/img/hybrid.png b/doc/administration/high_availability/img/hybrid.png deleted file mode 100644 index 8dd9923e597..00000000000 Binary files a/doc/administration/high_availability/img/hybrid.png and /dev/null differ diff --git a/doc/administration/high_availability/load_balancer.md b/doc/administration/high_availability/load_balancer.md deleted file mode 100644 index 5cedc4e11ae..00000000000 --- a/doc/administration/high_availability/load_balancer.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../load_balancer.md ---- - -This document was moved to [another location](../load_balancer.md). diff --git a/doc/administration/high_availability/monitoring_node.md b/doc/administration/high_availability/monitoring_node.md deleted file mode 100644 index 76bcf6d0d40..00000000000 --- a/doc/administration/high_availability/monitoring_node.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../monitoring/prometheus/index.md ---- - -This document was moved to [another location](../monitoring/prometheus/index.md). diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md deleted file mode 100644 index e3342fa0813..00000000000 --- a/doc/administration/high_availability/nfs.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../nfs.md ---- - -This document was moved to [another location](../nfs.md). diff --git a/doc/administration/high_availability/nfs_host_client_setup.md b/doc/administration/high_availability/nfs_host_client_setup.md deleted file mode 100644 index e3342fa0813..00000000000 --- a/doc/administration/high_availability/nfs_host_client_setup.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../nfs.md ---- - -This document was moved to [another location](../nfs.md). diff --git a/doc/administration/high_availability/object_storage.md b/doc/administration/high_availability/object_storage.md deleted file mode 100644 index eeb730d3cc7..00000000000 --- a/doc/administration/high_availability/object_storage.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../object_storage.md' ---- - -This document was moved to [another location](../object_storage.md). diff --git a/doc/administration/high_availability/pgbouncer.md b/doc/administration/high_availability/pgbouncer.md deleted file mode 100644 index 44f4aa37651..00000000000 --- a/doc/administration/high_availability/pgbouncer.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../postgresql/pgbouncer.md ---- - -This document was moved to [another location](../postgresql/pgbouncer.md). diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md deleted file mode 100644 index 2b5771f49f2..00000000000 --- a/doc/administration/high_availability/redis.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../redis/index.md ---- - -This document was moved to [another location](../redis/index.md). diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md deleted file mode 100644 index 75496638979..00000000000 --- a/doc/administration/high_availability/redis_source.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../redis/replication_and_failover_external.md ---- - -This document was moved to [another location](../redis/replication_and_failover_external.md). diff --git a/doc/administration/high_availability/sidekiq.md b/doc/administration/high_availability/sidekiq.md deleted file mode 100644 index ac92ae2eaaa..00000000000 --- a/doc/administration/high_availability/sidekiq.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: ../sidekiq.md ---- - -This document was moved to [another location](../sidekiq.md). diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index 4110f8b7646..c784c788b31 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Housekeeping > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3041) in GitLab 8.4. @@ -28,6 +34,9 @@ the `pushes_since_gc` value is 200 a `git gc` will be run. `git add`. - `git repack` ([man page](https://mirrors.edge.kernel.org/pub/software/scm/git/docs/git-repack.html)) re-organize existing packs into a single, more efficient pack. +Housekeeping will also [remove unreferenced LFS files](../raketasks/cleanup.md#remove-unreferenced-lfs-files) +from your project on the same schedule as the `git gc` operation, freeing up storage space for your project. + You can find this option under your project's **Settings > General > Advanced**. ![Housekeeping settings](img/housekeeping_settings.png) diff --git a/doc/administration/img/export_audit_log_v13_4.png b/doc/administration/img/export_audit_log_v13_4.png index 1b404b5742c..e4ba330b8a9 100644 Binary files a/doc/administration/img/export_audit_log_v13_4.png and b/doc/administration/img/export_audit_log_v13_4.png differ diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index c0c03044225..bd075e86a15 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -82,15 +82,15 @@ instead of the regular password for the mailbox. To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the [Postfix setup documentation](reply_by_email_postfix_setup.md). -### Security Concerns +### Security concerns -WARNING: **WARNING:** +CAUTION: **Caution:** Be careful when choosing the domain used for receiving incoming email. -For the sake of example, suppose your top-level company domain is `hooli.com`. +For example, suppose your top-level company domain is `hooli.com`. All employees in your company have an email address at that domain via Google Apps, and your company's private Slack instance requires a valid `@hooli.com` -email address in order to sign up. +email address to sign up. If you also host a public-facing GitLab instance at `hooli.com` and set your incoming email domain to `hooli.com`, an attacker could abuse the "Create new @@ -112,7 +112,7 @@ See GitLab issue [#30366](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/303 for a real-world example of this exploit. CAUTION: **Caution:** -Be sure to use a mail server that has been configured to reduce +Use a mail server that has been configured to reduce spam. A Postfix mail server that is running on a default configuration, for example, can result in abuse. All messages received on the configured mailbox will be processed diff --git a/doc/administration/index.md b/doc/administration/index.md index a6448fcf64f..07aa3b50bc6 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -1,8 +1,11 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: 'Learn how to install, configure, update, and maintain your GitLab instance.' --- -# Administrator Docs **(CORE ONLY)** +# Administrator documentation **(CORE ONLY)** Learn how to administer your self-managed GitLab instance. @@ -12,18 +15,16 @@ GitLab has two product distributions available through [different subscriptions] - The open core [GitLab Enterprise Edition (EE)](https://gitlab.com/gitlab-org/gitlab). You can [install either GitLab CE or GitLab EE](https://about.gitlab.com/install/ce-or-ee/). -However, the features you'll have access to depend on the subscription you choose -(Core, Starter, Premium, or Ultimate). +However, the features you have access to depend on your chosen [subscription](https://about.gitlab.com/pricing/). -NOTE: **Note:** -GitLab Community Edition installations only have access to Core features. +GitLab Community Edition installations have access only to Core features. -GitLab.com is administered by GitLab, Inc., therefore, only GitLab team members have -access to its admin configurations. If you're a GitLab.com user, please check the -[user documentation](../user/index.md). +Non-administrator users can't access GitLab administration tools and settings. -NOTE: **Note:** -Non-administrator users don’t have access to GitLab administration tools and settings. +GitLab.com is administered by GitLab, Inc., and only GitLab team members have +access to its administration tools and settings. Users of GitLab.com should +instead refer to the [User documentation](../user/index.md) for GitLab +configuration and usage documentation. ## Installing and maintaining GitLab @@ -52,8 +53,10 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [GitLab Pages configuration](pages/index.md): Enable and configure GitLab Pages. - [GitLab Pages configuration for GitLab source installations](pages/source.md): Enable and configure GitLab Pages on [source installations](../install/installation.md#installation-from-source). - [Uploads administration](uploads.md): Configure GitLab uploads storage. -- [Environment variables](environment_variables.md): Supported environment variables that can be used to override their defaults values in order to configure GitLab. -- [Plugins](plugins.md): With custom plugins, GitLab administrators can introduce custom integrations without modifying GitLab's source code. +- [Environment variables](environment_variables.md): Supported environment + variables that can be used to override their default values to configure + GitLab. +- [Plugins](file_hooks.md): With custom plugins, GitLab administrators can introduce custom integrations without modifying GitLab's source code. - [Enforcing Terms of Service](../user/admin_area/settings/terms.md) - [Third party offers](../user/admin_area/settings/third_party_offers.md) - [Compliance](compliance.md): A collection of features from across the application that you may configure to help ensure that your GitLab instance and DevOps workflow meet compliance standards. @@ -82,6 +85,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq MemoryKiller, Puma). - [Restart GitLab](restart_gitlab.md): Learn how to restart GitLab and its components. - [Invalidate Markdown cache](invalidate_markdown_cache.md): Invalidate any cached Markdown. +- [Instance review](instance_review.md): Request a free review of your GitLab instance. #### Updating GitLab @@ -113,7 +117,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Kerberos authentication](../integration/kerberos.md) **(STARTER ONLY)** - See also other [authentication](../topics/authentication/index.md#gitlab-administrators) topics (for example, enforcing 2FA). - [Email users](../tools/email.md): Email GitLab users from within GitLab. **(STARTER ONLY)** -- [User Cohorts](../user/admin_area/user_cohorts.md): Display the monthly cohorts of new users and their activities over time. +- [User Cohorts](../user/admin_area/analytics/user_cohorts.md): Display the monthly cohorts of new users and their activities over time. - [Audit logs and events](audit_events.md): View the changes made within the GitLab server for: - Groups and projects. **(STARTER)** - Instances. **(PREMIUM ONLY)** diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index abd98002934..cb37be8d9dd 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- @@ -163,7 +166,7 @@ There is a limit when embedding metrics in GFM for performance reasons. On GitLab.com, the [maximum number of webhooks and their size](../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. To set this limit on a self-managed installation, run the following in the -[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session): +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby # If limits don't exist for the default plan, you can create one with: @@ -203,7 +206,7 @@ support keyset-based pagination. More information about pagination options can b found in the [API docs section on pagination](../api/README.md#pagination). To set this limit on a self-managed installation, run the following in the -[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session): +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby # If limits don't exist for the default plan, you can create one with: @@ -238,7 +241,7 @@ will fail with a `job_activity_limit_exceeded` error. This limit is disabled by default. To set this limit on a self-managed installation, run the following in the -[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session): +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby # If limits don't exist for the default plan, you can create one with: @@ -264,7 +267,7 @@ limit, the subscription will be considered invalid. - On [GitLab Starter](https://about.gitlab.com/pricing/#self-managed) tier or higher self-managed installations, this limit is defined for the `default` plan that affects all projects. To set this limit on a self-managed installation, run the following in the -[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session): +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby Plan.default.actual_limits.update!(ci_project_subscriptions: 500) @@ -290,7 +293,7 @@ or higher tiers), this limit is defined for the `default` plan that affects all projects. By default, there is no limit. To set this limit on a self-managed installation, run the following in the -[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session): +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby Plan.default.actual_limits.update!(ci_pipeline_schedules: 100) @@ -308,7 +311,7 @@ On self-managed instances this limit is defined for the `default` plan. By defau this limit is set to `25`. To update this limit to a new value on a self-managed installation, run the following in the -[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session): +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby Plan.default.actual_limits.update!(ci_instance_level_variables: 30) @@ -333,6 +336,7 @@ setting is used: | Artifact limit name | Default value | |---------------------------------------------|---------------| | `ci_max_artifact_size_accessibility` | 0 | +| `ci_max_artifact_size_api_fuzzing` | 0 | | `ci_max_artifact_size_archive` | 0 | | `ci_max_artifact_size_browser_performance` | 0 | | `ci_max_artifact_size_cluster_applications` | 0 | @@ -360,7 +364,7 @@ setting is used: | `ci_max_artifact_size_trace` | 0 | For example, to set the `ci_max_artifact_size_junit` limit to 10MB on a self-managed -installation, run the following in the [GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session): +installation, run the following in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby Plan.default.actual_limits.update!(ci_max_artifact_size_junit: 10) @@ -480,7 +484,7 @@ indexed](#maximum-file-size-indexed)). - For self-managed installations it is unlimited by default This limit can be configured for self-managed installations when [enabling -Elasticsearch](../integration/elasticsearch.md#enabling-elasticsearch). +Elasticsearch](../integration/elasticsearch.md#enabling-advanced-search). NOTE: **Note:** Set the limit to `0` to disable it. @@ -527,13 +531,17 @@ More information can be found in the [Push event activities limit and bulk push > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218017) in GitLab 13.4. -On GitLab.com, the maximum file size for a package that's uploaded to the [GitLab Package Registry](../user/packages/package_registry/index.md) -is 5 gigabytes. +On GitLab.com, the maximum file size for a package that's uploaded to the [GitLab Package Registry](../user/packages/package_registry/index.md) varies by format: -Limits are set per package type. +- Conan: 3GB +- Generic: 5GB +- Maven: 3GB +- NPM: 500MB +- NuGet: 500MB +- PyPI: 3GB To set this limit on a self-managed installation, run the following in the -[GitLab Rails console](troubleshooting/debug.md#starting-a-rails-console-session): +[GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session): ```ruby # File size limit is stored in bytes @@ -552,6 +560,12 @@ Plan.default.actual_limits.update!(maven_max_file_size: 100.megabytes) # For PyPI Packages Plan.default.actual_limits.update!(pypi_max_file_size: 100.megabytes) + +# For Debian Packages +Plan.default.actual_limits.update!(debian_max_file_size: 100.megabytes) + +# For Generic Packages +Plan.default.actual_limits.update!(generic_packages_max_file_size: 100.megabytes) ``` Set the limit to `0` to allow any file size. diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index 8ea4bff252e..7eadb54804b 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -1,13 +1,25 @@ +--- +stage: Growth +group: Conversion +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Instance Review **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6995) in [GitLab Core](https://about.gitlab.com/pricing/) 11.3. -If you are running a medium size instance of GitLab Core edition you are qualified for a free Instance Review. You can find the button in the User menu. +If you are running a medium size instance (50+ users) of +[GitLab Core](https://about.gitlab.com/pricing/) edition, you are qualified for a +free Instance Review. -![Instance Review button](img/instance_review_button.png) +1. Sign in as a user with Admin [permissions](../user/permissions.md). +1. In the top menu, click your user icon, and select + **Get a free instance review**: -When you click the button you will be redirected to a form with prefilled data obtained from your instance. + ![Instance Review button](img/instance_review_button.png) -Once you submit the data to GitLab Inc. you can see the initial report. +1. GitLab redirects you to a form with prefilled data obtained from your instance. +1. Click **Submit** to see the initial report. -Additionally you will be contacted by our team for further review which should help you to improve your usage of GitLab. +A GitLab team member will contact you for further review, to provide suggestions +that will help you improve your usage of GitLab. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 49ea59d239c..5bdea9d8843 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -132,7 +132,7 @@ stop; You need to enable PlantUML integration from Settings under Admin Area. To do that, login with an Admin account and do following: -- In GitLab, go to **Admin Area > Settings > Integrations**. +- In GitLab, go to **Admin Area > Settings > General**. - Expand the **PlantUML** section. - Check **Enable PlantUML** checkbox. - Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index c363bd30543..3c53535d856 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,3 +1,9 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Web terminals > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7690) in GitLab 8.15. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 2a79923b793..8069b12e0b9 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -99,8 +99,13 @@ artifacts, you can use an object storage like AWS S3 instead. This configuration relies on valid AWS credentials to be configured already. Use an object storage option like AWS S3 to store job artifacts. +If you configure GitLab to store artifacts on object storage, you may also want to +[eliminate local disk usage for job logs](job_logs.md#prevent-local-disk-usage). +In both cases, job logs are archived and moved to object storage when the job completes. + DANGER: **Danger:** -If you configure GitLab to store CI logs and artifacts on object storage, you must also enable [incremental logging](job_logs.md#new-incremental-logging-architecture). Otherwise, job logs will disappear or not be saved. +In a multi-server setup you must use one of the options to +[eliminate local disk usage for job logs](job_logs.md#prevent-local-disk-usage), or job logs could be lost. [Read more about using object storage with GitLab](object_storage.md). @@ -117,9 +122,9 @@ For source installations the following settings are nested under `artifacts:` an |---------|-------------|---------| | `enabled` | Enable/disable object storage | `false` | | `remote_directory` | The bucket name where Artifacts will be stored| | -| `direct_upload` | Set to true to enable direct upload of Artifacts without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | -| `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | -| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | +| `direct_upload` | Set to `true` to enable direct upload of Artifacts without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | +| `background_upload` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | +| `proxy_download` | Set to `true` to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | | `connection` | Various connection options described below | | #### Connection settings @@ -203,9 +208,9 @@ _The artifacts are stored by default in enabled: true object_store: enabled: true - remote_directory: "artifacts" # The bucket name + remote_directory: "artifacts" # The bucket name connection: - provider: AWS # Only AWS supported at the moment + provider: AWS # Only AWS supported at the moment aws_access_key_id: AWS_ACCESS_KEY_ID aws_secret_access_key: AWS_SECRET_ACCESS_KEY region: eu-central-1 @@ -316,9 +321,9 @@ _The uploads are stored by default in **In Omnibus installations:** -In order to migrate back to local storage: +To migrate back to local storage: -1. Set both `direct_upload` and `background_upload` to false in `gitlab.rb`, under the artifacts object storage settings. +1. Set both `direct_upload` and `background_upload` to `false` in `gitlab.rb`, under the artifacts object storage settings. 1. [Reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Run `gitlab-rake gitlab:artifacts:migrate_to_local`. 1. Disable object_storage for artifacts in `gitlab.rb`: @@ -369,7 +374,7 @@ default artifacts expiration setting, which you can find in the [CI/CD Admin set > Introduced in GitLab 10.3. -To disable [the dependencies validation](../ci/yaml/README.md#when-a-dependent-job-will-fail), +To disable [the dependencies validation](../ci/yaml/README.md#when-a-dependent-job-fails), you can enable the `ci_disable_validates_dependencies` feature flag from a Rails console. **In Omnibus installations:** @@ -419,10 +424,10 @@ generated by [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse). that are located in the artifacts archive itself. The metadata file is in a binary format, with additional Gzip compression. -GitLab does not extract the artifacts archive in order to save space, memory -and disk I/O. It instead inspects the metadata file which contains all the -relevant information. This is especially important when there is a lot of -artifacts, or an archive is a very large file. +GitLab doesn't extract the artifacts archive to save space, memory, and disk +I/O. It instead inspects the metadata file which contains all the relevant +information. This is especially important when there is a lot of artifacts, or +an archive is a very large file. When clicking on a specific file, [GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) extracts it from the archive and the download begins. This implementation saves space, diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index c34035e3c0c..c89ffb8da8b 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -65,6 +65,15 @@ job logs are automatically migrated to it along with the other job artifacts. See "Phase 4: uploading" in [Data flow](#data-flow) to learn about the process. +## Prevent local disk usage + +If you want to avoid any local disk usage for job logs, +you can do so using one of the following options: + +- Enable the [beta incremental logging](#new-incremental-logging-architecture) feature. +- Set the [job logs location](#changing-the-job-logs-local-location) + to an NFS drive. + ## How to remove job logs There isn't a way to automatically expire old job logs, but it's safe to remove diff --git a/doc/administration/lfs/index.md b/doc/administration/lfs/index.md index 5c1a9519a35..a360542ac44 100644 --- a/doc/administration/lfs/index.md +++ b/doc/administration/lfs/index.md @@ -6,14 +6,16 @@ type: reference, howto disqus_identifier: 'https://docs.gitlab.com/ee/workflow/lfs/lfs_administration.html' --- -# GitLab Git Large File Storage (LFS) Administration +# GitLab Git Large File Storage (LFS) Administration **(CORE ONLY)** + +> - Git LFS is supported in GitLab starting with version 8.2. +> - Support for object storage, such as AWS S3, was introduced in 10.0. +> - LFS is enabled in GitLab self-managed instances by default. Documentation on how to use Git LFS are under [Managing large binary files with Git LFS doc](../../topics/git/lfs/index.md). ## Requirements -- Git LFS is supported in GitLab starting with version 8.2. -- Support for object storage, such as AWS S3, was introduced in 10.0. - Users need to install [Git LFS client](https://git-lfs.github.com) version 1.0.1 and up. ## Configuration @@ -41,6 +43,8 @@ gitlab_rails['lfs_enabled'] = false gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects" ``` +After you update settings in `/etc/gitlab/gitlab.rb`, make sure to run [Omnibus GitLab reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure). + ### Configuration for installations from source In `config/gitlab.yml`: diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md index beecd9e4783..a92e6fade03 100644 --- a/doc/administration/libravatar.md +++ b/doc/administration/libravatar.md @@ -1,4 +1,7 @@ --- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: howto --- @@ -72,10 +75,9 @@ Then run `sudo gitlab-ctl reconfigure` for the changes to take effect. missing images for user email addresses that are not found on the Libravatar service. -In order to use a set other than `identicon`, replace the `&d=identicon` -portion of the URL with another supported set. -For example, you can use the `retro` set, in which case the URL would look like: -`plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"` +To use a set other than `identicon`, replace the `&d=identicon` portion of the +URL with another supported set. For example, you can use the `retro` set, in +which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"` ## Usage examples for Microsoft Office 365 @@ -84,8 +86,8 @@ Note that this service requires a login, so this use case is most useful in a corporate installation where all users have access to Office 365. ```ruby -gitlab_rails['gravatar_plain_url'] = 'http://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' -gitlab_rails['gravatar_ssl_url'] = 'https://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' +gitlab_rails['gravatar_plain_url'] = 'http://outlook.office.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' +gitlab_rails['gravatar_ssl_url'] = 'https://outlook.office.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' ``` -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace - the file of the same name on this server. If that file is not on this server, - add the file from your Consul server to this server. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and + then replace the file of the same name on this server. If that file isn't on + this server, add the file from your Consul server to this server. -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). ### Gitaly TLS support @@ -1521,11 +1490,10 @@ Name. If you are addressing the Gitaly server by its IP address, you must add it as a Subject Alternative Name to the certificate. [gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). -NOTE: **Note:** -It is possible to configure Gitaly servers with both an -unencrypted listening address `listen_addr` and an encrypted listening -address `tls_listen_addr` at the same time. This allows you to do a -gradual transition from unencrypted to encrypted traffic, if necessary. +It's possible to configure Gitaly servers with both an unencrypted listening +address (`listen_addr`) and an encrypted listening address (`tls_listen_addr`) +at the same time. This allows you to do a gradual transition from unencrypted to +encrypted traffic, if necessary. To configure Gitaly with TLS: @@ -1580,10 +1548,10 @@ The following IPs will be used as an example: To configure the Sidekiq nodes, on each one: -1. SSH into the Sidekiq server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab package -you want using steps 1 and 2 from the GitLab downloads page. -**Do not complete any other steps on the download page.** +1. SSH in to the Sidekiq server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Open `/etc/gitlab/gitlab.rb` with your editor: ```ruby @@ -1701,15 +1669,14 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails -NOTE: **Note:** -In our architectures we run each GitLab Rails node using the Puma webserver -and have its number of workers set to 90% of available CPUs along with four threads. For -nodes that are running Rails with other components the worker value should be reduced -accordingly where we've found 50% achieves a good balance but this is dependent -on workload. - This section describes how to configure the GitLab application (Rails) component. +In our architecture, we run each GitLab Rails node using the Puma webserver, and +have its number of workers set to 90% of available CPUs, with four threads. For +nodes running Rails with other components, the worker value should be reduced +accordingly. We've determined that a worker value of 50% achieves a good balance, +but this is dependent on workload. + The following IPs will be used as an example: - `10.6.0.111`: GitLab application 1 @@ -1718,10 +1685,9 @@ The following IPs will be used as an example: On each node perform the following: -1. Download/install Omnibus GitLab using **steps 1 and 2** from - [GitLab downloads](https://about.gitlab.com/install/). Do not complete other - steps on the download page. - +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace the file of the same name on this server. If that file is not on this server, add the file from your Consul server to this server. @@ -1752,6 +1718,7 @@ On each node perform the following: roles ['application_role'] gitaly['enable'] = false nginx['enable'] = true + sidekiq['enable'] = false ## PostgreSQL connection details # Disable PostgreSQL on the application node @@ -1795,7 +1762,6 @@ On each node perform the following: # Set the network addresses that the exporters used for monitoring will listen on node_exporter['listen_address'] = '0.0.0.0:9100' gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229' - sidekiq['listen_address'] = "0.0.0.0" puma['listen'] = '0.0.0.0' # Add the monitoring node's IP address to the monitoring whitelist and allow it to @@ -1836,7 +1802,7 @@ On each node perform the following: 1. Specify the necessary NFS mounts in `/etc/fstab`. The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../high_availability/nfs.md) + to configure your NFS server. See the [NFS documentation](../nfs.md) for examples and the various options. 1. Create the shared directories. These may be different depending on your NFS @@ -1877,30 +1843,31 @@ On each node perform the following: 1. Optionally, from the Gitaly servers, confirm that Gitaly can perform callbacks to the internal API: ```shell - sudo /opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml + sudo /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml ``` -NOTE: **Note:** -When you specify `https` in the `external_url`, as in the example -above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If -certificates are not present, NGINX will fail to start. See the -[NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) -for more information. +When you specify `https` in the `external_url`, as in the previous example, +GitLab expects that the SSL certificates are in `/etc/gitlab/ssl/`. If the +certificates aren't present, NGINX will fail to start. For more information, see +the [NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https). ### GitLab Rails post-configuration -Initialize the GitLab database, by running the following in one of the Rails nodes: +1. Designate one application node for running database migrations during + installation and updates. Initialize the GitLab database and ensure all + migrations ran: -```shell -sudo gitlab-rake gitlab:db:configure -``` + ```shell + sudo gitlab-rake gitlab:db:configure + ``` -NOTE: **Note:** -If you encounter a `rake aborted!` error stating that PgBouncer is failing to connect to -PostgreSQL it may be that your PgBouncer node's IP address is missing from -PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` on your database nodes. See -[PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server) -in the Troubleshooting section before proceeding. + If you encounter a `rake aborted!` error message stating that PgBouncer is + failing to connect to PostgreSQL, it may be that your PgBouncer node's IP + address is missing from PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` + on your database nodes. Before proceeding, see + [PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server). + +1. [Configure fast lookup of authorized SSH keys in the database](../operations/fast_ssh_key_lookup.md).
@@ -1920,11 +1887,10 @@ The following IP will be used as an example: To configure the Monitoring node: -1. SSH into the Monitoring node. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - Do not complete any other steps on the download page. - +1. SSH in to the Monitoring node. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace the file of the same name on this server. If that file is not on this server, add the file from your Consul server to this server. @@ -1988,28 +1954,44 @@ It's recommended over [NFS](#configure-nfs-optional) and in general it's better in larger setups as object storage is typically much more performant, reliable, and scalable. -Object storage options that GitLab has tested, or is aware of customers using include: +GitLab has been tested on a number of object storage providers: -- SaaS/Cloud solutions such as [Amazon S3](https://aws.amazon.com/s3/), [Google cloud storage](https://cloud.google.com/storage). +- [Amazon S3](https://aws.amazon.com/s3/) +- [Google Cloud Storage](https://cloud.google.com/storage) +- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces/) +- [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) +- [Openstack Swift](https://docs.openstack.org/swift/latest/s3_compat.html) +- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - On-premises hardware and appliances from various storage vendors. -- MinIO. There is [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. - -For configuring GitLab to use Object Storage refer to the following guides -based on what features you intend to use: - -1. Configure [object storage for backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage). -1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) - including [incremental logging](../job_logs.md#new-incremental-logging-architecture). -1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage). -1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). -1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). -1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). -1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). +- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. + +There are two ways of specifying object storage configuration in GitLab: + +- [Consolidated form](../object_storage.md#consolidated-object-storage-configuration): A single credential is + shared by all supported object types. +- [Storage-specific form](../object_storage.md#storage-specific-configuration): Every object defines its + own object storage [connection and configuration](../object_storage.md#connection-settings). + +Starting with GitLab 13.2, consolidated object storage configuration is available. It simplifies your GitLab configuration since the connection details are shared across object types. Refer to [Consolidated object storage configuration](../object_storage.md#consolidated-object-storage-configuration) guide for instructions on how to set it up. + +For configuring object storage in GitLab 13.1 and earlier, or for storage types not +supported by consolidated configuration form, refer to the following guides based +on what features you intend to use: + +|Object storage type|Supported by consolidated configuration?| +|-------------------|----------------------------------------| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | +| [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | +| [Uploads](../uploads.md#using-object-storage) | Yes | +| [Container Registry](../packages/container_registry.md#use-object-storage) (optional feature) | No | +| [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | +| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | +| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | +| [Terraform state files](../terraform_state.md#using-object-storage) | Yes | Using separate buckets for each data type is the recommended approach for GitLab. @@ -2033,13 +2015,29 @@ work.
+## Configure Advanced Search **(STARTER ONLY)** + +You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) +for faster, more advanced code search across your entire GitLab instance. + +Elasticsearch cluster design and requirements are dependent on your specific +data. For recommended best practices about how to set up your Elasticsearch +cluster alongside your instance, read how to +[choose the optimal cluster configuration](../../integration/elasticsearch.md#guidance-on-choosing-optimal-cluster-configuration). + +
+ + Back to setup components + +
+ ## Configure NFS (optional) [Object storage](#configure-the-object-storage), along with [Gitaly](#configure-gitaly) are recommended over NFS wherever possible for improved performance. If you intend to use GitLab Pages, this currently [requires NFS](troubleshooting.md#gitlab-pages-requires-nfs). -See how to [configure NFS](../high_availability/nfs.md). +See how to [configure NFS](../nfs.md).
diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index d376c1b7575..0cb7b8868c3 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -20,8 +20,8 @@ many organizations . | Users | Configuration | GCP | AWS | Azure | |--------------|-------------------------|----------------|-----------------|----------------| -| Up to 500 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | -| Up to 1,000 | 8 vCPU, 7.2GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | +| Up to 500 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| Up to 1,000 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) @@ -30,20 +30,28 @@ or higher, are required for your CPU or node counts. For more information, see our [Sysbench](https://github.com/akopytov/sysbench)-based [CPU benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks). -In addition to the stated configurations, we recommend having at least 2GB of +In addition to the stated configurations, we recommend having at least 2 GB of swap on your server, even if you currently have enough available memory. Having -swap will help reduce the chance of errors occurring if your available memory +swap helps to reduce the chance of errors occurring if your available memory changes. We also recommend configuring the kernel's swappiness setting to a lower value (such as `10`) to make the most of your memory, while still having the swap available when needed. ## Setup instructions -For this default reference architecture, to install GitLab use the standard +To install GitLab for this default reference architecture, use the standard [installation instructions](../../install/README.md). -NOTE: **Note:** -You can also optionally configure GitLab to use an -[external PostgreSQL service](../postgresql/external.md) or an -[external object storage service](../high_availability/object_storage.md) for -added performance and reliability at a reduced complexity cost. +You can also optionally configure GitLab to use an [external PostgreSQL service](../postgresql/external.md) +or an [external object storage service](../object_storage.md) for added +performance and reliability at a reduced complexity cost. + +## Configure Advanced Search **(STARTER ONLY)** + +You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) +for faster, more advanced code search across your entire GitLab instance. + +Elasticsearch cluster design and requirements are dependent on your specific +data. For recommended best practices about how to set up your Elasticsearch +cluster alongside your instance, read how to +[choose the optimal cluster configuration](../../integration/elasticsearch.md#guidance-on-choosing-optimal-cluster-configuration). diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 2ef555bff29..bb6e2eb4376 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -17,21 +17,21 @@ full list of reference architectures, see | Service | Nodes | Configuration | GCP | AWS | Azure | |-----------------------------------------|-------------|-------------------------|-----------------|-------------|----------| -| External load balancing node | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | -| Consul | 3 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 3 | 8 vCPU, 30GB memory | n1-standard-8 | m5.2xlarge | D8s v3 | -| PgBouncer | 3 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Internal load balancing node | 1 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Redis - Cache | 3 | 4 vCPU, 15GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis - Queues / Shared State | 3 | 4 vCPU, 15GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7GB memory | g1-small | t2.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7GB memory | g1-small | t2.small | B1MS | -| Gitaly | 2 (minimum) | 32 vCPU, 120GB memory | n1-standard-32 | m5.8xlarge | D32s v3 | -| Sidekiq | 4 | 4 vCPU, 15GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| GitLab Rails | 5 | 32 vCPU, 28.8GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | -| Monitoring node | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | -| Object Storage | n/a | n/a | n/a | n/a | n/a | -| NFS Server | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| External load balancing node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| Consul | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| PostgreSQL | 3 | 8 vCPU, 30 GB memory | n1-standard-8 | m5.2xlarge | D8s v3 | +| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Internal load balancing node | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.large | F2s v2 | +| Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | +| Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Gitaly | 2 (minimum) | 32 vCPU, 120 GB memory | n1-standard-32 | m5.8xlarge | D32s v3 | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | +| GitLab Rails | 5 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| Object storage | n/a | n/a | n/a | n/a | n/a | +| NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) @@ -40,41 +40,43 @@ or higher, are required for your CPU or node counts. For more information, see our [Sysbench](https://github.com/akopytov/sysbench)-based [CPU benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks). -For data objects (such as LFS, Uploads, or Artifacts), an -[object storage service](#configure-the-object-storage) is recommended instead -of NFS where possible, due to better performance and availability. Since this -doesn't require a node to be set up, *Object Storage* is noted as not -applicable (n/a) in the previous table. +Due to better performance and availability, for data objects (such as LFS, +uploads, or artifacts), using an [object storage service](#configure-the-object-storage) +is recommended instead of using NFS. Using an object storage service also +doesn't require you to provision and maintain a node. ## Setup components To set up GitLab and its components to accommodate up to 25,000 users: 1. [Configure the external load balancing node](#configure-the-external-load-balancer) - that will handle the load balancing of the three GitLab application services nodes. + to handle the load balancing of the GitLab application services nodes. 1. [Configure Consul](#configure-consul). 1. [Configure PostgreSQL](#configure-postgresql), the database for GitLab. 1. [Configure PgBouncer](#configure-pgbouncer). -1. [Configure the internal load balancing node](#configure-the-internal-load-balancer) +1. [Configure the internal load balancing node](#configure-the-internal-load-balancer). 1. [Configure Redis](#configure-redis). 1. [Configure Gitaly](#configure-gitaly), which provides access to the Git repositories. 1. [Configure Sidekiq](#configure-sidekiq). 1. [Configure the main GitLab Rails application](#configure-gitlab-rails) - to run Puma/Unicorn, Workhorse, GitLab Shell, and to serve all frontend requests (UI, API, Git - over HTTP/SSH). -1. [Configure Prometheus](#configure-prometheus) to monitor your GitLab environment. -1. [Configure the Object Storage](#configure-the-object-storage) + to run Puma/Unicorn, Workhorse, GitLab Shell, and to serve all frontend + requests (which include UI, API, and Git over HTTP/SSH). +1. [Configure Prometheus](#configure-prometheus) to monitor your GitLab + environment. +1. [Configure the object storage](#configure-the-object-storage) used for shared data objects. -1. [Configure NFS (Optional)](#configure-nfs-optional) - to have shared disk storage service as an alternative to Gitaly and/or Object Storage (although - not recommended). NFS is required for GitLab Pages, you can skip this step if you're not using - that feature. +1. [Configure Advanced Search](#configure-advanced-search) (optional) for faster, + more advanced code search across your entire GitLab instance. +1. [Configure NFS](#configure-nfs-optional) (optional, and not recommended) + to have shared disk storage service as an alternative to Gitaly or object + storage. You can skip this step if you're not using GitLab Pages (which + requires NFS). -We start with all servers on the same 10.6.0.0/24 private network range, they -can connect to each other freely on those addresses. +The servers start on the same 10.6.0.0/24 private network range, and can +connect to each other freely on these addresses. -Here is a list and description of each machine and the assigned IP: +The following list includes descriptions of each server and its assigned IP: - `10.6.0.10`: External Load Balancer - `10.6.0.11`: Consul 1 @@ -112,19 +114,18 @@ Here is a list and description of each machine and the assigned IP: ## Configure the external load balancer -NOTE: **Note:** +In an active/active GitLab configuration, you'll need a load balancer to route +traffic to the application servers. The specifics on which load balancer to use +or its exact configuration is beyond the scope of GitLab documentation. We hope +that if you're managing multi-node systems like GitLab, you already have a load +balancer of choice. Some load balancer examples include HAProxy (open-source), +F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and +protocols needed for use with GitLab. + This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) as the load balancer. Although other load balancers with similar feature sets could also be used, those load balancers have not been validated. -In an active/active GitLab configuration, you will need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or the exact configuration is beyond the scope of GitLab documentation. We hope -that if you're managing multi-node systems like GitLab you have a load balancer of -choice already. Some examples including HAProxy (open-source), F5 Big-IP LTM, -and Citrix Net Scaler. This documentation will outline what ports and protocols -you need to use with GitLab. - The next question is how you will handle SSL in your environment. There are several different options: @@ -247,14 +248,11 @@ with the other servers. To configure Consul: -1. SSH into the server that will host Consul. -1. [Download/install](https://about.gitlab.com/install/) the - Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the - GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. - +1. SSH in to the server that will host Consul. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -282,10 +280,9 @@ To configure Consul: 1. Go through the steps again for all the other Consul nodes, and make sure you set up the correct IPs. -NOTE: **Note:** -A Consul leader will be elected when the provisioning of the third Consul server is completed. -Viewing the Consul logs `sudo gitlab-ctl tail consul` will display -`...[INFO] consul: New leader elected: ...` +A Consul leader is _elected_ when the provisioning of the third Consul server is +complete. Viewing the Consul logs `sudo gitlab-ctl tail consul` displays +`...[INFO] consul: New leader elected: ...`. You can list the current Consul members (server, client): @@ -352,7 +349,7 @@ in the second step, do not supply the `EXTERNAL_URL` value. #### PostgreSQL primary node -1. SSH into the PostgreSQL primary node. +1. SSH in to the PostgreSQL primary node. 1. Generate a password hash for the PostgreSQL username/password pair. This assumes you will use the default username of `gitlab` (recommended). The command will request a password and confirmation. Use the value that is output by this command in the next @@ -513,7 +510,7 @@ are supported and can be added if needed. #### PostgreSQL post-configuration -SSH into the **primary node**: +SSH in to the **primary node**: 1. Open a database prompt: @@ -548,7 +545,7 @@ SSH into the **primary node**: is not an IP address, it will need to be a resolvable name (via DNS or `/etc/hosts`) -SSH into the **secondary node**: +SSH in to the **secondary node**: 1. Set up the repmgr standby: @@ -662,7 +659,6 @@ The following IPs will be used as an example: 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. - NOTE: **Note:** If an error `execute[generate databases.ini]` occurs, this is due to an existing [known issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4713). It will be resolved when you run a second `reconfigure` after the next step. @@ -796,35 +792,31 @@ to be used with GitLab. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -NOTE: **Providing your own Redis instance:** -Managed Redis from cloud providers such as AWS ElastiCache will work. If these -services support high availability, be sure it is **not** the Redis Cluster type. -Redis version 5.0 or higher is required, as this is what ships with -Omnibus GitLab packages starting with GitLab 13.0. Older Redis versions -do not support an optional count argument to SPOP which is now required for -[Merge Trains](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). +### Providing your own Redis instance + +Managed Redis from cloud providers (such as AWS ElastiCache) will work. If these +services support high availability, be sure it _isn't_ of the Redis Cluster type. +Redis version 5.0 or higher is required, which is included with Omnibus GitLab +packages starting with GitLab 13.0. Older Redis versions don't support an +optional count argument to SPOP, which is required for [Merge Trains](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). Note the Redis node's IP address or hostname, port, and password (if required). -These will be necessary when configuring the -[GitLab application servers](#configure-gitlab-rails) later. +These will be necessary later when configuring the [GitLab application servers](#configure-gitlab-rails). ### Configure the Redis and Sentinel Cache cluster This is the section where we install and set up the new Redis Cache instances. -NOTE: **Note:** -Redis nodes (both primary and replica) will need the same password defined in -`redis['password']`. At any time during a failover the Sentinels can -reconfigure a node and change its status from primary to replica and vice versa. +Both the primary and replica Redis nodes need the same password defined in +`redis['password']`. At any time during a failover, the Sentinels can reconfigure +a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Cache node -1. SSH into the **Primary** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **Primary** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -868,20 +860,17 @@ reconfigure a node and change its status from primary to replica and vice versa. 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). #### Configure the replica Redis Cache nodes -1. SSH into the **replica** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **replica** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -934,10 +923,9 @@ Read more about [roles](https://docs.gitlab.com/omnibus/roles/). 1. Go through the steps again for all the other replica nodes, and make sure to set up the IPs correctly. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). These values don't have to be changed again in `/etc/gitlab/gitlab.rb` after a failover, as the nodes will be managed by the [Sentinels](#configure-the-sentinel-cache-nodes), and even after a @@ -955,13 +943,6 @@ are supported and can be added if needed. #### Configure the Sentinel Cache nodes -NOTE: **Note:** -If you are using an external Redis Sentinel instance, be sure -to exclude the `requirepass` parameter from the Sentinel -configuration. This parameter will cause clients to report `NOAUTH -Authentication required.`. [Redis Sentinel 3.2.x does not support -password authentication](https://github.com/antirez/redis/issues/3279). - Now that the Redis servers are all set up, let's configure the Sentinel servers. The following IPs will be used as an example: @@ -969,16 +950,19 @@ servers. The following IPs will be used as an example: - `10.6.0.72`: Sentinel - Cache 2 - `10.6.0.73`: Sentinel - Cache 3 -To configure the Sentinel Cache server: +NOTE: **Note:** +If you're using an external Redis Sentinel instance, be sure to exclude the +`requirepass` parameter from the Sentinel configuration. This parameter causes +clients to report `NOAUTH Authentication required.`. +[Redis Sentinel 3.2.x doesn't support password authentication](https://github.com/antirez/redis/issues/3279). -1. SSH into the server that will host Consul/Sentinel. -1. [Download/install](https://about.gitlab.com/install/) the - Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the - GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. +To configure the Sentinel Cache server: +1. SSH in to the server that will host Consul/Sentinel. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1081,20 +1065,17 @@ To configure the Sentinel Cache server: This is the section where we install and set up the new Redis Queues instances. -NOTE: **Note:** -Redis nodes (both primary and replica) will need the same password defined in -`redis['password']`. At any time during a failover the Sentinels can -reconfigure a node and change its status from primary to replica and vice versa. +Both the primary and replica Redis nodes need the same password defined in +`redis['password']`. At any time during a failover, the Sentinels can reconfigure +a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Queues node -1. SSH into the **Primary** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **Primary** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1143,20 +1124,17 @@ reconfigure a node and change its status from primary to replica and vice versa. 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). #### Configure the replica Redis Queues nodes -1. SSH into the **replica** Redis Queue server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **replica** Redis Queue server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1209,10 +1187,9 @@ Read more about [roles](https://docs.gitlab.com/omnibus/roles/). 1. Go through the steps again for all the other replica nodes, and make sure to set up the IPs correctly. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). These values don't have to be changed again in `/etc/gitlab/gitlab.rb` after a failover, as the nodes will be managed by the [Sentinels](#configure-the-sentinel-queues-nodes), and even after a @@ -1230,13 +1207,6 @@ are supported and can be added if needed. #### Configure the Sentinel Queues nodes -NOTE: **Note:** -If you are using an external Redis Sentinel instance, be sure -to exclude the `requirepass` parameter from the Sentinel -configuration. This parameter will cause clients to report `NOAUTH -Authentication required.`. [Redis Sentinel 3.2.x does not support -password authentication](https://github.com/antirez/redis/issues/3279). - Now that the Redis servers are all set up, let's configure the Sentinel servers. The following IPs will be used as an example: @@ -1244,16 +1214,19 @@ servers. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -To configure the Sentinel Queues server: +NOTE: **Note:** +If you're using an external Redis Sentinel instance, be sure to exclude the +`requirepass` parameter from the Sentinel configuration. This parameter causes +clients to report `NOAUTH Authentication required.`. +[Redis Sentinel 3.2.x doesn't support password authentication](https://github.com/antirez/redis/issues/3279). -1. SSH into the server that will host Sentinel. -1. [Download/install](https://about.gitlab.com/install/) the - Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the - GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. +To configure the Sentinel Queues server: +1. SSH in to the server that will host Sentinel. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1362,52 +1335,48 @@ To configure the Sentinel Queues server: ## Configure Gitaly -Deploying Gitaly in its own server can benefit GitLab installations that are -larger than a single machine. - -The Gitaly node requirements are dependent on customer data, specifically the number of -projects and their repository sizes. Two nodes are recommended as an absolute minimum. -Each Gitaly node should store no more than 5TB of data and have the number of -[`gitaly-ruby` workers](../gitaly/index.md#gitaly-ruby) set to 20% of available CPUs. -Additional nodes should be considered in conjunction with a review of expected -data size and spread based on the recommendations above. - -It is also strongly recommended that all Gitaly nodes be set up with SSD disks with -a throughput of at least 8,000 IOPS for read operations and 2,000 IOPS for write, -as Gitaly has heavy I/O. These IOPS values are recommended only as a starter as with -time they may be adjusted higher or lower depending on the scale of your environment's workload. -If you're running the environment on a Cloud provider, you may need to refer to -their documentation on how to configure IOPS correctly. - -Some things to note: - -- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md). -- A Gitaly server can host one or more storages. -- A GitLab server can use one or more Gitaly servers. -- Gitaly addresses must be specified in such a way that they resolve - correctly for ALL Gitaly clients. +[Gitaly](../gitaly/index.md) server node requirements are dependent on data, +specifically the number of projects and those projects' sizes. It's recommended +that a Gitaly server node stores no more than 5 TB of data. Although this +reference architecture includes a recommendation for the number of Gitaly server +nodes to use, depending on your storage requirements, you may require additional +Gitaly server nodes. + +Due to Gitaly having notable input and output requirements, we strongly +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should +have a throughput of at least 8,000 input/output operations per second (IOPS) +for read operations and 2,000 IOPS for write operations. These IOPS values are +initial recommendations, and may be adjusted to greater or lesser values +depending on the scale of your environment's workload. If you're running the +environment on a Cloud provider, refer to their documentation about how to +configure IOPS correctly. + +Be sure to note the following items: + +- The GitLab Rails application shards repositories into + [repository storage paths](../repository_storage_paths.md). +- A Gitaly server can host one or more storage paths. +- A GitLab server can use one or more Gitaly server nodes. +- Gitaly addresses must be specified to be correctly resolvable for _all_ + Gitaly clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -TIP: **Tip:** -For more information about Gitaly's history and network architecture see the -[standalone Gitaly documentation](../gitaly/index.md). - -Note: **Note:** -The token referred to throughout the Gitaly documentation is -just an arbitrary password selected by the administrator. It is unrelated to -tokens created for the GitLab API or other similar web API tokens. +NOTE: **Note:** +The token referred to throughout the Gitaly documentation is an arbitrary +password selected by the administrator. This token is unrelated to tokens +created for the GitLab API or other similar web API tokens. -Below we describe how to configure two Gitaly servers, with IPs and -domain names: +This section describes how to configure two Gitaly servers, with the following +IPs and domain names: - `10.6.0.91`: Gitaly 1 (`gitaly1.internal`) - `10.6.0.92`: Gitaly 2 (`gitaly2.internal`) -The secret token is assumed to be `gitalysecret` and that -your GitLab installation has three repository storages: +Assumptions about your servers include having the secret token be `gitalysecret`, +and that your GitLab installation has three repository storages: - `default` on Gitaly 1 - `storage1` on Gitaly 1 @@ -1415,11 +1384,11 @@ your GitLab installation has three repository storages: On each node: -1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page but - **without** providing the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable - the network listener and configure the token: +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and _do not_ provide the `EXTERNAL_URL` value. +1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable + the network listener, and configure the token: -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace - the file of the same name on this server. If that file is not on this server, - add the file from your Consul server to this server. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and + then replace the file of the same name on this server. If that file isn't on + this server, add the file from your Consul server to this server. -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). ### Gitaly TLS support @@ -1521,11 +1490,10 @@ Name. If you are addressing the Gitaly server by its IP address, you must add it as a Subject Alternative Name to the certificate. [gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). -NOTE: **Note:** -It is possible to configure Gitaly servers with both an -unencrypted listening address `listen_addr` and an encrypted listening -address `tls_listen_addr` at the same time. This allows you to do a -gradual transition from unencrypted to encrypted traffic, if necessary. +It's possible to configure Gitaly servers with both an unencrypted listening +address (`listen_addr`) and an encrypted listening address (`tls_listen_addr`) +at the same time. This allows you to do a gradual transition from unencrypted to +encrypted traffic, if necessary. To configure Gitaly with TLS: @@ -1580,10 +1548,10 @@ The following IPs will be used as an example: To configure the Sidekiq nodes, on each one: -1. SSH into the Sidekiq server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab package -you want using steps 1 and 2 from the GitLab downloads page. -**Do not complete any other steps on the download page.** +1. SSH in to the Sidekiq server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Open `/etc/gitlab/gitlab.rb` with your editor: ```ruby @@ -1701,15 +1669,14 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails -NOTE: **Note:** -In our architectures we run each GitLab Rails node using the Puma webserver -and have its number of workers set to 90% of available CPUs along with four threads. For -nodes that are running Rails with other components the worker value should be reduced -accordingly where we've found 50% achieves a good balance but this is dependent -on workload. - This section describes how to configure the GitLab application (Rails) component. +In our architecture, we run each GitLab Rails node using the Puma webserver, and +have its number of workers set to 90% of available CPUs, with four threads. For +nodes running Rails with other components, the worker value should be reduced +accordingly. We've determined that a worker value of 50% achieves a good balance, +but this is dependent on workload. + The following IPs will be used as an example: - `10.6.0.111`: GitLab application 1 @@ -1718,10 +1685,9 @@ The following IPs will be used as an example: On each node perform the following: -1. Download/install Omnibus GitLab using **steps 1 and 2** from - [GitLab downloads](https://about.gitlab.com/install/). Do not complete other - steps on the download page. - +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace the file of the same name on this server. If that file is not on this server, add the file from your Consul server to this server. @@ -1752,6 +1718,7 @@ On each node perform the following: roles ['application_role'] gitaly['enable'] = false nginx['enable'] = true + sidekiq['enable'] = false ## PostgreSQL connection details # Disable PostgreSQL on the application node @@ -1795,7 +1762,6 @@ On each node perform the following: # Set the network addresses that the exporters used for monitoring will listen on node_exporter['listen_address'] = '0.0.0.0:9100' gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229' - sidekiq['listen_address'] = "0.0.0.0" puma['listen'] = '0.0.0.0' # Add the monitoring node's IP address to the monitoring whitelist and allow it to @@ -1836,7 +1802,7 @@ On each node perform the following: 1. Specify the necessary NFS mounts in `/etc/fstab`. The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../high_availability/nfs.md) + to configure your NFS server. See the [NFS documentation](../nfs.md) for examples and the various options. 1. Create the shared directories. These may be different depending on your NFS @@ -1877,30 +1843,31 @@ On each node perform the following: 1. Optionally, from the Gitaly servers, confirm that Gitaly can perform callbacks to the internal API: ```shell - sudo /opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml + sudo /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml ``` -NOTE: **Note:** -When you specify `https` in the `external_url`, as in the example -above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If -certificates are not present, NGINX will fail to start. See the -[NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) -for more information. +When you specify `https` in the `external_url`, as in the previous example, +GitLab expects that the SSL certificates are in `/etc/gitlab/ssl/`. If the +certificates aren't present, NGINX will fail to start. For more information, see +the [NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https). ### GitLab Rails post-configuration -Initialize the GitLab database, by running the following in one of the Rails nodes: +1. Designate one application node for running database migrations during + installation and updates. Initialize the GitLab database and ensure all + migrations ran: -```shell -sudo gitlab-rake gitlab:db:configure -``` + ```shell + sudo gitlab-rake gitlab:db:configure + ``` -NOTE: **Note:** -If you encounter a `rake aborted!` error stating that PgBouncer is failing to connect to -PostgreSQL it may be that your PgBouncer node's IP address is missing from -PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` on your database nodes. See -[PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server) -in the Troubleshooting section before proceeding. + If you encounter a `rake aborted!` error message stating that PgBouncer is + failing to connect to PostgreSQL, it may be that your PgBouncer node's IP + address is missing from PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` + on your database nodes. Before proceeding, see + [PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server). + +1. [Configure fast lookup of authorized SSH keys in the database](../operations/fast_ssh_key_lookup.md).
@@ -1920,11 +1887,10 @@ The following IP will be used as an example: To configure the Monitoring node: -1. SSH into the Monitoring node. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - Do not complete any other steps on the download page. - +1. SSH in to the Monitoring node. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace the file of the same name on this server. If that file is not on this server, add the file from your Consul server to this server. @@ -1988,28 +1954,44 @@ It's recommended over [NFS](#configure-nfs-optional) and in general it's better in larger setups as object storage is typically much more performant, reliable, and scalable. -Object storage options that GitLab has tested, or is aware of customers using include: +GitLab has been tested on a number of object storage providers: -- SaaS/Cloud solutions such as [Amazon S3](https://aws.amazon.com/s3/), [Google cloud storage](https://cloud.google.com/storage). +- [Amazon S3](https://aws.amazon.com/s3/) +- [Google Cloud Storage](https://cloud.google.com/storage) +- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces/) +- [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) +- [Openstack Swift](https://docs.openstack.org/swift/latest/s3_compat.html) +- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - On-premises hardware and appliances from various storage vendors. -- MinIO. There is [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. - -For configuring GitLab to use Object Storage refer to the following guides -based on what features you intend to use: - -1. Configure [object storage for backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage). -1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) - including [incremental logging](../job_logs.md#new-incremental-logging-architecture). -1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage). -1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). -1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). -1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). -1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). +- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. + +There are two ways of specifying object storage configuration in GitLab: + +- [Consolidated form](../object_storage.md#consolidated-object-storage-configuration): A single credential is + shared by all supported object types. +- [Storage-specific form](../object_storage.md#storage-specific-configuration): Every object defines its + own object storage [connection and configuration](../object_storage.md#connection-settings). + +Starting with GitLab 13.2, consolidated object storage configuration is available. It simplifies your GitLab configuration since the connection details are shared across object types. Refer to [Consolidated object storage configuration](../object_storage.md#consolidated-object-storage-configuration) guide for instructions on how to set it up. + +For configuring object storage in GitLab 13.1 and earlier, or for storage types not +supported by consolidated configuration form, refer to the following guides based +on what features you intend to use: + +|Object storage type|Supported by consolidated configuration?| +|-------------------|----------------------------------------| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | +| [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | +| [Uploads](../uploads.md#using-object-storage) | Yes | +| [Container Registry](../packages/container_registry.md#use-object-storage) (optional feature) | No | +| [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | +| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | +| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | +| [Terraform state files](../terraform_state.md#using-object-storage) | Yes | Using separate buckets for each data type is the recommended approach for GitLab. @@ -2033,13 +2015,29 @@ work.
+## Configure Advanced Search **(STARTER ONLY)** + +You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) +for faster, more advanced code search across your entire GitLab instance. + +Elasticsearch cluster design and requirements are dependent on your specific +data. For recommended best practices about how to set up your Elasticsearch +cluster alongside your instance, read how to +[choose the optimal cluster configuration](../../integration/elasticsearch.md#guidance-on-choosing-optimal-cluster-configuration). + +
+ + Back to setup components + +
+ ## Configure NFS (optional) [Object storage](#configure-the-object-storage), along with [Gitaly](#configure-gitaly) are recommended over NFS wherever possible for improved performance. If you intend to use GitLab Pages, this currently [requires NFS](troubleshooting.md#gitlab-pages-requires-nfs). -See how to [configure NFS](../high_availability/nfs.md). +See how to [configure NFS](../nfs.md).
diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index 34b90964fbf..4863329b695 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -17,14 +17,14 @@ For a full list of reference architectures, see | Service | Nodes | Configuration | GCP | AWS | Azure | |------------------------------------------|--------|-------------------------|----------------|--------------|---------| -| Load balancer | 1 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 1 | 2 vCPU, 7.5GB memory | n1-standard-2 | m5.large | D2s v3 | -| Redis | 1 | 1 vCPU, 3.75GB memory | n1-standard-1 | m5.large | D2s v3 | -| Gitaly | 1 | 4 vCPU, 15GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| GitLab Rails | 2 | 8 vCPU, 7.2GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | -| Monitoring node | 1 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Load balancer | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| PostgreSQL | 1 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | +| Redis | 1 | 1 vCPU, 3.75 GB memory | n1-standard-1 | m5.large | D2s v3 | +| Gitaly | 1 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | +| GitLab Rails | 2 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | | Object storage | n/a | n/a | n/a | n/a | n/a | -| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) @@ -43,7 +43,7 @@ doesn't require you to provision and maintain a node. To set up GitLab and its components to accommodate up to 2,000 users: 1. [Configure the external load balancing node](#configure-the-external-load-balancer) - to handle the load balancing of the two GitLab application services nodes. + to handle the load balancing of the GitLab application services nodes. 1. [Configure PostgreSQL](#configure-postgresql), the database for GitLab. 1. [Configure Redis](#configure-redis). 1. [Configure Gitaly](#configure-gitaly), which provides access to the Git @@ -55,6 +55,8 @@ To set up GitLab and its components to accommodate up to 2,000 users: environment. 1. [Configure the object storage](#configure-the-object-storage) used for shared data objects. +1. [Configure Advanced Search](#configure-advanced-search) (optional) for faster, + more advanced code search across your entire GitLab instance. 1. [Configure NFS](#configure-nfs-optional) (optional, and not recommended) to have shared disk storage service as an alternative to Gitaly or object storage. You can skip this step if you're not using GitLab Pages (which @@ -62,18 +64,17 @@ To set up GitLab and its components to accommodate up to 2,000 users: ## Configure the external load balancer -NOTE: **Note:** -This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/). -Although you can use a load balancer with a similar set of features, GitLab -hasn't validated other load balancers. - In an active/active GitLab configuration, you'll need a load balancer to route -traffic to the application servers. The specifics for which load balancer to -use or its exact configuration is out of scope for the GitLab documentation. -If you're managing multi-node systems (including GitLab) you'll probably -already have a load balancer of choice. Some examples including HAProxy -(open-source), F5 Big-IP LTM, and Citrix Net Scaler. This documentation -includes the ports and protocols for use with GitLab. +traffic to the application servers. The specifics on which load balancer to use +or its exact configuration is beyond the scope of GitLab documentation. We hope +that if you're managing multi-node systems like GitLab, you already have a load +balancer of choice. Some load balancer examples include HAProxy (open-source), +F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and +protocols needed for use with GitLab. + +This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) +as the load balancer. Although other load balancers with similar feature sets +could also be used, those load balancers have not been validated. The next question is how you will handle SSL in your environment. There are several different options: @@ -206,10 +207,10 @@ further configuration steps. ### Standalone PostgreSQL using Omnibus GitLab -1. SSH into the PostgreSQL server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Do not complete any other steps on the download page. +1. SSH in to the PostgreSQL server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Generate a password hash for PostgreSQL. This assumes you will use the default username of `gitlab` (recommended). The command will request a password and confirmation. Use the value that is output by this command in the next @@ -300,11 +301,10 @@ The Omnibus GitLab package can be used to configure a standalone Redis server. The steps below are the minimum necessary to configure a Redis server with Omnibus: -1. SSH into the Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Do not complete any other steps on the download page. - +1. SSH in to the Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -393,12 +393,11 @@ The following procedure describes how to configure a single Gitaly server named `gitaly1.internal` with the secret token `gitalysecret`. We assume your GitLab installation has two repository storages: `default` and `storage1`. -To configure the Gitaly server: +To configure the Gitaly server, on the server node you want to use for Gitaly: -1. On the server node you want to use for Gitaly, - [download and install](https://about.gitlab.com/install/) your selected - Omnibus GitLab package using *steps 1 and 2* from the GitLab downloads page, - but *without* providing the `EXTERNAL_URL` value. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and _do not_ provide the `EXTERNAL_URL` value. 1. Edit the Gitaly server node's `/etc/gitlab/gitlab.rb` file to configure storage paths, enable the network listener, and to configure the token: @@ -464,7 +463,7 @@ To configure the Gitaly server: 1. Confirm that Gitaly can perform callbacks to the internal API: ```shell - sudo /opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml + sudo /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml ``` ### Gitaly TLS support @@ -487,11 +486,10 @@ Name. If you are addressing the Gitaly server by its IP address, you must add it as a Subject Alternative Name to the certificate. [gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). -NOTE: **Note:** -It is possible to configure Gitaly servers with both an -unencrypted listening address `listen_addr` and an encrypted listening -address `tls_listen_addr` at the same time. This allows you to do a -gradual transition from unencrypted to encrypted traffic, if necessary. +It's possible to configure Gitaly servers with both an unencrypted listening +address (`listen_addr`) and an encrypted listening address (`tls_listen_addr`) +at the same time. This allows you to do a gradual transition from unencrypted to +encrypted traffic, if necessary. To configure Gitaly with TLS: @@ -535,14 +533,14 @@ To configure Gitaly with TLS: ## Configure GitLab Rails -NOTE: **Note:** -In our architectures we run each GitLab Rails node using the Puma webserver -and have its number of workers set to 90% of available CPUs along with four threads. For -nodes that are running Rails with other components the worker value should be reduced -accordingly where we've found 50% achieves a good balance but this is dependent -on workload. - This section describes how to configure the GitLab application (Rails) component. + +In our architecture, we run each GitLab Rails node using the Puma webserver, and +have its number of workers set to 90% of available CPUs, with four threads. For +nodes running Rails with other components, the worker value should be reduced +accordingly. We've determined that a worker value of 50% achieves a good balance, +but this is dependent on workload. + On each node perform the following: 1. If you're [using NFS](#configure-nfs-optional): @@ -570,10 +568,10 @@ On each node perform the following: mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data ``` -1. Download/install Omnibus GitLab using **steps 1 and 2** from - [GitLab downloads](https://about.gitlab.com/install/). Do not complete other - steps on the download page. -1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. +1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration. To maintain uniformity of links across nodes, the `external_url` on the application server should point to the external URL that users will use to access GitLab. This would be the URL of the [load balancer](#configure-the-external-load-balancer) @@ -664,12 +662,33 @@ On each node perform the following: sudo gitlab-ctl tail gitaly ``` -NOTE: **Note:** -When you specify `https` in the `external_url`, as in the example -above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If -certificates are not present, NGINX will fail to start. See the -[NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) -for more information. +1. Save the `/etc/gitlab/gitlab-secrets.json` file from one of the two + application nodes and install it on the other application node and the + [Gitaly node](#configure-gitaly) and + [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +When you specify `https` in the `external_url`, as in the previous example, +GitLab expects that the SSL certificates are in `/etc/gitlab/ssl/`. If the +certificates aren't present, NGINX will fail to start. For more information, see +the [NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https). + +### GitLab Rails post-configuration + +1. Designate one application node for running database migrations during + installation and updates. Initialize the GitLab database and ensure all + migrations ran: + + ```shell + sudo gitlab-rake gitlab:db:configure + ``` + + If you encounter a `rake aborted!` error message stating that PgBouncer is + failing to connect to PostgreSQL, it may be that your PgBouncer node's IP + address is missing from PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` + on your database nodes. Before proceeding, see + [PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server). + +1. [Configure fast lookup of authorized SSH keys in the database](../operations/fast_ssh_key_lookup.md).
@@ -683,10 +702,10 @@ The Omnibus GitLab package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md): -1. SSH into the Monitoring node. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - Do not complete any other steps on the download page. +1. SSH in to the Monitoring node. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -806,30 +825,44 @@ data, and is recommended over [NFS](#configure-nfs-optional). In general, object storage services are better for larger environments, as object storage is typically much more performant, reliable, and scalable. -Object storage options that GitLab has either tested or is aware of customers -using, includes: - -- SaaS/Cloud solutions (such as [Amazon S3](https://aws.amazon.com/s3/) or - [Google Cloud Storage](https://cloud.google.com/storage)). -- On-premises hardware and appliances, from various storage vendors. -- MinIO ([Deployment guide](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html)). - -To configure GitLab to use object storage, refer to the following guides based -on the features you intend to use: - -1. [Object storage for backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage). -1. [Object storage for job artifacts](../job_artifacts.md#using-object-storage) - including [incremental logging](../job_logs.md#new-incremental-logging-architecture). -1. [Object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. [Object storage for uploads](../uploads.md#using-object-storage). -1. [Object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). -1. [Object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). -1. [Object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). -1. [Object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. [Object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. [Object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. [Object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional, for improved performance). -1. [Object storage for Terraform state files](../terraform_state.md#using-object-storage). +GitLab has been tested on a number of object storage providers: + +- [Amazon S3](https://aws.amazon.com/s3/) +- [Google Cloud Storage](https://cloud.google.com/storage) +- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces/) +- [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) +- [Openstack Swift](https://docs.openstack.org/swift/latest/s3_compat.html) +- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) +- On-premises hardware and appliances from various storage vendors. +- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. + +There are two ways of specifying object storage configuration in GitLab: + +- [Consolidated form](../object_storage.md#consolidated-object-storage-configuration): A single credential is + shared by all supported object types. +- [Storage-specific form](../object_storage.md#storage-specific-configuration): Every object defines its + own object storage [connection and configuration](../object_storage.md#connection-settings). + +Starting with GitLab 13.2, consolidated object storage configuration is available. It simplifies your GitLab configuration since the connection details are shared across object types. Refer to [Consolidated object storage configuration](../object_storage.md#consolidated-object-storage-configuration) guide for instructions on how to set it up. + +For configuring object storage in GitLab 13.1 and earlier, or for storage types not +supported by consolidated configuration form, refer to the following guides based +on what features you intend to use: + +|Object storage type|Supported by consolidated configuration?| +|-------------------|----------------------------------------| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | +| [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | +| [Uploads](../uploads.md#using-object-storage) | Yes | +| [Container Registry](../packages/container_registry.md#use-object-storage) (optional feature) | No | +| [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | +| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | +| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | +| [Terraform state files](../terraform_state.md#using-object-storage) | Yes | Using separate buckets for each data type is the recommended approach for GitLab. @@ -851,6 +884,22 @@ functioning backups is encountered.
+## Configure Advanced Search **(STARTER ONLY)** + +You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) +for faster, more advanced code search across your entire GitLab instance. + +Elasticsearch cluster design and requirements are dependent on your specific +data. For recommended best practices about how to set up your Elasticsearch +cluster alongside your instance, read how to +[choose the optimal cluster configuration](../../integration/elasticsearch.md#guidance-on-choosing-optimal-cluster-configuration). + + + ## Configure NFS (optional) For improved performance, [object storage](#configure-the-object-storage), diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index be944586e43..70d0cae6dfd 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -24,18 +24,18 @@ costly-to-operate environment by using the | Service | Nodes | Configuration | GCP | AWS | Azure | |--------------------------------------------|-------------|-----------------------|----------------|-------------|---------| -| External load balancing node | 1 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Redis | 3 | 2 vCPU, 7.5GB memory | n1-standard-2 | m5.large | D2s v3 | -| Consul + Sentinel | 3 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 3 | 2 vCPU, 7.5GB memory | n1-standard-2 | m5.large | D2s v3 | -| PgBouncer | 3 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Internal load balancing node | 1 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Gitaly | 2 (minimum) | 4 vCPU, 15GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Sidekiq | 4 | 2 vCPU, 7.5GB memory | n1-standard-2 | m5.large | D2s v3 | -| GitLab Rails | 3 | 8 vCPU, 7.2GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | -| Monitoring node | 1 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Object Storage | n/a | n/a | n/a | n/a | n/a | -| NFS Server (optional, not recommended) | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| External load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Redis | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | +| Consul + Sentinel | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| PostgreSQL | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | +| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Gitaly | 2 (minimum) | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | +| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | +| GitLab Rails | 3 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Object storage | n/a | n/a | n/a | n/a | n/a | +| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) @@ -44,41 +44,43 @@ or higher, are required for your CPU or node counts. For more information, see our [Sysbench](https://github.com/akopytov/sysbench)-based [CPU benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks). -For data objects (such as LFS, Uploads, or Artifacts), an -[object storage service](#configure-the-object-storage) is recommended instead -of NFS where possible, due to better performance and availability. Since this -doesn't require a node to be set up, *Object Storage* is noted as not -applicable (n/a) in the previous table. +Due to better performance and availability, for data objects (such as LFS, +uploads, or artifacts), using an [object storage service](#configure-the-object-storage) +is recommended instead of using NFS. Using an object storage service also +doesn't require you to provision and maintain a node. ## Setup components To set up GitLab and its components to accommodate up to 3,000 users: 1. [Configure the external load balancing node](#configure-the-external-load-balancer) - that will handle the load balancing of the two GitLab application services nodes. + to handle the load balancing of the GitLab application services nodes. 1. [Configure Redis](#configure-redis). 1. [Configure Consul and Sentinel](#configure-consul-and-sentinel). 1. [Configure PostgreSQL](#configure-postgresql), the database for GitLab. 1. [Configure PgBouncer](#configure-pgbouncer). -1. [Configure the internal load balancing node](#configure-the-internal-load-balancer) +1. [Configure the internal load balancing node](#configure-the-internal-load-balancer). 1. [Configure Gitaly](#configure-gitaly), which provides access to the Git repositories. 1. [Configure Sidekiq](#configure-sidekiq). 1. [Configure the main GitLab Rails application](#configure-gitlab-rails) - to run Puma/Unicorn, Workhorse, GitLab Shell, and to serve all frontend requests (UI, API, Git - over HTTP/SSH). -1. [Configure Prometheus](#configure-prometheus) to monitor your GitLab environment. -1. [Configure the Object Storage](#configure-the-object-storage) + to run Puma/Unicorn, Workhorse, GitLab Shell, and to serve all frontend + requests (which include UI, API, and Git over HTTP/SSH). +1. [Configure Prometheus](#configure-prometheus) to monitor your GitLab + environment. +1. [Configure the object storage](#configure-the-object-storage) used for shared data objects. -1. [Configure NFS (Optional)](#configure-nfs-optional) - to have shared disk storage service as an alternative to Gitaly and/or Object Storage (although - not recommended). NFS is required for GitLab Pages, you can skip this step if you're not using - that feature. +1. [Configure Advanced Search](#configure-advanced-search) (optional) for faster, + more advanced code search across your entire GitLab instance. +1. [Configure NFS](#configure-nfs-optional) (optional, and not recommended) + to have shared disk storage service as an alternative to Gitaly or object + storage. You can skip this step if you're not using GitLab Pages (which + requires NFS). -We start with all servers on the same 10.6.0.0/16 private network range, they -can connect to each other freely on those addresses. +The servers start on the same 10.6.0.0/24 private network range, and can +connect to each other freely on these addresses. -Here is a list and description of each machine and the assigned IP: +The following list includes descriptions of each server and its assigned IP: - `10.6.0.10`: External Load Balancer - `10.6.0.61`: Redis Primary @@ -107,19 +109,18 @@ Here is a list and description of each machine and the assigned IP: ## Configure the external load balancer -NOTE: **Note:** +In an active/active GitLab configuration, you'll need a load balancer to route +traffic to the application servers. The specifics on which load balancer to use +or its exact configuration is beyond the scope of GitLab documentation. We hope +that if you're managing multi-node systems like GitLab, you already have a load +balancer of choice. Some load balancer examples include HAProxy (open-source), +F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and +protocols needed for use with GitLab. + This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) as the load balancer. Although other load balancers with similar feature sets could also be used, those load balancers have not been validated. -In an active/active GitLab configuration, you will need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or the exact configuration is beyond the scope of GitLab documentation. We hope -that if you're managing multi-node systems like GitLab you have a load balancer of -choice already. Some examples including HAProxy (open-source), F5 Big-IP LTM, -and Citrix Net Scaler. This documentation will outline what ports and protocols -you need to use with GitLab. - The next question is how you will handle SSL in your environment. There are several different options: @@ -277,20 +278,17 @@ The requirements for a Redis setup are the following: ([Internet](https://gitlab.com/gitlab-org/gitlab-foss/uploads/c4cc8cd353604bd80315f9384035ff9e/The_Internet_IT_Crowd.png)), using a firewall. -NOTE: **Note:** -Redis nodes (both primary and replica) will need the same password defined in -`redis['password']`. At any time during a failover the Sentinels can -reconfigure a node and change its status from primary to replica and vice versa. +Both the primary and replica Redis nodes need the same password defined in +`redis['password']`. At any time during a failover, the Sentinels can reconfigure +a node and change its status from primary to replica (and vice versa). #### Configuring the primary Redis instance -1. SSH into the **Primary** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **Primary** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -334,18 +332,17 @@ reconfigure a node and change its status from primary to replica and vice versa. 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). -You can list the current Redis Primary, Replica status via: +You can list the current Redis Primary, Replica status by using: ```shell /opt/gitlab/embedded/bin/redis-cli -h -a 'redis-password-goes-here' info replication ``` -Show running GitLab services via: +Show running GitLab services by using: ```shell gitlab-ctl status @@ -363,13 +360,11 @@ run: redis-exporter: (pid 30075) 76861s; run: log: (pid 29674) 76896s #### Configuring the replica Redis instances -1. SSH into the **replica** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **replica** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -422,10 +417,9 @@ run: redis-exporter: (pid 30075) 76861s; run: log: (pid 29674) 76896s 1. Go through the steps again for all the other replica nodes, and make sure to set up the IPs correctly. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). These values don't have to be changed again in `/etc/gitlab/gitlab.rb` after a failover, as the nodes will be managed by the [Sentinels](#configure-consul-and-sentinel), and even after a @@ -443,13 +437,6 @@ are supported and can be added if needed. ## Configure Consul and Sentinel -NOTE: **Note:** -If you are using an external Redis Sentinel instance, be sure -to exclude the `requirepass` parameter from the Sentinel -configuration. This parameter will cause clients to report `NOAUTH -Authentication required.`. [Redis Sentinel 3.2.x does not support -password authentication](https://github.com/antirez/redis/issues/3279). - Now that the Redis servers are all set up, let's configure the Sentinel servers. The following IPs will be used as an example: @@ -457,16 +444,19 @@ servers. The following IPs will be used as an example: - `10.6.0.12`: Consul/Sentinel 2 - `10.6.0.13`: Consul/Sentinel 3 -To configure the Sentinel: +NOTE: **Note:** +If you're using an external Redis Sentinel instance, be sure to exclude the +`requirepass` parameter from the Sentinel configuration. This parameter causes +clients to report `NOAUTH Authentication required.`. +[Redis Sentinel 3.2.x doesn't support password authentication](https://github.com/antirez/redis/issues/3279). -1. SSH into the server that will host Consul/Sentinel. -1. [Download/install](https://about.gitlab.com/install/) the - Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the - GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. +To configure the Sentinel: +1. SSH in to the server that will host Consul/Sentinel. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -556,10 +546,9 @@ To configure the Sentinel: 1. Go through the steps again for all the other Consul/Sentinel nodes, and make sure you set up the correct IPs. -NOTE: **Note:** -A Consul leader will be elected when the provisioning of the third Consul server is completed. -Viewing the Consul logs `sudo gitlab-ctl tail consul` will display -`...[INFO] consul: New leader elected: ...` +A Consul leader is _elected_ when the provisioning of the third Consul server is +complete. Viewing the Consul logs `sudo gitlab-ctl tail consul` displays +`...[INFO] consul: New leader elected: ...`. You can list the current Consul members (server, client): @@ -627,7 +616,7 @@ in the second step, do not supply the `EXTERNAL_URL` value. #### PostgreSQL primary node -1. SSH into the PostgreSQL primary node. +1. SSH in to the PostgreSQL primary node. 1. Generate a password hash for the PostgreSQL username/password pair. This assumes you will use the default username of `gitlab` (recommended). The command will request a password and confirmation. Use the value that is output by this command in the next @@ -812,7 +801,7 @@ are supported and can be added if needed. #### PostgreSQL post-configuration -SSH into the **primary node**: +SSH in to the **primary node**: 1. Open a database prompt: @@ -848,7 +837,7 @@ SSH into the **primary node**: is not an IP address, it will need to be a resolvable name (via DNS or `/etc/hosts`) -SSH into the **secondary node**: +SSH in to the **secondary node**: 1. Set up the repmgr standby: @@ -1069,51 +1058,48 @@ Refer to your preferred Load Balancer's documentation for further guidance. ## Configure Gitaly -Deploying Gitaly in its own server can benefit GitLab installations that are -larger than a single machine. - -The Gitaly node requirements are dependent on customer data, specifically the number of -projects and their repository sizes. Two nodes are recommended as an absolute minimum. -Each Gitaly node should store no more than 5TB of data and have the number of -[`gitaly-ruby` workers](../gitaly/index.md#gitaly-ruby) set to 20% of available CPUs. -Additional nodes should be considered in conjunction with a review of expected -data size and spread based on the recommendations above. - -It is also strongly recommended that all Gitaly nodes be set up with SSD disks with -a throughput of at least 8,000 IOPS for read operations and 2,000 IOPS for write, -as Gitaly has heavy I/O. These IOPS values are recommended only as a starter as with -time they may be adjusted higher or lower depending on the scale of your environment's workload. -If you're running the environment on a Cloud provider, you may need to refer to -their documentation on how to configure IOPS correctly. - -Some things to note: - -- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md). -- A Gitaly server can host one or more storages. -- A GitLab server can use one or more Gitaly servers. -- Gitaly addresses must be specified in such a way that they resolve - correctly for ALL Gitaly clients. +[Gitaly](../gitaly/index.md) server node requirements are dependent on data, +specifically the number of projects and those projects' sizes. It's recommended +that a Gitaly server node stores no more than 5 TB of data. Although this +reference architecture includes a recommendation for the number of Gitaly server +nodes to use, depending on your storage requirements, you may require additional +Gitaly server nodes. + +Due to Gitaly having notable input and output requirements, we strongly +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should +have a throughput of at least 8,000 input/output operations per second (IOPS) +for read operations and 2,000 IOPS for write operations. These IOPS values are +initial recommendations, and may be adjusted to greater or lesser values +depending on the scale of your environment's workload. If you're running the +environment on a Cloud provider, refer to their documentation about how to +configure IOPS correctly. + +Be sure to note the following items: + +- The GitLab Rails application shards repositories into + [repository storage paths](../repository_storage_paths.md). +- A Gitaly server can host one or more storage paths. +- A GitLab server can use one or more Gitaly server nodes. +- Gitaly addresses must be specified to be correctly resolvable for _all_ + Gitaly clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -TIP: **Tip:** -For more information about Gitaly's history and network architecture see the -[standalone Gitaly documentation](../gitaly/index.md). - -Note: **Note:** The token referred to throughout the Gitaly documentation is -just an arbitrary password selected by the administrator. It is unrelated to -tokens created for the GitLab API or other similar web API tokens. +NOTE: **Note:** +The token referred to throughout the Gitaly documentation is an arbitrary +password selected by the administrator. This token is unrelated to tokens +created for the GitLab API or other similar web API tokens. -Below we describe how to configure two Gitaly servers, with IPs and -domain names: +This section describes how to configure two Gitaly servers, with the following +IPs and domain names: - `10.6.0.51`: Gitaly 1 (`gitaly1.internal`) - `10.6.0.52`: Gitaly 2 (`gitaly2.internal`) -The secret token is assumed to be `gitalysecret` and that -your GitLab installation has three repository storages: +Assumptions about your servers include having the secret token be `gitalysecret`, +and that your GitLab installation has three repository storages: - `default` on Gitaly 1 - `storage1` on Gitaly 1 @@ -1121,11 +1107,11 @@ your GitLab installation has three repository storages: On each node: -1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page but - **without** providing the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable - the network listener and configure the token: +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and _do not_ provide the `EXTERNAL_URL` value. +1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable + the network listener, and configure the token: -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Confirm that Gitaly can perform callbacks to the internal API: ```shell - sudo /opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml + sudo /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml ``` 1. Verify the GitLab services are running: @@ -1259,11 +1245,10 @@ Name. If you are addressing the Gitaly server by its IP address, you must add it as a Subject Alternative Name to the certificate. [gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). -NOTE: **Note:** -It is possible to configure Gitaly servers with both an -unencrypted listening address `listen_addr` and an encrypted listening -address `tls_listen_addr` at the same time. This allows you to do a -gradual transition from unencrypted to encrypted traffic, if necessary. +It's possible to configure Gitaly servers with both an unencrypted listening +address (`listen_addr`) and an encrypted listening address (`tls_listen_addr`) +at the same time. This allows you to do a gradual transition from unencrypted to +encrypted traffic, if necessary. To configure Gitaly with TLS: @@ -1317,10 +1302,10 @@ The following IPs will be used as an example: To configure the Sidekiq nodes, one each one: -1. SSH into the Sidekiq server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab package -you want using steps 1 and 2 from the GitLab downloads page. -**Do not complete any other steps on the download page.** +1. SSH in to the Sidekiq server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Open `/etc/gitlab/gitlab.rb` with your editor: ```ruby @@ -1431,14 +1416,14 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails -NOTE: **Note:** -In our architectures we run each GitLab Rails node using the Puma webserver -and have its number of workers set to 90% of available CPUs along with four threads. For -nodes that are running Rails with other components the worker value should be reduced -accordingly where we've found 50% achieves a good balance but this is dependent -on workload. - This section describes how to configure the GitLab application (Rails) component. + +In our architecture, we run each GitLab Rails node using the Puma webserver, and +have its number of workers set to 90% of available CPUs, with four threads. For +nodes running Rails with other components, the worker value should be reduced +accordingly. We've determined that a worker value of 50% achieves a good balance, +but this is dependent on workload. + On each node perform the following: 1. If you're [using NFS](#configure-nfs-optional): @@ -1466,10 +1451,10 @@ On each node perform the following: mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data ``` -1. Download/install Omnibus GitLab using **steps 1 and 2** from - [GitLab downloads](https://about.gitlab.com/install/). Do not complete other - steps on the download page. -1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. +1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration. To maintain uniformity of links across nodes, the `external_url` on the application server should point to the external URL that users will use to access GitLab. This would be the URL of the [external load balancer](#configure-the-external-load-balancer) @@ -1582,6 +1567,11 @@ On each node perform the following: sudo gitlab-ctl tail gitaly ``` +1. Save the `/etc/gitlab/gitlab-secrets.json` file from one of the two + application nodes and install it on the other application node, the + [Gitaly node](#configure-gitaly) and the [Sidekiq node](#configure-sidekiq) and + [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + 1. Verify the GitLab services are running: ```shell @@ -1600,12 +1590,10 @@ On each node perform the following: run: puma: (pid 4936) 8645s; run: log: (pid 29656) 79161s ``` -NOTE: **Note:** -When you specify `https` in the `external_url`, as in the example -above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If -certificates are not present, NGINX will fail to start. See the -[NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) -for more information. +When you specify `https` in the `external_url`, as in the previous example, +GitLab expects that the SSL certificates are in `/etc/gitlab/ssl/`. If the +certificates aren't present, NGINX will fail to start. For more information, see +the [NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https). ### GitLab Rails post-configuration @@ -1615,12 +1603,11 @@ for more information. gitlab-rake gitlab:db:configure ``` - NOTE: **Note:** - If you encounter a `rake aborted!` error stating that PgBouncer is failing to connect to - PostgreSQL it may be that your PgBouncer node's IP address is missing from - PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` on your database nodes. See - [PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server) - in the Troubleshooting section before proceeding. + If you encounter a `rake aborted!` error message stating that PgBouncer is + failing to connect to PostgreSQL, it may be that your PgBouncer node's IP + address is missing from PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` + on your database nodes. Before proceeding, see + [PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server). 1. [Configure fast lookup of authorized SSH keys in the database](../operations/fast_ssh_key_lookup.md). @@ -1636,10 +1623,10 @@ The Omnibus GitLab package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md): -1. SSH into the Monitoring node. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - Do not complete any other steps on the download page. +1. SSH in to the Monitoring node. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1714,28 +1701,44 @@ It's recommended over [NFS](#configure-nfs-optional) and in general it's better in larger setups as object storage is typically much more performant, reliable, and scalable. -Object storage options that GitLab has tested, or is aware of customers using include: +GitLab has been tested on a number of object storage providers: -- SaaS/Cloud solutions such as [Amazon S3](https://aws.amazon.com/s3/), [Google cloud storage](https://cloud.google.com/storage). +- [Amazon S3](https://aws.amazon.com/s3/) +- [Google Cloud Storage](https://cloud.google.com/storage) +- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces/) +- [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) +- [Openstack Swift](https://docs.openstack.org/swift/latest/s3_compat.html) +- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - On-premises hardware and appliances from various storage vendors. -- MinIO. There is [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. - -For configuring GitLab to use Object Storage refer to the following guides -based on what features you intend to use: - -1. Configure [object storage for backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage). -1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) - including [incremental logging](../job_logs.md#new-incremental-logging-architecture). -1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage). -1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). -1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). -1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). -1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). +- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. + +There are two ways of specifying object storage configuration in GitLab: + +- [Consolidated form](../object_storage.md#consolidated-object-storage-configuration): A single credential is + shared by all supported object types. +- [Storage-specific form](../object_storage.md#storage-specific-configuration): Every object defines its + own object storage [connection and configuration](../object_storage.md#connection-settings). + +Starting with GitLab 13.2, consolidated object storage configuration is available. It simplifies your GitLab configuration since the connection details are shared across object types. Refer to [Consolidated object storage configuration](../object_storage.md#consolidated-object-storage-configuration) guide for instructions on how to set it up. + +For configuring object storage in GitLab 13.1 and earlier, or for storage types not +supported by consolidated configuration form, refer to the following guides based +on what features you intend to use: + +|Object storage type|Supported by consolidated configuration?| +|-------------------|----------------------------------------| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | +| [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | +| [Uploads](../uploads.md#using-object-storage) | Yes | +| [Container Registry](../packages/container_registry.md#use-object-storage) (optional feature) | No | +| [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | +| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | +| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | +| [Terraform state files](../terraform_state.md#using-object-storage) | Yes | Using separate buckets for each data type is the recommended approach for GitLab. @@ -1759,6 +1762,22 @@ work.
+## Configure Advanced Search **(STARTER ONLY)** + +You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) +for faster, more advanced code search across your entire GitLab instance. + +Elasticsearch cluster design and requirements are dependent on your specific +data. For recommended best practices about how to set up your Elasticsearch +cluster alongside your instance, read how to +[choose the optimal cluster configuration](../../integration/elasticsearch.md#guidance-on-choosing-optimal-cluster-configuration). + +
+ + Back to setup components + +
+ ## Configure NFS (optional) [Object storage](#configure-the-object-storage), along with [Gitaly](#configure-gitaly) diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index e812eed0227..44fbe2db504 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -17,21 +17,21 @@ full list of reference architectures, see | Service | Nodes | Configuration | GCP | AWS | Azure | |-----------------------------------------|-------------|-------------------------|-----------------|--------------|----------| -| External load balancing node | 1 | 8 vCPU, 7.2GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | -| Consul | 3 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 3 | 16 vCPU, 60GB memory | n1-standard-16 | m5.4xlarge | D16s v3 | -| PgBouncer | 3 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Internal load balancing node | 1 | 8 vCPU, 7.2GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | -| Redis - Cache | 3 | 4 vCPU, 15GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis - Queues / Shared State | 3 | 4 vCPU, 15GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7GB memory | g1-small | t2.small | B1MS | -| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7GB memory | g1-small | t2.small | B1MS | -| Gitaly | 2 (minimum) | 64 vCPU, 240GB memory | n1-standard-64 | m5.16xlarge | D64s v3 | -| Sidekiq | 4 | 4 vCPU, 15GB memory | n1-standard-4 | m5.xlarge | D4s v3 | -| GitLab Rails | 12 | 32 vCPU, 28.8GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | -| Monitoring node | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | -| Object Storage | n/a | n/a | n/a | n/a | n/a | -| NFS Server | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| External load balancing node | 1 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | +| Consul | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| PostgreSQL | 3 | 16 vCPU, 60 GB memory | n1-standard-16 | m5.4xlarge | D16s v3 | +| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Internal load balancing node | 1 | 8 vCPU, 7.2 GB memory | n1-highcpu-8 | c5.2xlarge | F8s v2 | +| Redis - Cache | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | +| Redis - Queues / Shared State | 3 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | +| Redis Sentinel - Cache | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Redis Sentinel - Queues / Shared State | 3 | 1 vCPU, 1.7 GB memory | g1-small | t2.small | B1MS | +| Gitaly | 2 (minimum) | 64 vCPU, 240 GB memory | n1-standard-64 | m5.16xlarge | D64s v3 | +| Sidekiq | 4 | 4 vCPU, 15 GB memory | n1-standard-4 | m5.xlarge | D4s v3 | +| GitLab Rails | 12 | 32 vCPU, 28.8 GB memory | n1-highcpu-32 | c5.9xlarge | F32s v2 | +| Monitoring node | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| Object storage | n/a | n/a | n/a | n/a | n/a | +| NFS server | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) @@ -40,41 +40,43 @@ or higher, are required for your CPU or node counts. For more information, see our [Sysbench](https://github.com/akopytov/sysbench)-based [CPU benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks). -For data objects (such as LFS, Uploads, or Artifacts), an -[object storage service](#configure-the-object-storage) is recommended instead -of NFS where possible, due to better performance and availability. Since this -doesn't require a node to be set up, *Object Storage* is noted as not -applicable (n/a) in the previous table. +Due to better performance and availability, for data objects (such as LFS, +uploads, or artifacts), using an [object storage service](#configure-the-object-storage) +is recommended instead of using NFS. Using an object storage service also +doesn't require you to provision and maintain a node. ## Setup components To set up GitLab and its components to accommodate up to 50,000 users: 1. [Configure the external load balancing node](#configure-the-external-load-balancer) - that will handle the load balancing of the three GitLab application services nodes. + to handle the load balancing of the GitLab application services nodes. 1. [Configure Consul](#configure-consul). 1. [Configure PostgreSQL](#configure-postgresql), the database for GitLab. 1. [Configure PgBouncer](#configure-pgbouncer). -1. [Configure the internal load balancing node](#configure-the-internal-load-balancer) +1. [Configure the internal load balancing node](#configure-the-internal-load-balancer). 1. [Configure Redis](#configure-redis). 1. [Configure Gitaly](#configure-gitaly), which provides access to the Git repositories. 1. [Configure Sidekiq](#configure-sidekiq). 1. [Configure the main GitLab Rails application](#configure-gitlab-rails) - to run Puma/Unicorn, Workhorse, GitLab Shell, and to serve all frontend requests (UI, API, Git - over HTTP/SSH). -1. [Configure Prometheus](#configure-prometheus) to monitor your GitLab environment. -1. [Configure the Object Storage](#configure-the-object-storage) + to run Puma/Unicorn, Workhorse, GitLab Shell, and to serve all frontend + requests (which include UI, API, and Git over HTTP/SSH). +1. [Configure Prometheus](#configure-prometheus) to monitor your GitLab + environment. +1. [Configure the object storage](#configure-the-object-storage) used for shared data objects. -1. [Configure NFS (Optional)](#configure-nfs-optional) - to have shared disk storage service as an alternative to Gitaly and/or Object Storage (although - not recommended). NFS is required for GitLab Pages, you can skip this step if you're not using - that feature. +1. [Configure Advanced Search](#configure-advanced-search) (optional) for faster, + more advanced code search across your entire GitLab instance. +1. [Configure NFS](#configure-nfs-optional) (optional, and not recommended) + to have shared disk storage service as an alternative to Gitaly or object + storage. You can skip this step if you're not using GitLab Pages (which + requires NFS). -We start with all servers on the same 10.6.0.0/24 private network range, they -can connect to each other freely on those addresses. +The servers start on the same 10.6.0.0/24 private network range, and can +connect to each other freely on these addresses. -Here is a list and description of each machine and the assigned IP: +The following list includes descriptions of each server and its assigned IP: - `10.6.0.10`: External Load Balancer - `10.6.0.11`: Consul 1 @@ -112,19 +114,18 @@ Here is a list and description of each machine and the assigned IP: ## Configure the external load balancer -NOTE: **Note:** +In an active/active GitLab configuration, you'll need a load balancer to route +traffic to the application servers. The specifics on which load balancer to use +or its exact configuration is beyond the scope of GitLab documentation. We hope +that if you're managing multi-node systems like GitLab, you already have a load +balancer of choice. Some load balancer examples include HAProxy (open-source), +F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and +protocols needed for use with GitLab. + This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) as the load balancer. Although other load balancers with similar feature sets could also be used, those load balancers have not been validated. -In an active/active GitLab configuration, you will need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or the exact configuration is beyond the scope of GitLab documentation. We hope -that if you're managing multi-node systems like GitLab you have a load balancer of -choice already. Some examples including HAProxy (open-source), F5 Big-IP LTM, -and Citrix Net Scaler. This documentation will outline what ports and protocols -you need to use with GitLab. - The next question is how you will handle SSL in your environment. There are several different options: @@ -247,14 +248,11 @@ with the other servers. To configure Consul: -1. SSH into the server that will host Consul. -1. [Download/install](https://about.gitlab.com/install/) the - Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the - GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. - +1. SSH in to the server that will host Consul. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -282,10 +280,9 @@ To configure Consul: 1. Go through the steps again for all the other Consul nodes, and make sure you set up the correct IPs. -NOTE: **Note:** -A Consul leader will be elected when the provisioning of the third Consul server is completed. -Viewing the Consul logs `sudo gitlab-ctl tail consul` will display -`...[INFO] consul: New leader elected: ...` +A Consul leader is _elected_ when the provisioning of the third Consul server is +complete. Viewing the Consul logs `sudo gitlab-ctl tail consul` displays +`...[INFO] consul: New leader elected: ...`. You can list the current Consul members (server, client): @@ -352,7 +349,7 @@ in the second step, do not supply the `EXTERNAL_URL` value. #### PostgreSQL primary node -1. SSH into the PostgreSQL primary node. +1. SSH in to the PostgreSQL primary node. 1. Generate a password hash for the PostgreSQL username/password pair. This assumes you will use the default username of `gitlab` (recommended). The command will request a password and confirmation. Use the value that is output by this command in the next @@ -513,7 +510,7 @@ are supported and can be added if needed. #### PostgreSQL post-configuration -SSH into the **primary node**: +SSH in to the **primary node**: 1. Open a database prompt: @@ -548,7 +545,7 @@ SSH into the **primary node**: is not an IP address, it will need to be a resolvable name (via DNS or `/etc/hosts`) -SSH into the **secondary node**: +SSH in to the **secondary node**: 1. Set up the repmgr standby: @@ -662,7 +659,6 @@ The following IPs will be used as an example: 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. - NOTE: **Note:** If an error `execute[generate databases.ini]` occurs, this is due to an existing [known issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4713). It will be resolved when you run a second `reconfigure` after the next step. @@ -796,35 +792,31 @@ to be used with GitLab. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -NOTE: **Providing your own Redis instance:** -Managed Redis from cloud providers such as AWS ElastiCache will work. If these -services support high availability, be sure it is **not** the Redis Cluster type. -Redis version 5.0 or higher is required, as this is what ships with -Omnibus GitLab packages starting with GitLab 13.0. Older Redis versions -do not support an optional count argument to SPOP which is now required for -[Merge Trains](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). +### Providing your own Redis instance + +Managed Redis from cloud providers (such as AWS ElastiCache) will work. If these +services support high availability, be sure it _isn't_ of the Redis Cluster type. +Redis version 5.0 or higher is required, which is included with Omnibus GitLab +packages starting with GitLab 13.0. Older Redis versions don't support an +optional count argument to SPOP, which is required for [Merge Trains](../../ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). Note the Redis node's IP address or hostname, port, and password (if required). -These will be necessary when configuring the -[GitLab application servers](#configure-gitlab-rails) later. +These will be necessary later when configuring the [GitLab application servers](#configure-gitlab-rails). ### Configure the Redis and Sentinel Cache cluster This is the section where we install and set up the new Redis Cache instances. -NOTE: **Note:** -Redis nodes (both primary and replica) will need the same password defined in -`redis['password']`. At any time during a failover the Sentinels can -reconfigure a node and change its status from primary to replica and vice versa. +Both the primary and replica Redis nodes need the same password defined in +`redis['password']`. At any time during a failover, the Sentinels can reconfigure +a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Cache node -1. SSH into the **Primary** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **Primary** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -868,20 +860,17 @@ reconfigure a node and change its status from primary to replica and vice versa. 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). #### Configure the replica Redis Cache nodes -1. SSH into the **replica** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **replica** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -934,10 +923,9 @@ Read more about [roles](https://docs.gitlab.com/omnibus/roles/). 1. Go through the steps again for all the other replica nodes, and make sure to set up the IPs correctly. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). These values don't have to be changed again in `/etc/gitlab/gitlab.rb` after a failover, as the nodes will be managed by the [Sentinels](#configure-the-sentinel-cache-nodes), and even after a @@ -955,13 +943,6 @@ are supported and can be added if needed. #### Configure the Sentinel Cache nodes -NOTE: **Note:** -If you are using an external Redis Sentinel instance, be sure -to exclude the `requirepass` parameter from the Sentinel -configuration. This parameter will cause clients to report `NOAUTH -Authentication required.`. [Redis Sentinel 3.2.x does not support -password authentication](https://github.com/antirez/redis/issues/3279). - Now that the Redis servers are all set up, let's configure the Sentinel servers. The following IPs will be used as an example: @@ -969,16 +950,19 @@ servers. The following IPs will be used as an example: - `10.6.0.72`: Sentinel - Cache 2 - `10.6.0.73`: Sentinel - Cache 3 -To configure the Sentinel Cache server: +NOTE: **Note:** +If you're using an external Redis Sentinel instance, be sure to exclude the +`requirepass` parameter from the Sentinel configuration. This parameter causes +clients to report `NOAUTH Authentication required.`. +[Redis Sentinel 3.2.x doesn't support password authentication](https://github.com/antirez/redis/issues/3279). -1. SSH into the server that will host Consul/Sentinel. -1. [Download/install](https://about.gitlab.com/install/) the - Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the - GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. +To configure the Sentinel Cache server: +1. SSH in to the server that will host Consul/Sentinel. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1081,20 +1065,17 @@ To configure the Sentinel Cache server: This is the section where we install and set up the new Redis Queues instances. -NOTE: **Note:** -Redis nodes (both primary and replica) will need the same password defined in -`redis['password']`. At any time during a failover the Sentinels can -reconfigure a node and change its status from primary to replica and vice versa. +Both the primary and replica Redis nodes need the same password defined in +`redis['password']`. At any time during a failover, the Sentinels can reconfigure +a node and change its status from primary to replica (and vice versa). #### Configure the primary Redis Queues node -1. SSH into the **Primary** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **Primary** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1143,20 +1124,17 @@ reconfigure a node and change its status from primary to replica and vice versa. 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). #### Configure the replica Redis Queues nodes -1. SSH into the **replica** Redis Queue server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **replica** Redis Queue server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1209,10 +1187,9 @@ Read more about [roles](https://docs.gitlab.com/omnibus/roles/). 1. Go through the steps again for all the other replica nodes, and make sure to set up the IPs correctly. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). These values don't have to be changed again in `/etc/gitlab/gitlab.rb` after a failover, as the nodes will be managed by the [Sentinels](#configure-the-sentinel-queues-nodes), and even after a @@ -1230,13 +1207,6 @@ are supported and can be added if needed. #### Configure the Sentinel Queues nodes -NOTE: **Note:** -If you are using an external Redis Sentinel instance, be sure -to exclude the `requirepass` parameter from the Sentinel -configuration. This parameter will cause clients to report `NOAUTH -Authentication required.`. [Redis Sentinel 3.2.x does not support -password authentication](https://github.com/antirez/redis/issues/3279). - Now that the Redis servers are all set up, let's configure the Sentinel servers. The following IPs will be used as an example: @@ -1244,16 +1214,19 @@ servers. The following IPs will be used as an example: - `10.6.0.82`: Sentinel - Queues 2 - `10.6.0.83`: Sentinel - Queues 3 -To configure the Sentinel Queues server: +NOTE: **Note:** +If you're using an external Redis Sentinel instance, be sure to exclude the +`requirepass` parameter from the Sentinel configuration. This parameter causes +clients to report `NOAUTH Authentication required.`. +[Redis Sentinel 3.2.x doesn't support password authentication](https://github.com/antirez/redis/issues/3279). -1. SSH into the server that will host Sentinel. -1. [Download/install](https://about.gitlab.com/install/) the - Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the - GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. +To configure the Sentinel Queues server: +1. SSH in to the server that will host Sentinel. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1362,52 +1335,48 @@ To configure the Sentinel Queues server: ## Configure Gitaly -Deploying Gitaly in its own server can benefit GitLab installations that are -larger than a single machine. - -The Gitaly node requirements are dependent on customer data, specifically the number of -projects and their repository sizes. Two nodes are recommended as an absolute minimum. -Each Gitaly node should store no more than 5TB of data and have the number of -[`gitaly-ruby` workers](../gitaly/index.md#gitaly-ruby) set to 20% of available CPUs. -Additional nodes should be considered in conjunction with a review of expected -data size and spread based on the recommendations above. - -It is also strongly recommended that all Gitaly nodes be set up with SSD disks with -a throughput of at least 8,000 IOPS for read operations and 2,000 IOPS for write, -as Gitaly has heavy I/O. These IOPS values are recommended only as a starter as with -time they may be adjusted higher or lower depending on the scale of your environment's workload. -If you're running the environment on a Cloud provider, you may need to refer to -their documentation on how to configure IOPS correctly. - -Some things to note: - -- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md). -- A Gitaly server can host one or more storages. -- A GitLab server can use one or more Gitaly servers. -- Gitaly addresses must be specified in such a way that they resolve - correctly for ALL Gitaly clients. +[Gitaly](../gitaly/index.md) server node requirements are dependent on data, +specifically the number of projects and those projects' sizes. It's recommended +that a Gitaly server node stores no more than 5 TB of data. Although this +reference architecture includes a recommendation for the number of Gitaly server +nodes to use, depending on your storage requirements, you may require additional +Gitaly server nodes. + +Due to Gitaly having notable input and output requirements, we strongly +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should +have a throughput of at least 8,000 input/output operations per second (IOPS) +for read operations and 2,000 IOPS for write operations. These IOPS values are +initial recommendations, and may be adjusted to greater or lesser values +depending on the scale of your environment's workload. If you're running the +environment on a Cloud provider, refer to their documentation about how to +configure IOPS correctly. + +Be sure to note the following items: + +- The GitLab Rails application shards repositories into + [repository storage paths](../repository_storage_paths.md). +- A Gitaly server can host one or more storage paths. +- A GitLab server can use one or more Gitaly server nodes. +- Gitaly addresses must be specified to be correctly resolvable for _all_ + Gitaly clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -TIP: **Tip:** -For more information about Gitaly's history and network architecture see the -[standalone Gitaly documentation](../gitaly/index.md). - -Note: **Note:** -The token referred to throughout the Gitaly documentation is -just an arbitrary password selected by the administrator. It is unrelated to -tokens created for the GitLab API or other similar web API tokens. +NOTE: **Note:** +The token referred to throughout the Gitaly documentation is an arbitrary +password selected by the administrator. This token is unrelated to tokens +created for the GitLab API or other similar web API tokens. -Below we describe how to configure two Gitaly servers, with IPs and -domain names: +This section describes how to configure two Gitaly servers, with the following +IPs and domain names: - `10.6.0.91`: Gitaly 1 (`gitaly1.internal`) - `10.6.0.92`: Gitaly 2 (`gitaly2.internal`) -The secret token is assumed to be `gitalysecret` and that -your GitLab installation has three repository storages: +Assumptions about your servers include having the secret token be `gitalysecret`, +and that your GitLab installation has three repository storages: - `default` on Gitaly 1 - `storage1` on Gitaly 1 @@ -1415,11 +1384,11 @@ your GitLab installation has three repository storages: On each node: -1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page but - **without** providing the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable - the network listener and configure the token: +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and _do not_ provide the `EXTERNAL_URL` value. +1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable + the network listener, and configure the token: -1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace - the file of the same name on this server. If that file is not on this server, - add the file from your Consul server to this server. +1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and + then replace the file of the same name on this server. If that file isn't on + this server, add the file from your Consul server to this server. -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). ### Gitaly TLS support @@ -1521,11 +1490,10 @@ Name. If you are addressing the Gitaly server by its IP address, you must add it as a Subject Alternative Name to the certificate. [gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). -NOTE: **Note:** -It is possible to configure Gitaly servers with both an -unencrypted listening address `listen_addr` and an encrypted listening -address `tls_listen_addr` at the same time. This allows you to do a -gradual transition from unencrypted to encrypted traffic, if necessary. +It's possible to configure Gitaly servers with both an unencrypted listening +address (`listen_addr`) and an encrypted listening address (`tls_listen_addr`) +at the same time. This allows you to do a gradual transition from unencrypted to +encrypted traffic, if necessary. To configure Gitaly with TLS: @@ -1580,10 +1548,10 @@ The following IPs will be used as an example: To configure the Sidekiq nodes, on each one: -1. SSH into the Sidekiq server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab package -you want using steps 1 and 2 from the GitLab downloads page. -**Do not complete any other steps on the download page.** +1. SSH in to the Sidekiq server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Open `/etc/gitlab/gitlab.rb` with your editor: ```ruby @@ -1701,15 +1669,14 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails -NOTE: **Note:** -In our architectures we run each GitLab Rails node using the Puma webserver -and have its number of workers set to 90% of available CPUs along with four threads. For -nodes that are running Rails with other components the worker value should be reduced -accordingly where we've found 50% achieves a good balance but this is dependent -on workload. - This section describes how to configure the GitLab application (Rails) component. +In our architecture, we run each GitLab Rails node using the Puma webserver, and +have its number of workers set to 90% of available CPUs, with four threads. For +nodes running Rails with other components, the worker value should be reduced +accordingly. We've determined that a worker value of 50% achieves a good balance, +but this is dependent on workload. + The following IPs will be used as an example: - `10.6.0.111`: GitLab application 1 @@ -1718,10 +1685,9 @@ The following IPs will be used as an example: On each node perform the following: -1. Download/install Omnibus GitLab using **steps 1 and 2** from - [GitLab downloads](https://about.gitlab.com/install/). Do not complete other - steps on the download page. - +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace the file of the same name on this server. If that file is not on this server, add the file from your Consul server to this server. @@ -1752,6 +1718,7 @@ On each node perform the following: roles ['application_role'] gitaly['enable'] = false nginx['enable'] = true + sidekiq['enable'] = false ## PostgreSQL connection details # Disable PostgreSQL on the application node @@ -1795,7 +1762,6 @@ On each node perform the following: # Set the network addresses that the exporters used for monitoring will listen on node_exporter['listen_address'] = '0.0.0.0:9100' gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229' - sidekiq['listen_address'] = "0.0.0.0" puma['listen'] = '0.0.0.0' # Add the monitoring node's IP address to the monitoring whitelist and allow it to @@ -1836,7 +1802,7 @@ On each node perform the following: 1. Specify the necessary NFS mounts in `/etc/fstab`. The exact contents of `/etc/fstab` will depend on how you chose - to configure your NFS server. See the [NFS documentation](../high_availability/nfs.md) + to configure your NFS server. See the [NFS documentation](../nfs.md) for examples and the various options. 1. Create the shared directories. These may be different depending on your NFS @@ -1877,30 +1843,31 @@ On each node perform the following: 1. Optionally, from the Gitaly servers, confirm that Gitaly can perform callbacks to the internal API: ```shell - sudo /opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml + sudo /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml ``` -NOTE: **Note:** -When you specify `https` in the `external_url`, as in the example -above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If -certificates are not present, NGINX will fail to start. See the -[NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) -for more information. +When you specify `https` in the `external_url`, as in the previous example, +GitLab expects that the SSL certificates are in `/etc/gitlab/ssl/`. If the +certificates aren't present, NGINX will fail to start. For more information, see +the [NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https). ### GitLab Rails post-configuration -Initialize the GitLab database, by running the following in one of the Rails nodes: +1. Designate one application node for running database migrations during + installation and updates. Initialize the GitLab database and ensure all + migrations ran: -```shell -sudo gitlab-rake gitlab:db:configure -``` + ```shell + sudo gitlab-rake gitlab:db:configure + ``` -NOTE: **Note:** -If you encounter a `rake aborted!` error stating that PgBouncer is failing to connect to -PostgreSQL it may be that your PgBouncer node's IP address is missing from -PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` on your database nodes. See -[PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server) -in the Troubleshooting section before proceeding. + If you encounter a `rake aborted!` error message stating that PgBouncer is + failing to connect to PostgreSQL, it may be that your PgBouncer node's IP + address is missing from PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` + on your database nodes. Before proceeding, see + [PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server). + +1. [Configure fast lookup of authorized SSH keys in the database](../operations/fast_ssh_key_lookup.md).
@@ -1920,11 +1887,10 @@ The following IP will be used as an example: To configure the Monitoring node: -1. SSH into the Monitoring node. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - Do not complete any other steps on the download page. - +1. SSH in to the Monitoring node. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Copy the `/etc/gitlab/gitlab-secrets.json` file from your Consul server, and replace the file of the same name on this server. If that file is not on this server, add the file from your Consul server to this server. @@ -1988,28 +1954,44 @@ It's recommended over [NFS](#configure-nfs-optional) and in general it's better in larger setups as object storage is typically much more performant, reliable, and scalable. -Object storage options that GitLab has tested, or is aware of customers using include: +GitLab has been tested on a number of object storage providers: -- SaaS/Cloud solutions such as [Amazon S3](https://aws.amazon.com/s3/), [Google cloud storage](https://cloud.google.com/storage). +- [Amazon S3](https://aws.amazon.com/s3/) +- [Google Cloud Storage](https://cloud.google.com/storage) +- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces/) +- [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) +- [Openstack Swift](https://docs.openstack.org/swift/latest/s3_compat.html) +- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - On-premises hardware and appliances from various storage vendors. -- MinIO. There is [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. - -For configuring GitLab to use Object Storage refer to the following guides -based on what features you intend to use: - -1. Configure [object storage for backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage). -1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) - including [incremental logging](../job_logs.md#new-incremental-logging-architecture). -1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage). -1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). -1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). -1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). -1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). +- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. + +There are two ways of specifying object storage configuration in GitLab: + +- [Consolidated form](../object_storage.md#consolidated-object-storage-configuration): A single credential is + shared by all supported object types. +- [Storage-specific form](../object_storage.md#storage-specific-configuration): Every object defines its + own object storage [connection and configuration](../object_storage.md#connection-settings). + +Starting with GitLab 13.2, consolidated object storage configuration is available. It simplifies your GitLab configuration since the connection details are shared across object types. Refer to [Consolidated object storage configuration](../object_storage.md#consolidated-object-storage-configuration) guide for instructions on how to set it up. + +For configuring object storage in GitLab 13.1 and earlier, or for storage types not +supported by consolidated configuration form, refer to the following guides based +on what features you intend to use: + +|Object storage type|Supported by consolidated configuration?| +|-------------------|----------------------------------------| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | +| [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | +| [Uploads](../uploads.md#using-object-storage) | Yes | +| [Container Registry](../packages/container_registry.md#use-object-storage) (optional feature) | No | +| [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | +| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | +| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | +| [Terraform state files](../terraform_state.md#using-object-storage) | Yes | Using separate buckets for each data type is the recommended approach for GitLab. @@ -2033,13 +2015,29 @@ work.
+## Configure Advanced Search **(STARTER ONLY)** + +You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) +for faster, more advanced code search across your entire GitLab instance. + +Elasticsearch cluster design and requirements are dependent on your specific +data. For recommended best practices about how to set up your Elasticsearch +cluster alongside your instance, read how to +[choose the optimal cluster configuration](../../integration/elasticsearch.md#guidance-on-choosing-optimal-cluster-configuration). + +
+ + Back to setup components + +
+ ## Configure NFS (optional) [Object storage](#configure-the-object-storage), along with [Gitaly](#configure-gitaly) are recommended over NFS wherever possible for improved performance. If you intend to use GitLab Pages, this currently [requires NFS](troubleshooting.md#gitlab-pages-requires-nfs). -See how to [configure NFS](../high_availability/nfs.md). +See how to [configure NFS](../nfs.md).
diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 6dfa588b092..9f83950a927 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -24,18 +24,18 @@ costly-to-operate environment by using the | Service | Nodes | Configuration | GCP | AWS | Azure | |--------------------------------------------|-------------|-------------------------|----------------|-------------|----------| -| External load balancing node | 1 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Redis | 3 | 2 vCPU, 7.5GB memory | n1-standard-2 | m5.large | D2s v3 | -| Consul + Sentinel | 3 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| PostgreSQL | 3 | 2 vCPU, 7.5GB memory | n1-standard-2 | m5.large | D2s v3 | -| PgBouncer | 3 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Internal load balancing node | 1 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Gitaly | 2 (minimum) | 8 vCPU, 30GB memory | n1-standard-8 | m5.2xlarge | D8s v3 | -| Sidekiq | 4 | 2 vCPU, 7.5GB memory | n1-standard-2 | m5.large | D2s v3 | -| GitLab Rails | 3 | 16 vCPU, 14.4GB memory | n1-highcpu-16 | c5.4xlarge | F16s v2 | -| Monitoring node | 1 | 2 vCPU, 1.8GB memory | n1-highcpu-2 | c5.large | F2s v2 | -| Object Storage | n/a | n/a | n/a | n/a | n/a | -| NFS Server (optional, not recommended) | 1 | 4 vCPU, 3.6GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | +| External load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Redis | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | +| Consul + Sentinel | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| PostgreSQL | 3 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | +| PgBouncer | 3 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Internal load balancing node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Gitaly | 2 (minimum) | 8 vCPU, 30 GB memory | n1-standard-8 | m5.2xlarge | D8s v3 | +| Sidekiq | 4 | 2 vCPU, 7.5 GB memory | n1-standard-2 | m5.large | D2s v3 | +| GitLab Rails | 3 | 16 vCPU, 14.4 GB memory | n1-highcpu-16 | c5.4xlarge | F16s v2 | +| Monitoring node | 1 | 2 vCPU, 1.8 GB memory | n1-highcpu-2 | c5.large | F2s v2 | +| Object storage | n/a | n/a | n/a | n/a | n/a | +| NFS server (optional, not recommended) | 1 | 4 vCPU, 3.6 GB memory | n1-highcpu-4 | c5.xlarge | F4s v2 | The Google Cloud Platform (GCP) architectures were built and tested using the [Intel Xeon E5 v3 (Haswell)](https://cloud.google.com/compute/docs/cpu-platforms) @@ -44,41 +44,43 @@ or higher, are required for your CPU or node counts. For more information, see our [Sysbench](https://github.com/akopytov/sysbench)-based [CPU benchmark](https://gitlab.com/gitlab-org/quality/performance/-/wikis/Reference-Architectures/GCP-CPU-Benchmarks). -For data objects (such as LFS, Uploads, or Artifacts), an -[object storage service](#configure-the-object-storage) is recommended instead -of NFS where possible, due to better performance and availability. Since this -doesn't require a node to be set up, *Object Storage* is noted as not -applicable (n/a) in the previous table. +Due to better performance and availability, for data objects (such as LFS, +uploads, or artifacts), using an [object storage service](#configure-the-object-storage) +is recommended instead of using NFS. Using an object storage service also +doesn't require you to provision and maintain a node. ## Setup components To set up GitLab and its components to accommodate up to 5,000 users: 1. [Configure the external load balancing node](#configure-the-external-load-balancer) - that will handle the load balancing of the two GitLab application services nodes. + to handle the load balancing of the GitLab application services nodes. 1. [Configure Redis](#configure-redis). 1. [Configure Consul and Sentinel](#configure-consul-and-sentinel). 1. [Configure PostgreSQL](#configure-postgresql), the database for GitLab. 1. [Configure PgBouncer](#configure-pgbouncer). -1. [Configure the internal load balancing node](#configure-the-internal-load-balancer) +1. [Configure the internal load balancing node](#configure-the-internal-load-balancer). 1. [Configure Gitaly](#configure-gitaly), which provides access to the Git repositories. 1. [Configure Sidekiq](#configure-sidekiq). 1. [Configure the main GitLab Rails application](#configure-gitlab-rails) - to run Puma/Unicorn, Workhorse, GitLab Shell, and to serve all frontend requests (UI, API, Git - over HTTP/SSH). -1. [Configure Prometheus](#configure-prometheus) to monitor your GitLab environment. -1. [Configure the Object Storage](#configure-the-object-storage) + to run Puma/Unicorn, Workhorse, GitLab Shell, and to serve all frontend + requests (which include UI, API, and Git over HTTP/SSH). +1. [Configure Prometheus](#configure-prometheus) to monitor your GitLab + environment. +1. [Configure the object storage](#configure-the-object-storage) used for shared data objects. -1. [Configure NFS (Optional)](#configure-nfs-optional) - to have shared disk storage service as an alternative to Gitaly and/or Object Storage (although - not recommended). NFS is required for GitLab Pages, you can skip this step if you're not using - that feature. +1. [Configure Advanced Search](#configure-advanced-search) (optional) for faster, + more advanced code search across your entire GitLab instance. +1. [Configure NFS](#configure-nfs-optional) (optional, and not recommended) + to have shared disk storage service as an alternative to Gitaly or object + storage. You can skip this step if you're not using GitLab Pages (which + requires NFS). -We start with all servers on the same 10.6.0.0/16 private network range, they -can connect to each other freely on those addresses. +The servers start on the same 10.6.0.0/24 private network range, and can +connect to each other freely on these addresses. -Here is a list and description of each machine and the assigned IP: +The following list includes descriptions of each server and its assigned IP: - `10.6.0.10`: External Load Balancer - `10.6.0.61`: Redis Primary @@ -107,19 +109,18 @@ Here is a list and description of each machine and the assigned IP: ## Configure the external load balancer -NOTE: **Note:** +In an active/active GitLab configuration, you'll need a load balancer to route +traffic to the application servers. The specifics on which load balancer to use +or its exact configuration is beyond the scope of GitLab documentation. We hope +that if you're managing multi-node systems like GitLab, you already have a load +balancer of choice. Some load balancer examples include HAProxy (open-source), +F5 Big-IP LTM, and Citrix Net Scaler. This documentation outline the ports and +protocols needed for use with GitLab. + This architecture has been tested and validated with [HAProxy](https://www.haproxy.org/) as the load balancer. Although other load balancers with similar feature sets could also be used, those load balancers have not been validated. -In an active/active GitLab configuration, you will need a load balancer to route -traffic to the application servers. The specifics on which load balancer to use -or the exact configuration is beyond the scope of GitLab documentation. We hope -that if you're managing multi-node systems like GitLab you have a load balancer of -choice already. Some examples including HAProxy (open-source), F5 Big-IP LTM, -and Citrix Net Scaler. This documentation will outline what ports and protocols -you need to use with GitLab. - The next question is how you will handle SSL in your environment. There are several different options: @@ -277,20 +278,17 @@ The requirements for a Redis setup are the following: ([Internet](https://gitlab.com/gitlab-org/gitlab-foss/uploads/c4cc8cd353604bd80315f9384035ff9e/The_Internet_IT_Crowd.png)), using a firewall. -NOTE: **Note:** -Redis nodes (both primary and replica) will need the same password defined in -`redis['password']`. At any time during a failover the Sentinels can -reconfigure a node and change its status from primary to replica and vice versa. +Both the primary and replica Redis nodes need the same password defined in +`redis['password']`. At any time during a failover, the Sentinels can reconfigure +a node and change its status from primary to replica (and vice versa). #### Configuring the primary Redis instance -1. SSH into the **Primary** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **Primary** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -334,10 +332,9 @@ reconfigure a node and change its status from primary to replica and vice versa. 1. [Reconfigure Omnibus GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). You can list the current Redis Primary, Replica status via: @@ -363,13 +360,11 @@ run: redis-exporter: (pid 30075) 76861s; run: log: (pid 29674) 76896s #### Configuring the replica Redis instances -1. SSH into the **replica** Redis server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - and type (Community, Enterprise editions) of your current install. - - Do not complete any other steps on the download page. - +1. SSH in to the **replica** Redis server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -422,10 +417,9 @@ run: redis-exporter: (pid 30075) 76861s; run: log: (pid 29674) 76896s 1. Go through the steps again for all the other replica nodes, and make sure to set up the IPs correctly. -NOTE: **Note:** -You can specify multiple roles like sentinel and Redis as: -`roles ['redis_sentinel_role', 'redis_master_role']`. -Read more about [roles](https://docs.gitlab.com/omnibus/roles/). +You can specify multiple roles, like sentinel and Redis, as: +`roles ['redis_sentinel_role', 'redis_master_role']`. Read more about +[roles](https://docs.gitlab.com/omnibus/roles/). These values don't have to be changed again in `/etc/gitlab/gitlab.rb` after a failover, as the nodes will be managed by the [Sentinels](#configure-consul-and-sentinel), and even after a @@ -443,13 +437,6 @@ are supported and can be added if needed. ## Configure Consul and Sentinel -NOTE: **Note:** -If you are using an external Redis Sentinel instance, be sure -to exclude the `requirepass` parameter from the Sentinel -configuration. This parameter will cause clients to report `NOAUTH -Authentication required.`. [Redis Sentinel 3.2.x does not support -password authentication](https://github.com/antirez/redis/issues/3279). - Now that the Redis servers are all set up, let's configure the Sentinel servers. The following IPs will be used as an example: @@ -457,16 +444,19 @@ servers. The following IPs will be used as an example: - `10.6.0.12`: Consul/Sentinel 2 - `10.6.0.13`: Consul/Sentinel 3 -To configure the Sentinel: +NOTE: **Note:** +If you're using an external Redis Sentinel instance, be sure to exclude the +`requirepass` parameter from the Sentinel configuration. This parameter causes +clients to report `NOAUTH Authentication required.`. +[Redis Sentinel 3.2.x doesn't support password authentication](https://github.com/antirez/redis/issues/3279). -1. SSH into the server that will host Consul/Sentinel. -1. [Download/install](https://about.gitlab.com/install/) the - Omnibus GitLab Enterprise Edition package using **steps 1 and 2** from the - GitLab downloads page. - - Make sure you select the correct Omnibus package, with the same version - the GitLab application is running. - - Do not complete any other steps on the download page. +To configure the Sentinel: +1. SSH in to the server that will host Consul/Sentinel. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to both follow _only_ installation steps 1 and 2 + on the page, and to select the correct Omnibus GitLab package, with the same version + and type (Community or Enterprise editions) as your current install. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -556,10 +546,9 @@ To configure the Sentinel: 1. Go through the steps again for all the other Consul/Sentinel nodes, and make sure you set up the correct IPs. -NOTE: **Note:** -A Consul leader will be elected when the provisioning of the third Consul server is completed. -Viewing the Consul logs `sudo gitlab-ctl tail consul` will display -`...[INFO] consul: New leader elected: ...` +A Consul leader is _elected_ when the provisioning of the third Consul server is +complete. Viewing the Consul logs `sudo gitlab-ctl tail consul` displays +`...[INFO] consul: New leader elected: ...`. You can list the current Consul members (server, client): @@ -627,7 +616,7 @@ in the second step, do not supply the `EXTERNAL_URL` value. #### PostgreSQL primary node -1. SSH into the PostgreSQL primary node. +1. SSH in to the PostgreSQL primary node. 1. Generate a password hash for the PostgreSQL username/password pair. This assumes you will use the default username of `gitlab` (recommended). The command will request a password and confirmation. Use the value that is output by this command in the next @@ -812,7 +801,7 @@ are supported and can be added if needed. #### PostgreSQL post-configuration -SSH into the **primary node**: +SSH in to the **primary node**: 1. Open a database prompt: @@ -847,7 +836,7 @@ SSH into the **primary node**: is not an IP address, it will need to be a resolvable name (via DNS or `/etc/hosts`) -SSH into the **secondary node**: +SSH in to the **secondary node**: 1. Set up the repmgr standby: @@ -1068,51 +1057,48 @@ Refer to your preferred Load Balancer's documentation for further guidance. ## Configure Gitaly -Deploying Gitaly in its own server can benefit GitLab installations that are -larger than a single machine. - -The Gitaly node requirements are dependent on customer data, specifically the number of -projects and their repository sizes. Two nodes are recommended as an absolute minimum. -Each Gitaly node should store no more than 5TB of data and have the number of -[`gitaly-ruby` workers](../gitaly/index.md#gitaly-ruby) set to 20% of available CPUs. -Additional nodes should be considered in conjunction with a review of expected -data size and spread based on the recommendations above. - -It is also strongly recommended that all Gitaly nodes be set up with SSD disks with -a throughput of at least 8,000 IOPS for read operations and 2,000 IOPS for write, -as Gitaly has heavy I/O. These IOPS values are recommended only as a starter as with -time they may be adjusted higher or lower depending on the scale of your environment's workload. -If you're running the environment on a Cloud provider, you may need to refer to -their documentation on how to configure IOPS correctly. - -Some things to note: - -- The GitLab Rails application shards repositories into [repository storages](../repository_storage_paths.md). -- A Gitaly server can host one or more storages. -- A GitLab server can use one or more Gitaly servers. -- Gitaly addresses must be specified in such a way that they resolve - correctly for ALL Gitaly clients. +[Gitaly](../gitaly/index.md) server node requirements are dependent on data, +specifically the number of projects and those projects' sizes. It's recommended +that a Gitaly server node stores no more than 5 TB of data. Although this +reference architecture includes a recommendation for the number of Gitaly server +nodes to use, depending on your storage requirements, you may require additional +Gitaly server nodes. + +Due to Gitaly having notable input and output requirements, we strongly +recommend that all Gitaly nodes use solid-state drives (SSDs). These SSDs should +have a throughput of at least 8,000 input/output operations per second (IOPS) +for read operations and 2,000 IOPS for write operations. These IOPS values are +initial recommendations, and may be adjusted to greater or lesser values +depending on the scale of your environment's workload. If you're running the +environment on a Cloud provider, refer to their documentation about how to +configure IOPS correctly. + +Be sure to note the following items: + +- The GitLab Rails application shards repositories into + [repository storage paths](../repository_storage_paths.md). +- A Gitaly server can host one or more storage paths. +- A GitLab server can use one or more Gitaly server nodes. +- Gitaly addresses must be specified to be correctly resolvable for _all_ + Gitaly clients. - Gitaly servers must not be exposed to the public internet, as Gitaly's network traffic is unencrypted by default. The use of a firewall is highly recommended to restrict access to the Gitaly server. Another option is to [use TLS](#gitaly-tls-support). -TIP: **Tip:** -For more information about Gitaly's history and network architecture see the -[standalone Gitaly documentation](../gitaly/index.md). - -Note: **Note:** The token referred to throughout the Gitaly documentation is -just an arbitrary password selected by the administrator. It is unrelated to -tokens created for the GitLab API or other similar web API tokens. +NOTE: **Note:** +The token referred to throughout the Gitaly documentation is an arbitrary +password selected by the administrator. This token is unrelated to tokens +created for the GitLab API or other similar web API tokens. -Below we describe how to configure two Gitaly servers, with IPs and -domain names: +This section describes how to configure two Gitaly servers, with the following +IPs and domain names: - `10.6.0.51`: Gitaly 1 (`gitaly1.internal`) - `10.6.0.52`: Gitaly 2 (`gitaly2.internal`) -The secret token is assumed to be `gitalysecret` and that -your GitLab installation has three repository storages: +Assumptions about your servers include having the secret token be `gitalysecret`, +and that your GitLab installation has three repository storages: - `default` on Gitaly 1 - `storage1` on Gitaly 1 @@ -1120,11 +1106,11 @@ your GitLab installation has three repository storages: On each node: -1. [Download/Install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page but - **without** providing the `EXTERNAL_URL` value. -1. Edit `/etc/gitlab/gitlab.rb` to configure storage paths, enable - the network listener and configure the token: +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page, and _do not_ provide the `EXTERNAL_URL` value. +1. Edit `/etc/gitlab/gitlab.rb` to configure the storage paths, enable + the network listener, and configure the token: -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). +1. Save the file, and then [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Confirm that Gitaly can perform callbacks to the internal API: ```shell - sudo /opt/gitlab/embedded/service/gitlab-shell/bin/check -config /opt/gitlab/embedded/service/gitlab-shell/config.yml + sudo /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml ``` 1. Verify the GitLab services are running: @@ -1258,11 +1244,10 @@ Name. If you are addressing the Gitaly server by its IP address, you must add it as a Subject Alternative Name to the certificate. [gRPC does not support using an IP address as Common Name in a certificate](https://github.com/grpc/grpc/issues/2691). -NOTE: **Note:** -It is possible to configure Gitaly servers with both an -unencrypted listening address `listen_addr` and an encrypted listening -address `tls_listen_addr` at the same time. This allows you to do a -gradual transition from unencrypted to encrypted traffic, if necessary. +It's possible to configure Gitaly servers with both an unencrypted listening +address (`listen_addr`) and an encrypted listening address (`tls_listen_addr`) +at the same time. This allows you to do a gradual transition from unencrypted to +encrypted traffic, if necessary. To configure Gitaly with TLS: @@ -1316,10 +1301,10 @@ The following IPs will be used as an example: To configure the Sidekiq nodes, one each one: -1. SSH into the Sidekiq server. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab package -you want using steps 1 and 2 from the GitLab downloads page. -**Do not complete any other steps on the download page.** +1. SSH in to the Sidekiq server. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Open `/etc/gitlab/gitlab.rb` with your editor: ```ruby @@ -1430,14 +1415,14 @@ You can also run [multiple Sidekiq processes](../operations/extra_sidekiq_proces ## Configure GitLab Rails -NOTE: **Note:** -In our architectures we run each GitLab Rails node using the Puma webserver -and have its number of workers set to 90% of available CPUs along with four threads. For -nodes that are running Rails with other components the worker value should be reduced -accordingly where we've found 50% achieves a good balance but this is dependent -on workload. - This section describes how to configure the GitLab application (Rails) component. + +In our architecture, we run each GitLab Rails node using the Puma webserver, and +have its number of workers set to 90% of available CPUs, with four threads. For +nodes running Rails with other components, the worker value should be reduced +accordingly. We've determined that a worker value of 50% achieves a good balance, +but this is dependent on workload. + On each node perform the following: 1. If you're [using NFS](#configure-nfs-optional): @@ -1465,10 +1450,10 @@ On each node perform the following: mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data ``` -1. Download/install Omnibus GitLab using **steps 1 and 2** from - [GitLab downloads](https://about.gitlab.com/install/). Do not complete other - steps on the download page. -1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. +1. Create or edit `/etc/gitlab/gitlab.rb` and use the following configuration. To maintain uniformity of links across nodes, the `external_url` on the application server should point to the external URL that users will use to access GitLab. This would be the URL of the [external load balancer](#configure-the-external-load-balancer) @@ -1581,6 +1566,11 @@ On each node perform the following: sudo gitlab-ctl tail gitaly ``` +1. Save the `/etc/gitlab/gitlab-secrets.json` file from one of the two + application nodes and install it on the other application node, the + [Gitaly node](#configure-gitaly) and the [Sidekiq node](#configure-sidekiq) and + [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + 1. Verify the GitLab services are running: ```shell @@ -1599,12 +1589,10 @@ On each node perform the following: run: puma: (pid 4936) 8645s; run: log: (pid 29656) 79161s ``` -NOTE: **Note:** -When you specify `https` in the `external_url`, as in the example -above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If -certificates are not present, NGINX will fail to start. See the -[NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) -for more information. +When you specify `https` in the `external_url`, as in the previous example, +GitLab expects that the SSL certificates are in `/etc/gitlab/ssl/`. If the +certificates aren't present, NGINX will fail to start. For more information, see +the [NGINX documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https). ### GitLab Rails post-configuration @@ -1614,12 +1602,11 @@ for more information. gitlab-rake gitlab:db:configure ``` - NOTE: **Note:** - If you encounter a `rake aborted!` error stating that PgBouncer is failing to connect to - PostgreSQL it may be that your PgBouncer node's IP address is missing from - PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` on your database nodes. See - [PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server) - in the Troubleshooting section before proceeding. + If you encounter a `rake aborted!` error message stating that PgBouncer is + failing to connect to PostgreSQL, it may be that your PgBouncer node's IP + address is missing from PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` + on your database nodes. Before proceeding, see + [PgBouncer error `ERROR: pgbouncer cannot connect to server`](troubleshooting.md#pgbouncer-error-error-pgbouncer-cannot-connect-to-server). 1. [Configure fast lookup of authorized SSH keys in the database](../operations/fast_ssh_key_lookup.md). @@ -1635,10 +1622,10 @@ The Omnibus GitLab package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md): -1. SSH into the Monitoring node. -1. [Download/install](https://about.gitlab.com/install/) the Omnibus GitLab - package you want using **steps 1 and 2** from the GitLab downloads page. - Do not complete any other steps on the download page. +1. SSH in to the Monitoring node. +1. [Download and install](https://about.gitlab.com/install/) the Omnibus GitLab + package of your choice. Be sure to follow _only_ installation steps 1 and 2 + on the page. 1. Edit `/etc/gitlab/gitlab.rb` and add the contents: ```ruby @@ -1713,28 +1700,44 @@ It's recommended over [NFS](#configure-nfs-optional) and in general it's better in larger setups as object storage is typically much more performant, reliable, and scalable. -Object storage options that GitLab has tested, or is aware of customers using include: +GitLab has been tested on a number of object storage providers: -- SaaS/Cloud solutions such as [Amazon S3](https://aws.amazon.com/s3/), [Google cloud storage](https://cloud.google.com/storage). +- [Amazon S3](https://aws.amazon.com/s3/) +- [Google Cloud Storage](https://cloud.google.com/storage) +- [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces/) +- [Oracle Cloud Infrastructure](https://docs.cloud.oracle.com/en-us/iaas/Content/Object/Tasks/s3compatibleapi.htm) +- [Openstack Swift](https://docs.openstack.org/swift/latest/s3_compat.html) +- [Azure Blob storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) - On-premises hardware and appliances from various storage vendors. -- MinIO. There is [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. - -For configuring GitLab to use Object Storage refer to the following guides -based on what features you intend to use: - -1. Configure [object storage for backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage). -1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) - including [incremental logging](../job_logs.md#new-incremental-logging-architecture). -1. Configure [object storage for LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage). -1. Configure [object storage for uploads](../uploads.md#using-object-storage). -1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). -1. Configure [object storage for Container Registry](../packages/container_registry.md#use-object-storage) (optional feature). -1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature). -1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). **(PREMIUM ONLY)** -1. Configure [object storage for Pseudonymizer](../pseudonymizer.md#configuration) (optional feature). **(ULTIMATE ONLY)** -1. Configure [object storage for autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional - for improved performance). -1. Configure [object storage for Terraform state files](../terraform_state.md#using-object-storage). +- MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. + +There are two ways of specifying object storage configuration in GitLab: + +- [Consolidated form](../object_storage.md#consolidated-object-storage-configuration): A single credential is + shared by all supported object types. +- [Storage-specific form](../object_storage.md#storage-specific-configuration): Every object defines its + own object storage [connection and configuration](../object_storage.md#connection-settings). + +Starting with GitLab 13.2, consolidated object storage configuration is available. It simplifies your GitLab configuration since the connection details are shared across object types. Refer to [Consolidated object storage configuration](../object_storage.md#consolidated-object-storage-configuration) guide for instructions on how to set it up. + +For configuring object storage in GitLab 13.1 and earlier, or for storage types not +supported by consolidated configuration form, refer to the following guides based +on what features you intend to use: + +|Object storage type|Supported by consolidated configuration?| +|-------------------|----------------------------------------| +| [Backups](../../raketasks/backup_restore.md#uploading-backups-to-a-remote-cloud-storage)|No| +| [Job artifacts](../job_artifacts.md#using-object-storage) including archived job logs | Yes | +| [LFS objects](../lfs/index.md#storing-lfs-objects-in-remote-object-storage) | Yes | +| [Uploads](../uploads.md#using-object-storage) | Yes | +| [Container Registry](../packages/container_registry.md#use-object-storage) (optional feature) | No | +| [Merge request diffs](../merge_request_diffs.md#using-object-storage) | Yes | +| [Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage)| No | +| [Packages](../packages/index.md#using-object-storage) (optional feature) | Yes | +| [Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature) **(PREMIUM ONLY)** | Yes | +| [Pseudonymizer](../pseudonymizer.md#configuration) (optional feature) **(ULTIMATE ONLY)** | No | +| [Autoscale runner caching](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching) (optional for improved performance) | No | +| [Terraform state files](../terraform_state.md#using-object-storage) | Yes | Using separate buckets for each data type is the recommended approach for GitLab. @@ -1758,6 +1761,22 @@ work.
+## Configure Advanced Search **(STARTER ONLY)** + +You can leverage Elasticsearch and [enable Advanced Search](../../integration/elasticsearch.md) +for faster, more advanced code search across your entire GitLab instance. + +Elasticsearch cluster design and requirements are dependent on your specific +data. For recommended best practices about how to set up your Elasticsearch +cluster alongside your instance, read how to +[choose the optimal cluster configuration](../../integration/elasticsearch.md#guidance-on-choosing-optimal-cluster-configuration). + +
+ + Back to setup components + +
+ ## Configure NFS (optional) [Object storage](#configure-the-object-storage), along with [Gitaly](#configure-gitaly) diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 3964b8daeb7..8816d0eecf4 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -105,7 +105,7 @@ is the least complex to setup. This provides a point-in-time recovery of a prede > - Supported tiers: [GitLab Starter, Premium, and Ultimate](https://about.gitlab.com/pricing/) This requires separating out GitLab into multiple application nodes with an added -[load balancer](../high_availability/load_balancer.md). The load balancer will distribute traffic +[load balancer](../load_balancer.md). The load balancer will distribute traffic across GitLab application nodes. Meanwhile, each application node connects to a shared file server and database systems on the back end. This way, if one of the application servers fails, the workflow is not interrupted. diff --git a/doc/administration/reply_by_email_postfix_setup.md b/doc/administration/reply_by_email_postfix_setup.md index f950134889d..f4fcbefa403 100644 --- a/doc/administration/reply_by_email_postfix_setup.md +++ b/doc/administration/reply_by_email_postfix_setup.md @@ -71,7 +71,7 @@ The instructions make the assumption that you will be using the email address `i sudo postfix start ``` -1. Send the new `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt: +1. Send the new `incoming` user an email to test SMTP, by entering the following into the SMTP prompt: ```plaintext ehlo localhost @@ -112,7 +112,7 @@ The instructions make the assumption that you will be using the email address `i q ``` -1. Log out of the `incoming` account and go back to being `root`: +1. Sign out of the `incoming` account, and go back to being `root`: ```shell logout @@ -164,7 +164,7 @@ Courier, which we will install later to add IMAP authentication, requires mailbo try the above steps again, substituting `heirloom-mailx` for the `mail` command._ -1. Log out of the `incoming` account and go back to being `root`: +1. Sign out of the `incoming` account, and go back to being `root`: ```shell logout @@ -251,7 +251,7 @@ Courier, which we will install later to add IMAP authentication, requires mailbo If you get a `Connection refused` error instead, make sure your firewall is set up to allow inbound traffic on port 25. - 1. Send the `incoming` user a dummy email to test SMTP, by entering the following into the SMTP prompt: + 1. Send the `incoming` user an email to test SMTP, by entering the following into the SMTP prompt: ```plaintext ehlo gitlab.example.com @@ -288,7 +288,7 @@ Courier, which we will install later to add IMAP authentication, requires mailbo q ``` - 1. Log out of the `incoming` account and go back to being `root`: + 1. Sign out of the `incoming` account, and go back to being `root`: ```shell logout diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 1c036cfe2ac..b272c4b463e 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -83,7 +83,7 @@ The "Gitaly relative path" is shown there, for example: This is the path under `/var/opt/gitlab/git-data/repositories/` on a default Omnibus installation. -In a [Rails console](troubleshooting/debug.md#starting-a-rails-console-session), +In a [Rails console](operations/rails_console.md#starting-a-rails-console-session), get this information using either the numeric project ID or the full path: ```ruby @@ -95,7 +95,7 @@ Project.find_by_full_path('group/project').disk_path To translate from a hashed storage path to a project name: -1. Start a [Rails console](troubleshooting/debug.md#starting-a-rails-console-session). +1. Start a [Rails console](operations/rails_console.md#starting-a-rails-console-session). 1. Run the following: ```ruby diff --git a/doc/administration/server_hooks.md b/doc/administration/server_hooks.md index 54b2cd43265..b5e975d397f 100644 --- a/doc/administration/server_hooks.md +++ b/doc/administration/server_hooks.md @@ -156,22 +156,6 @@ NOTE: **Note:** While other environment variables can be passed to server hooks, your application should not rely on them as they can change. -## Transition to Go - -> - Introduced in GitLab 13.2 using feature flags. -> - In GitLab 13.4, `update` Ruby [implementation removed](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2501). -> - In GitLab 13.4, `post-receive` Go implementation [made default](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/2502). - -The following server hooks have been re-implemented in Go: - -- `pre-receive`, with the Go implementation used by default. To use the Ruby implementation instead, - [disable](feature_flags.md#enable-or-disable-the-feature) the `:gitaly_go_preceive_hook` feature - flag. -- `update`, with Go implementation always used. No Ruby implementation is available. -- `post-receive`, with the Go implementation used by default. To use the Ruby implementation - instead, [disable](feature_flags.md#enable-or-disable-the-feature) the - `:gitaly_go_postreceive_hook` feature flag. - ## Custom error messages > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5073) in GitLab 8.10. diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md index b1e7e349978..6ded7fdd7d0 100644 --- a/doc/administration/smime_signing_email.md +++ b/doc/administration/smime_signing_email.md @@ -75,8 +75,8 @@ extensions), which contain the following in a single encrypted file: - Intermediate certificates (if any) - Private key -In order to export the required files in PEM encoding from the PKCS#12 file, -the `openssl` command can be used: +To export the required files in PEM encoding from the PKCS#12 file, the +`openssl` command can be used: ```shell #-- Extract private key in PEM encoding (no password, unencrypted) diff --git a/doc/administration/snippets/index.md b/doc/administration/snippets/index.md index 95de3b8c183..5e61d20c683 100644 --- a/doc/administration/snippets/index.md +++ b/doc/administration/snippets/index.md @@ -20,8 +20,8 @@ abuse of the feature. The default value is **52428800 Bytes** (50 MB). The content size limit will be applied when a snippet is created or updated. -In order not to break any existing snippets, the limit doesn't have any -effect on them until a snippet is edited again and the content changes. +This limit doesn't affect existing snippets until they're updated and their +content changes. ### Snippets size limit configuration diff --git a/doc/administration/terraform_state.md b/doc/administration/terraform_state.md index 76e54acce16..55e166d2bf7 100644 --- a/doc/administration/terraform_state.md +++ b/doc/administration/terraform_state.md @@ -1,3 +1,9 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Terraform state administration (alpha) > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 12.10. diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md index a1b4df9b94e..ef95bdc8602 100644 --- a/doc/administration/troubleshooting/debug.md +++ b/doc/administration/troubleshooting/debug.md @@ -5,27 +5,15 @@ in production. ## Starting a Rails console session -Troubleshooting and debugging your GitLab instance often requires a -[Rails console](https://guides.rubyonrails.org/command_line.html#rails-console). +Troubleshooting and debugging your GitLab instance often requires a Rails console. + +Your type of GitLab installation determines how +[to start a rails console](../operations/rails_console.md). See also: - [GitLab Rails Console Cheat Sheet](gitlab_rails_cheat_sheet.md). - [Navigating GitLab via Rails console](navigating_gitlab_via_rails_console.md). -**For Omnibus installations** - -```shell -sudo gitlab-rails console -``` - -**For installations from source** - -```shell -sudo -u git -H bundle exec rails console -e production -``` - -Kubernetes: the console is in the task-runner pod, refer to our [Kubernetes cheat sheet](kubernetes_cheat_sheet.md#gitlab-specific-kubernetes-information) for details. - ### Enabling Active Record logging You can enable output of Active Record debug logging in the Rails console @@ -98,7 +86,7 @@ sudo -u git -H bundle exec rails runner -e production /path/to/script.rb A common problem is that mails are not being sent for some reason. Suppose you configured an SMTP server, but you're not seeing mail delivered. Here's how to check the settings: -1. Run a [Rails console](#starting-a-rails-console-session). +1. Run a [Rails console](../operations/rails_console.md#starting-a-rails-console-session). 1. Look at the ActionMailer `delivery_method` to make sure it matches what you intended. If you configured SMTP, it should say `:smtp`. If you're using @@ -238,7 +226,7 @@ separate Rails process to debug the issue: 1. Log in to your GitLab account. 1. Copy the URL that is causing problems (e.g. `https://gitlab.com/ABC`). 1. Create a Personal Access Token for your user (Profile Settings -> Access Tokens). -1. Bring up the [GitLab Rails console.](#starting-a-rails-console-session) +1. Bring up the [GitLab Rails console.](../operations/rails_console.md#starting-a-rails-console-session) 1. At the Rails console, run: ```ruby diff --git a/doc/administration/troubleshooting/elasticsearch.md b/doc/administration/troubleshooting/elasticsearch.md index e13261e3074..6de5bb71d75 100644 --- a/doc/administration/troubleshooting/elasticsearch.md +++ b/doc/administration/troubleshooting/elasticsearch.md @@ -164,7 +164,7 @@ Troubleshooting search result issues is rather straight forward on Elasticsearch The first step is to confirm GitLab is using Elasticsearch for the search function. To do this: -1. Confirm the integration is enabled in **Admin Area > Settings > Integrations**. +1. Confirm the integration is enabled in **Admin Area > Settings > General**. 1. Confirm searches utilize Elasticsearch by accessing the rails console (`sudo gitlab-rails console`) and running the following commands: @@ -206,7 +206,7 @@ The best place to start is to determine if the issue is with creating an empty i If it is, check on the Elasticsearch side to determine if the `gitlab-production` (the name for the GitLab index) exists. If it exists, manually delete it on the Elasticsearch side and attempt to recreate it from the -[`recreate_index`](../../integration/elasticsearch.md#gitlab-elasticsearch-rake-tasks) +[`recreate_index`](../../integration/elasticsearch.md#gitlab-advanced-search-rake-tasks) Rake task. If you still encounter issues, try creating an index manually on the Elasticsearch @@ -225,8 +225,8 @@ during the indexing of projects. If errors do occur, they will either stem from If the indexing process does not present errors, you will want to check the status of the indexed projects. You can do this via the following Rake tasks: -- [`sudo gitlab-rake gitlab:elastic:index_projects_status`](../../integration/elasticsearch.md#gitlab-elasticsearch-rake-tasks) (shows the overall status) -- [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](../../integration/elasticsearch.md#gitlab-elasticsearch-rake-tasks) (shows specific projects that are not indexed) +- [`sudo gitlab-rake gitlab:elastic:index_projects_status`](../../integration/elasticsearch.md#gitlab-advanced-search-rake-tasks) (shows the overall status) +- [`sudo gitlab-rake gitlab:elastic:projects_not_indexed`](../../integration/elasticsearch.md#gitlab-advanced-search-rake-tasks) (shows specific projects that are not indexed) If: diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index 9a23a115765..dbda889d370 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -222,11 +222,12 @@ namespace = Namespace.find_by_full_path("") ```ruby # ID will be the webhook_id -WebHookLog.where(web_hook_id: ID).each_slice(ID) do |slice| - slice.each(&:destroy) -end +hook=WebHook.find(ID) + +WebHooks::DestroyService.new(current_user).execute(hook) -WebHook.find(ID).destroy +#In case the service gets timeout consider removing webhook_logs +hook.web_hook_logs.limit(BATCH_SIZE).delete_all ``` ### Bulk update service integration password for _all_ projects @@ -285,6 +286,16 @@ GitlabShellWorker.perform_in(0, :remove_repository, p.repository_storage, p.wiki p.create_wiki ### creates the wiki project on the filesystem ``` +## Issue boards + +### In case of issue boards not loading properly and it's getting time out. We need to call the Issue Rebalancing service to fix this + +```ruby +p=Project.find_by_full_path('PROJECT PATH') + +IssueRebalancingService.new(p.issues.take).execute +``` + ## Imports / Exports ```ruby @@ -411,6 +422,9 @@ user.skip_reconfirmation! # Active users on the instance, now User.active.count +# Users taking a seat on the instance +License.current.current_active_users_count + # The historical max on the instance as of the past year ::HistoricalData.max_historical_user_count ``` @@ -506,6 +520,54 @@ group = Group.find_by_path_or_name('group-name') group.project_creation_level=0 ``` +## SCIM + +### Fixing bad SCIM identities + +```ruby +def delete_bad_scim(email, group_path) + output = "" + u = User.find_by_email(email) + uid = u.id + g = Group.find_by_full_path(group_path) + saml_prov_id = SamlProvider.find_by(group_id: g.id).id + saml = Identity.where(user_id: uid, saml_provider_id: saml_prov_id) + scim = ScimIdentity.where(user_id: uid , group_id: g.id) + if saml[0] + saml_eid = saml[0].extern_uid + output += "%s," % [email] + output += "SAML: %s," % [saml_eid] + if scim[0] + scim_eid = scim[0].extern_uid + output += "SCIM: %s" % [scim_eid] + if saml_eid == scim_eid + output += " Identities matched, not deleted \n" + else + scim[0].destroy + output += " Deleted \n" + end + else + output = "ERROR No SCIM identify found for: [%s]\n" % [email] + puts output + return 1 + end + else + output = "ERROR No SAML identify found for: [%s]\n" % [email] + puts output + return 1 + end + puts output + return 0 +end + +# In case of multiple emails +emails = [email1, email2] + +emails.each do |e| + delete_bad_scim(e,'GROUPPATH') +end +``` + ## Routes ### Remove redirecting routes @@ -525,8 +587,8 @@ conflicting_permanent_redirects.destroy_all ### Close a merge request properly (if merged but still marked as open) ```ruby -p = Project.find_by_full_path('') -m = project.merge_requests.find_by(iid: ) +p = Project.find_by_full_path('') +m = p.merge_requests.find_by(iid: ) u = User.find_by_username('') MergeRequests::PostMergeService.new(p, u).execute(m) ``` diff --git a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md index 01532032b49..7c5a9e0d79f 100644 --- a/doc/administration/troubleshooting/kubernetes_cheat_sheet.md +++ b/doc/administration/troubleshooting/kubernetes_cheat_sheet.md @@ -84,8 +84,7 @@ and they will assist you with any issues you are having. ## GitLab-specific Kubernetes information -- Minimal config that can be used to test a Kubernetes Helm chart can be found - [here](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/620). +- Minimal configuration that can be used to [test a Kubernetes Helm chart](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/620). - Tailing logs of a separate pod. An example for a Webservice pod: @@ -190,7 +189,7 @@ and they will assist you with any issues you are having. be possible to use [Updating GitLab using the Helm Chart](https://docs.gitlab.com/charts/index.html#updating-gitlab-using-the-helm-chart) for upgrades. -- How to apply changes to GitLab config: +- How to apply changes to GitLab configuration: - Modify the `gitlab.yaml` file. - Run the following command to apply changes: @@ -255,7 +254,7 @@ to those documents for details. helm install gitlab -f gitlab/gitlab ``` - If you want to modify some GitLab settings, you can use the above-mentioned config + If you want to modify some GitLab settings, you can use the above-mentioned configuration as a base and create your own YAML file. - Monitor the installation progress via `helm status gitlab` and `minikube dashboard`. diff --git a/doc/administration/troubleshooting/log_parsing.md b/doc/administration/troubleshooting/log_parsing.md index dcd1df2f423..7914628a756 100644 --- a/doc/administration/troubleshooting/log_parsing.md +++ b/doc/administration/troubleshooting/log_parsing.md @@ -3,11 +3,11 @@ We recommend using log aggregation and search tools like Kibana and Splunk whenever possible, but if they are not available you can still quickly parse [GitLab logs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26311) in JSON format -(the default since GitLab 12.0) using [`jq`](https://stedolan.github.io/jq/). +(the default in GitLab 12.0 and later) using [`jq`](https://stedolan.github.io/jq/). ## What is JQ? -As noted in its [manual](https://stedolan.github.io/jq/manual/), jq is a command-line JSON processor. The following examples +As noted in its [manual](https://stedolan.github.io/jq/manual/), `jq` is a command-line JSON processor. The following examples include use cases targeted for parsing GitLab log files. ## Parsing Logs diff --git a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md index 571973c12d9..a1485249b0e 100644 --- a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md +++ b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md @@ -3,7 +3,7 @@ At the heart of GitLab is a web application [built using the Ruby on Rails framework](https://about.gitlab.com/blog/2018/10/29/why-we-use-rails-to-build-gitlab/). Thanks to this, we also get access to the amazing tools built right into Rails. -In this guide, we'll introduce the [Rails console](debug.md#starting-a-rails-console-session) +In this guide, we'll introduce the [Rails console](../operations/rails_console.md#starting-a-rails-console-session) and the basics of interacting with your GitLab instance from the command line. CAUTION: **Caution:** @@ -20,20 +20,10 @@ Rails experience is helpful to have but not a must. ## Starting a Rails console session -Omnibus GitLab comes with a convenient wrapper command which automatically loads -the production GitLab environment: +Your type of GitLab installation determines how +[to start a rails console](../operations/rails_console.md). -```shell -sudo gitlab-rails console -``` - -For source installations, you'll have to instead run: - -```shell -sudo -u git -H bundle exec rails console -e production -``` - -Further code examples will all take place inside the Rails console and also +The following code examples will all take place inside the Rails console and also assume an Omnibus GitLab installation. ## Active Record objects diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index 404e806c5d9..b7762f8ac3e 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.md @@ -7,7 +7,7 @@ may be filling up. Users will notice when this happens because new branches may not show up and merge requests may not be updated. The following are some troubleshooting steps that will help you diagnose the bottleneck. -NOTE **Note:** +NOTE: **Note:** GitLab administrators/users should consider working through these debug steps with GitLab Support so the backtraces can be analyzed by our team. It may reveal a bug or necessary improvement in GitLab. diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md index e6c081e1eea..4d4b9755fa9 100644 --- a/doc/administration/troubleshooting/ssl.md +++ b/doc/administration/troubleshooting/ssl.md @@ -23,7 +23,7 @@ After configuring a GitLab instance with an internal CA certificate, you might n More details here: https://curl.haxx.se/docs/sslcerts.html ``` -- Testing via the [rails console](debug.md#starting-a-rails-console-session) also fails: +- Testing via the [rails console](../operations/rails_console.md#starting-a-rails-console-session) also fails: ```ruby uri = URI.parse("https://gitlab.domain.tld") @@ -205,6 +205,6 @@ Some of these errors come from the Excon Ruby gem, and could be generated in cir where GitLab is configured to initiate an HTTPS session to a remote server that is serving just HTTP. -One scenario is that you're using [object storage](../high_availability/object_storage.md) +One scenario is that you're using [object storage](../object_storage.md) which is not served under HTTPS. GitLab is misconfigured and attempts a TLS handshake, but the object storage will respond with plain HTTP. diff --git a/doc/administration/troubleshooting/tracing_correlation_id.md b/doc/administration/troubleshooting/tracing_correlation_id.md index 03c342595a3..ae9ebd90951 100644 --- a/doc/administration/troubleshooting/tracing_correlation_id.md +++ b/doc/administration/troubleshooting/tracing_correlation_id.md @@ -4,7 +4,7 @@ type: reference # Finding relevant log entries with a correlation ID -Since GitLab 11.6, a unique request tracking ID, known as the "correlation ID" has been +In GitLab 11.6 and later, a unique request tracking ID, known as the "correlation ID" has been logged by the GitLab instance for most requests. Each individual request to GitLab gets its own correlation ID, which then gets logged in each GitLab component's logs for that request. This makes it easier to trace behavior in a @@ -122,5 +122,5 @@ If you have done some horizontal scaling in your GitLab infrastructure, then you will need to search across _all_ of your GitLab nodes. You can do this with some sort of log aggregation software like Loki, ELK, Splunk, or others. -You can use a tool like Ansible or PSSH (parellel SSH) that can execute identical commands across your servers in +You can use a tool like Ansible or PSSH (parallel SSH) that can execute identical commands across your servers in parallel, or craft your own solution. diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 71a41719003..91de089c45e 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -2,6 +2,35 @@ Uploads represent all user data that may be sent to GitLab as a single file. As an example, avatars and notes' attachments are uploads. Uploads are integral to GitLab functionality, and therefore cannot be disabled. +## Upload parameters + +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/214785) in GitLab 13.5. +> - It's [deployed behind a feature flag](../user/feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to disable it. **(CORE ONLY)** + +In 13.5 and later, upload parameters are passed [between Workhorse and GitLab Rails](../development/architecture.md#simplified-component-overview) differently than they +were before. + +This change is deployed behind a feature flag that is **enabled by default**. + +If you experience any issues with upload, +[GitLab administrators with access to the GitLab Rails console](./feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:upload_middleware_jwt_params_handler) +``` + +To disable it: + +```ruby +Feature.disable(:upload_middleware_jwt_params_handler) +``` + ## Using local storage NOTE: **Note:** @@ -58,7 +87,7 @@ This configuration relies on valid AWS credentials to be configured already. [Read more about using object storage with GitLab](object_storage.md). NOTE: **Note:** -We recommend using the [consolidated object storage settings](object_storage.md#consolidated-object-storage-configuration). The following instructions apply to the original config format. +We recommend using the [consolidated object storage settings](object_storage.md#consolidated-object-storage-configuration). The following instructions apply to the original configuration format. ## Object Storage Settings @@ -68,9 +97,9 @@ For source installations the following settings are nested under `uploads:` and |---------|-------------|---------| | `enabled` | Enable/disable object storage | `false` | | `remote_directory` | The bucket name where Uploads will be stored| | -| `direct_upload` | Set to true to remove Puma from the Upload path. Workhorse handles the actual Artifact Upload to Object Storage while Puma does minimal processing to keep track of the upload. There is no need for local shared storage. The option may be removed if support for a single storage type for all files is introduced. Read more on [direct upload](../development/uploads.md#direct-upload). | `false` | -| `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3 (if `direct_upload` is set to `true` it will override `background_upload`) | `true` | -| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | +| `direct_upload` | Set to `true` to remove Puma from the Upload path. Workhorse handles the actual Artifact Upload to Object Storage while Puma does minimal processing to keep track of the upload. There is no need for local shared storage. The option may be removed if support for a single storage type for all files is introduced. Read more on [direct upload](../development/uploads.md#direct-upload). | `false` | +| `background_upload` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 (if `direct_upload` is set to `true` it will override `background_upload`) | `true` | +| `proxy_download` | Set to `true` to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | | `connection` | Various connection options described below | | ### Connection settings diff --git a/doc/api/README.md b/doc/api/README.md index 53df4114a71..3f7dae055e2 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -83,7 +83,11 @@ There are several ways to authenticate with the GitLab API: 1. [OAuth2 tokens](#oauth2-tokens) 1. [Personal access tokens](../user/profile/personal_access_tokens.md) -1. [Project access tokens](../user/project/settings/project_access_tokens.md) **(CORE ONLY)** +1. [Project access tokens](../user/project/settings/project_access_tokens.md) + +NOTE: **Note:** +Project access tokens are supported for self-managed instances on Core and above. They are also supported on GitLab.com Bronze and above. + 1. [Session cookie](#session-cookie) 1. [GitLab CI/CD job token](#gitlab-ci-job-token) **(Specific endpoints only)** @@ -158,9 +162,22 @@ for example, without needing to explicitly pass an access token. With a few API endpoints you can use a [GitLab CI/CD job token](../user/project/new_ci_build_permissions_model.md#job-token) to authenticate with the API: +- Packages: + - [Composer Repository](../user/packages/composer_repository/index.md) + - [Conan Repository](../user/packages/conan_repository/index.md) + - [Container Registry](../user/packages/container_registry/index.md) (`$CI_REGISTRY_PASSWORD` is actually `$CI_JOB_TOKEN`, but this may change in the future) + - [Go Proxy](../user/packages/go_proxy/index.md) + - [Maven Repository](../user/packages/maven_repository/index.md#authenticate-with-a-ci-job-token) + - [NPM Repository](../user/packages/npm_registry/index.md#authenticating-with-a-ci-job-token) + - [Nuget Repository](../user/packages/nuget_repository/index.md) + - [PyPI Repository](../user/packages/pypi_repository/index.md#using-gitlab-ci-with-pypi-packages) + - [Generic packages](../user/packages/generic_packages/index.md#publish-a-generic-package-by-using-cicd) - [Get job artifacts](job_artifacts.md#get-job-artifacts) -- [Pipeline triggers](pipeline_triggers.md) +- [Pipeline triggers](pipeline_triggers.md) (via `token=` parameter) - [Release creation](releases/index.md#create-a-release) +- [Terraform plan](../user/infrastructure/index.md) + +The token is valid as long as the job is running. ### Impersonation tokens @@ -297,21 +314,22 @@ The following table gives an overview of how the API functions generally behave. The following table shows the possible return codes for API requests. -| Return values | Description | -| ------------- | ----------- | -| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. | -| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. | -| `201 Created` | The `POST` request was successful and the resource is returned as JSON. | -| `304 Not Modified` | Indicates that the resource has not been modified since the last request. | -| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. | -| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. | -| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. | -| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. | +| Return values | Description | +| ------------------------ | ----------- | +| `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. | +| `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. | +| `201 Created` | The `POST` request was successful and the resource is returned as JSON. | +| `304 Not Modified` | Indicates that the resource has not been modified since the last request. | +| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. | +| `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. | +| `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. | +| `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. | | `405 Method Not Allowed` | The request is not supported. | -| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. | -| `412` | Indicates the request was denied. May happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | -| `422 Unprocessable` | The entity could not be processed. | -| `500 Server Error` | While handling the request something went wrong server-side. | +| `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. | +| `412` | Indicates the request was denied. May happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | +| `422 Unprocessable` | The entity could not be processed. | +| `429 Too Many Requests` | The user exceeded the [application rate limits](../administration/instance_limits.md#rate-limits). | +| `500 Server Error` | While handling the request, something went wrong server-side. | ## Pagination @@ -360,22 +378,22 @@ curl --head --header "PRIVATE-TOKEN: " "https://gitlab.exampl The response will then be: ```http -HTTP/1.1 200 OK -Cache-Control: no-cache -Content-Length: 1103 -Content-Type: application/json -Date: Mon, 18 Jan 2016 09:43:18 GMT -Link: ; rel="prev", ; rel="next", ; rel="first", ; rel="last" -Status: 200 OK -Vary: Origin -X-Next-Page: 3 -X-Page: 2 -X-Per-Page: 3 -X-Prev-Page: 1 -X-Request-Id: 732ad4ee-9870-4866-a199-a9db0cde3c86 -X-Runtime: 0.108688 -X-Total: 8 -X-Total-Pages: 3 +HTTP/2 200 OK +cache-control: no-cache +content-length: 1103 +content-type: application/json +date: Mon, 18 Jan 2016 09:43:18 GMT +link: ; rel="prev", ; rel="next", ; rel="first", ; rel="last" +status: 200 OK +vary: Origin +x-next-page: 3 +x-page: 2 +x-per-page: 3 +x-prev-page: 1 +x-request-id: 732ad4ee-9870-4866-a199-a9db0cde3c86 +x-runtime: 0.108688 +x-total: 8 +x-total-pages: 3 ``` #### Other pagination headers @@ -384,12 +402,12 @@ GitLab also returns the following additional pagination headers: | Header | Description | | --------------- | --------------------------------------------- | -| `X-Total` | The total number of items | -| `X-Total-Pages` | The total number of pages | -| `X-Per-Page` | The number of items per page | -| `X-Page` | The index of the current page (starting at 1) | -| `X-Next-Page` | The index of the next page | -| `X-Prev-Page` | The index of the previous page | +| `x-total` | The total number of items | +| `x-total-pages` | The total number of pages | +| `x-per-page` | The number of items per page | +| `x-page` | The index of the current page (starting at 1) | +| `x-next-page` | The index of the next page | +| `X-prev-page` | The index of the previous page | NOTE: **Note:** For GitLab.com users, [some pagination headers may not be returned](../user/gitlab_com/index.md#pagination-response-headers). @@ -588,7 +606,7 @@ Such errors appear in two cases: - A required attribute of the API request is missing, e.g., the title of an issue is not given -- An attribute did not pass the validation, e.g., user bio is too long +- An attribute did not pass the validation, e.g., the user bio is too long When an attribute is missing, you will get something like: diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md index 4a2456d6f4a..22488d053b4 100644 --- a/doc/api/admin_sidekiq_queues.md +++ b/doc/api/admin_sidekiq_queues.md @@ -29,6 +29,7 @@ DELETE /admin/sidekiq/queues/:queue_name | `root_namespace` | string | no | The root namespace of the project | | `subscription_plan` | string | no | The subscription plan of the root namespace (GitLab.com only) | | `caller_id` | string | no | The endpoint or background job that schedule the job (for example: `ProjectsController#create`, `/api/:version/projects/:id`, `PostReceive`) | +| `feature_category` | string | no | The feature category of the background job (for example: `issue_tracking` or `code_review`) | At least one attribute, other than `queue_name`, is required. diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 898aa713331..199b244b2c3 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -9,7 +9,7 @@ Available resources for the [GitLab API](README.md) can be grouped in the follow See also: - [V3 to V4](v3_to_v4.md). -- Adding [deploy keys for multiple projects](deploy_key_multiple_projects.md). +- Adding [deploy keys for multiple projects](deploy_keys.md#adding-deploy-keys-to-multiple-projects). - [API Resources for various templates](#templates-api-resources). ## Project resources @@ -38,6 +38,7 @@ The following API resources are available in the project context: | [Issues Statistics](issues_statistics.md) | `/projects/:id/issues_statistics` (also available for groups and standalone) | | [Issue boards](boards.md) | `/projects/:id/boards` | | [Issue links](issue_links.md) **(STARTER)** | `/projects/:id/issues/.../links` | +| [Iterations](iterations.md) **(STARTER)** | `/projects/:id/iterations` (also available for groups) | | [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | | [Labels](labels.md) | `/projects/:id/labels` | | [Managed licenses](managed_licenses.md) **(ULTIMATE)** | `/projects/:id/managed_licenses` | @@ -80,7 +81,7 @@ The following API resources are available in the project context: | [Vulnerability exports](vulnerability_exports.md) **(ULTIMATE)** | `/projects/:id/vulnerability_exports` | | [Project vulnerabilities](project_vulnerabilities.md) **(ULTIMATE)** | `/projects/:id/vulnerabilities` | | [Vulnerability findings](vulnerability_findings.md) **(ULTIMATE)** | `/projects/:id/vulnerability_findings` | -| [Wikis](wikis.md) | `/projects/:id/wikis` | +| [Project wikis](wikis.md) | `/projects/:id/wikis` | ## Group resources @@ -97,6 +98,7 @@ The following API resources are available in the group context: | [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | | [Group badges](group_badges.md) | `/groups/:id/badges` | | [Group issue boards](group_boards.md) | `/groups/:id/boards` | +| [Group iterations](group_iterations.md) **(STARTER)** | `/groups/:id/iterations` (also available for projects) | | [Group labels](group_labels.md) | `/groups/:id/labels` | | [Group-level variables](group_level_variables.md) | `/groups/:id/variables` | | [Group milestones](group_milestones.md) | `/groups/:id/milestones` | @@ -108,6 +110,7 @@ The following API resources are available in the group context: | [Notification settings](notification_settings.md) | `/groups/:id/notification_settings` (also available for projects and standalone) | | [Resource label events](resource_label_events.md) | `/groups/:id/epics/.../resource_label_events` (also available for projects) | | [Search](search.md) | `/groups/:id/search` (also available for projects and standalone) | +| [Group wikis](group_wikis.md) **(PREMIUM)** | `/groups/:id/wikis` | ## Standalone resources diff --git a/doc/api/commits.md b/doc/api/commits.md index da95e9a943f..66b34d4bc75 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -614,7 +614,7 @@ Example response: ## Commit status -Since GitLab 8.1, this is the new commit status API. +In GitLab 8.1 and later, this is the new commit status API. ### List the statuses of a commit diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index e4687994017..3a7ebf9a2aa 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -23,9 +23,8 @@ GET /projects/:id/registry/repositories | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) accessible by the authenticated user. | -| `tags` | boolean | no | If the parameter is included as true, each repository will include an array of `"tags"` in the response. | -| `name` | string | no | Returns a list of repositories with a name that matches the value. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29763) in GitLab 13.0). | -| `tags_count` | boolean | no | If the parameter is included as true, each repository will include `"tags_count"` in the response ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). | +| `tags` | boolean | no | If the parameter is included as true, each repository includes an array of `"tags"` in the response. | +| `tags_count` | boolean | no | If the parameter is included as true, each repository includes `"tags_count"` in the response ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/registry/repositories" @@ -41,7 +40,8 @@ Example response: "path": "group/project", "project_id": 9, "location": "gitlab.example.com:5000/group/project", - "created_at": "2019-01-10T13:38:57.391Z" + "created_at": "2019-01-10T13:38:57.391Z", + "cleanup_policy_started_at": "2020-01-10T15:40:57.391Z" }, { "id": 2, @@ -49,7 +49,8 @@ Example response: "path": "group/project/releases", "project_id": 9, "location": "gitlab.example.com:5000/group/project/releases", - "created_at": "2019-01-10T13:39:08.229Z" + "created_at": "2019-01-10T13:39:08.229Z", + "cleanup_policy_started_at": "2020-08-17T03:12:35.489Z" } ] ``` @@ -65,9 +66,8 @@ GET /groups/:id/registry/repositories | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) accessible by the authenticated user. | -| `tags` | boolean | no | If the parameter is included as true, each repository will include an array of `"tags"` in the response. | -| `name` | string | no | Returns a list of repositories with a name that matches the value. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29763) in GitLab 13.0). | -| `tags_count` | boolean | no | If the parameter is included as true, each repository will include `"tags_count"` in the response ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). | +| `tags` | boolean | no | If the parameter is included as true, each repository includes an array of `"tags"` in the response. | +| `tags_count` | boolean | no | If the parameter is included as true, each repository includes `"tags_count"` in the response ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32141) in GitLab 13.1). | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/2/registry/repositories?tags=1&tags_count=true" @@ -84,6 +84,7 @@ Example response: "project_id": 9, "location": "gitlab.example.com:5000/group/project", "created_at": "2019-01-10T13:38:57.391Z", + "cleanup_policy_started_at": "2020-08-17T03:12:35.489Z", "tags_count": 1, "tags": [ { @@ -100,6 +101,7 @@ Example response: "project_id": 11, "location": "gitlab.example.com:5000/group/other_project", "created_at": "2019-01-10T13:39:08.229Z", + "cleanup_policy_started_at": "2020-01-10T15:40:57.391Z", "tags_count": 3, "tags": [ { @@ -228,7 +230,7 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" ``` -This action does not delete blobs. In order to delete them and recycle disk space, +This action doesn't delete blobs. To delete them and recycle disk space, [run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests). ## Delete registry repository tags in bulk @@ -248,28 +250,29 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags | `repository_id` | integer | yes | The ID of registry repository. | | `name_regex` | string | no | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to delete. To delete all tags specify `.*`. **Note:** `name_regex` is deprecated in favor of `name_regex_delete`. This field is validated. | | `name_regex_delete` | string | yes | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to delete. To delete all tags specify `.*`. This field is validated. | -| `name_regex_keep` | string | no | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to keep. This value will override any matches from `name_regex_delete`. This field is validated. Note: setting to `.*` will result in a no-op. | +| `name_regex_keep` | string | no | The [re2](https://github.com/google/re2/wiki/Syntax) regex of the name to keep. This value overrides any matches from `name_regex_delete`. This field is validated. Note: setting to `.*` results in a no-op. | | `keep_n` | integer | no | The amount of latest tags of given name to keep. | | `older_than` | string | no | Tags to delete that are older than the given time, written in human readable form `1h`, `1d`, `1month`. | This API call performs the following operations: -1. It orders all tags by creation date. The creation date is the time of the - manifest creation, not the time of tag push. -1. It removes only the tags matching the given `name_regex_delete` (or deprecated `name_regex`), keeping any that match `name_regex_keep`. -1. It never removes the tag named `latest`. -1. It keeps N latest matching tags (if `keep_n` is specified). -1. It only removes tags that are older than X amount of time (if `older_than` is specified). -1. It schedules the asynchronous job to be executed in the background. - -These operations are executed asynchronously and it might -take time to get executed. You can run this at most -once an hour for a given container repository. -This action does not delete blobs. In order to delete them and recycle disk space, +- It orders all tags by creation date. The creation date is the time of the + manifest creation, not the time of tag push. +- It removes only the tags matching the given `name_regex_delete` (or deprecated + `name_regex`), keeping any that match `name_regex_keep`. +- It never removes the tag named `latest`. +- It keeps N latest matching tags (if `keep_n` is specified). +- It only removes tags that are older than X amount of time (if `older_than` is + specified). +- It schedules the asynchronous job to be executed in the background. + +These operations are executed asynchronously and can take time to get executed. +You can run this at most once an hour for a given container repository. This +action doesn't delete blobs. To delete them and recycle disk space, [run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests). NOTE: **Note:** -Since GitLab 12.4, individual tags are deleted. +In GitLab 12.4 and later, individual tags are deleted. For more details, see the [discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/15737). Examples: diff --git a/doc/api/epics.md b/doc/api/epics.md index 91ea92c8589..5c7366c8457 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -267,6 +267,7 @@ POST /groups/:id/epics | `labels` | string | no | The comma separated list of labels | | `description` | string | no | The description of the epic. Limited to 1,048,576 characters. | | `confidential` | boolean | no | Whether the epic should be confidential | +| `created_at` | string | no | When the epic was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5) | | `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (since 11.3) | | `start_date_fixed` | string | no | The fixed start date of an epic (since 11.3) | | `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (since 11.3) | @@ -349,6 +350,7 @@ PUT /groups/:id/epics/:epic_iid | `description` | string | no | The description of an epic. Limited to 1,048,576 characters. | | `confidential` | boolean | no | Whether the epic should be confidential | | `labels` | string | no | The comma separated list of labels | +| `updated_at` | string | no | When the epic was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5) | | `start_date_is_fixed` | boolean | no | Whether start date should be sourced from `start_date_fixed` or from milestones (since 11.3) | | `start_date_fixed` | string | no | The fixed start date of an epic (since 11.3) | | `due_date_is_fixed` | boolean | no | Whether due date should be sourced from `due_date_fixed` or from milestones (since 11.3) | @@ -422,10 +424,10 @@ DELETE /groups/:id/epics/:epic_iid curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/1/epics/5" ``` -## Create a to-do +## Create a to do -Manually creates a to-do for the current user on an epic. If -there already exists a to-do for the user on that epic, status code `304` is +Manually creates a to do for the current user on an epic. If +there already exists a to do for the user on that epic, status code `304` is returned. ```plaintext diff --git a/doc/api/experiments.md b/doc/api/experiments.md new file mode 100644 index 00000000000..66c444e54ce --- /dev/null +++ b/doc/api/experiments.md @@ -0,0 +1,40 @@ +--- +stage: Growth +group: Expansion +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Experiments API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262725) in GitLab 13.5. + +This API is for listing Experiments [experiment use in development of GitLab](../development/experiment_guide/index.md). + +All methods require user be a [GitLab team member](https://gitlab.com/groups/gitlab-com/-/group_members) for authorization. + +## List all experiments + +Get a list of all experiments, with its enabled status. + +```plaintext +GET /experiments +``` + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/experiments" +``` + +Example response: + +```json +[ + { + "key": "experiment_1", + "enabled": true + }, + { + "key": "experiment_2", + "enabled": false + } +] +``` diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index 460f3727819..b44cb1fb9f2 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -4,9 +4,10 @@ group: Progressive Delivery info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Feature flag user lists API **(PREMIUM)** +# Feature flag user lists API **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205409) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205409) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to GitLab Core in 13.5. API for accessing GitLab Feature Flag User Lists. diff --git a/doc/api/feature_flags.md b/doc/api/feature_flags.md index 1088154b599..fbda873f866 100644 --- a/doc/api/feature_flags.md +++ b/doc/api/feature_flags.md @@ -4,9 +4,11 @@ group: Progressive Delivery info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Feature Flags API **(PREMIUM)** +# Feature Flags API **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.5. NOTE: **Note:** This API is behind a [feature flag](../operations/feature_flags.md#enable-or-disable-feature-flag-strategies). @@ -151,7 +153,7 @@ POST /projects/:id/feature_flags | `description` | string | no | The description of the feature flag. | | `active` | boolean | no | The active state of the flag. Defaults to true. [Supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38350) in GitLab 13.3 and later. | | `strategies` | JSON | no | The feature flag [strategies](../operations/feature_flags.md#feature-flag-strategies). | -| `strategies:name` | JSON | no | The strategy name. | +| `strategies:name` | JSON | no | The strategy name. Can be `default`, `gradualRolloutUserId`, `userWithId`, or `gitlabUserList`. In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/36380) and later, can be [`flexibleRollout`](https://unleash.github.io/docs/activation_strategy#flexiblerollout). | | `strategies:parameters` | JSON | no | The strategy parameters. | | `strategies:scopes` | JSON | no | The scopes for the strategy. | | `strategies:scopes:environment_scope` | string | no | The environment spec for the scope. | diff --git a/doc/api/feature_flags_legacy.md b/doc/api/feature_flags_legacy.md index 175261b3a7b..a7c139a02ba 100644 --- a/doc/api/feature_flags_legacy.md +++ b/doc/api/feature_flags_legacy.md @@ -4,9 +4,11 @@ group: Progressive Delivery info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Legacy Feature Flags API **(PREMIUM)** +# Legacy Feature Flags API **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9566) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.5. CAUTION: **Deprecation:** This API is deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). Use [this API](feature_flags.md) instead. diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 8d2052f7373..064bd26ee72 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -1,7 +1,7 @@ # Geo Nodes API **(PREMIUM ONLY)** -In order to interact with Geo node endpoints, you need to authenticate yourself -as an admin. +To interact with Geo node endpoints, you need to authenticate yourself as an +admin. ## Create a new Geo node @@ -460,12 +460,12 @@ Example response: "package_files_registry_count": 10, "package_files_synced_count": 6, "package_files_failed_count": 3, - "terraform_states_count": 10, - "terraform_states_checksummed_count": 10, - "terraform_states_checksum_failed_count": 0, - "terraform_states_registry_count": 10, - "terraform_states_synced_count": 6, - "terraform_states_failed_count": 3 + "terraform_state_versions_count": 10, + "terraform_state_versions_checksummed_count": 10, + "terraform_state_versions_checksum_failed_count": 0, + "terraform_state_versions_registry_count": 10, + "terraform_state_versions_synced_count": 6, + "terraform_state_versions_failed_count": 3, "snippet_repositories_count": 10, "snippet_repositories_checksummed_count": 10, "snippet_repositories_checksum_failed_count": 0, diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql index 7f5ff04bcee..a44f8f70311 100644 --- a/doc/api/graphql/reference/gitlab_schema.graphql +++ b/doc/api/graphql/reference/gitlab_schema.graphql @@ -32,7 +32,7 @@ input AddAwardEmojiInput { """ The global id of the awardable resource """ - awardableId: ID! + awardableId: AwardableID! """ A unique identifier for the client performing the mutation. @@ -77,7 +77,7 @@ input AddProjectToSecurityDashboardInput { """ ID of the project to be added to Instance Security Dashboard """ - id: ID! + id: ProjectID! } """ @@ -114,6 +114,11 @@ input AdminSidekiqQueuesDeleteJobsInput { """ clientMutationId: String + """ + Delete jobs matching feature_category in the context metadata + """ + featureCategory: String + """ Delete jobs matching project in the context metadata """ @@ -244,6 +249,11 @@ type AlertManagementAlert implements Noteable { """ endedAt: Time + """ + Environment for the alert + """ + environment: Environment + """ Number of events of this alert """ @@ -434,6 +444,16 @@ type AlertManagementAlertEdge { Values for sorting alerts """ enum AlertManagementAlertSort { + """ + Created at ascending order + """ + CREATED_ASC + + """ + Created at descending order + """ + CREATED_DESC + """ Created time by ascending order """ @@ -494,6 +514,16 @@ enum AlertManagementAlertSort { """ STATUS_DESC + """ + Updated at ascending order + """ + UPDATED_ASC + + """ + Updated at descending order + """ + UPDATED_DESC + """ Created time by ascending order """ @@ -507,22 +537,22 @@ enum AlertManagementAlertSort { """ Created at ascending order """ - created_asc + created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5") """ Created at descending order """ - created_desc + created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5") """ Updated at ascending order """ - updated_asc + updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5") """ Updated at descending order """ - updated_desc + updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5") } """ @@ -772,7 +802,7 @@ input AwardEmojiAddInput { """ The global id of the awardable resource """ - awardableId: ID! + awardableId: AwardableID! """ A unique identifier for the client performing the mutation. @@ -812,7 +842,7 @@ input AwardEmojiRemoveInput { """ The global id of the awardable resource """ - awardableId: ID! + awardableId: AwardableID! """ A unique identifier for the client performing the mutation. @@ -852,7 +882,7 @@ input AwardEmojiToggleInput { """ The global id of the awardable resource """ - awardableId: ID! + awardableId: AwardableID! """ A unique identifier for the client performing the mutation. @@ -890,6 +920,11 @@ type AwardEmojiTogglePayload { toggledOn: Boolean! } +""" +Identifier of Awardable +""" +scalar AwardableID + type BaseService implements Service { """ Indicates if the service is active @@ -1035,7 +1070,7 @@ type Board { Returns the last _n_ elements from the list. """ last: Int - ): EpicConnection + ): BoardEpicConnection """ Whether or not backlog list is hidden. @@ -1052,6 +1087,31 @@ type Board { """ id: ID! + """ + Labels of the board + """ + labels( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): LabelConnection + """ Lists of the board """ @@ -1076,6 +1136,11 @@ type Board { """ id: ID + """ + Filters applied when getting issue metadata in the board list + """ + issueFilters: BoardIssueInput + """ Returns the last _n_ elements from the list. """ @@ -1134,90 +1199,166 @@ type BoardEdge { } """ -Identifier of Board +Represents an epic on an issue board """ -scalar BoardID - -input BoardIssueInput { +type BoardEpic implements CurrentUserTodos & Noteable { """ - Filter by assignee username + Author of the epic """ - assigneeUsername: [String] + author: User! """ - Filter by author username + Children (sub-epics) of the epic """ - authorUsername: String + children( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String - """ - Filter by epic ID. Incompatible with epicWildcardId - """ - epicId: ID + """ + Filter epics by author + """ + authorUsername: String - """ - Filter by epic ID wildcard. Incompatible with epicId - """ - epicWildcardId: EpicWildcardId + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String - """ - Filter by label name - """ - labelName: [String] + """ + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use timeframe.end + """ + endDate: Time - """ - Filter by milestone title - """ - milestoneTitle: String + """ + Returns the first _n_ elements from the list. + """ + first: Int - """ - Filter by reaction emoji - """ - myReactionEmoji: String + """ + IID of the epic, e.g., "1" + """ + iid: ID + + """ + Filter epics by iid for autocomplete + """ + iidStartsWith: String + + """ + List of IIDs of epics, e.g., [1, 2] + """ + iids: [ID!] + + """ + Filter epics by labels + """ + labelName: [String!] + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Filter epics by milestone title, computed from epic's issues + """ + milestoneTitle: String + + """ + Search query for epic title or description + """ + search: String + + """ + List epics by sort order + """ + sort: EpicSort + + """ + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use + timeframe.start + """ + startDate: Time + + """ + Filter epics by state + """ + state: EpicState + + """ + List items overlapping the given timeframe + """ + timeframe: Timeframe + ): EpicConnection """ - List of negated params. Warning: this argument is experimental and a subject to change in future + Timestamp of when the epic was closed """ - not: NegatedBoardIssueInput + closedAt: Time """ - Filter by release tag + Indicates if the epic is confidential """ - releaseTag: String + confidential: Boolean """ - Search query for issue title or description + Timestamp of when the epic was created """ - search: String + createdAt: Time """ - Filter by weight + Todos for the current user """ - weight: String -} + currentUserTodos( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + State of the todos + """ + state: TodoStateEnum + ): TodoConnection! -""" -Represents a list for an issue board -""" -type BoardList { """ - Assignee in the list + Number of open and closed descendant epics and issues """ - assignee: User + descendantCounts: EpicDescendantCount """ - Indicates if list is collapsed for this user + Total weight of open and closed issues in the epic and its descendants """ - collapsed: Boolean + descendantWeightSum: EpicDescendantWeights """ - ID (global ID) of the list + Description of the epic """ - id: ID! + description: String """ - Board issues + All discussions on this noteable """ - issues( + discussions( """ Returns the elements in the list that come after the specified cursor. """ @@ -1228,11 +1369,6 @@ type BoardList { """ before: String - """ - Filters applied when selecting issues in the board list - """ - filters: BoardIssueInput - """ Returns the first _n_ elements from the list. """ @@ -1242,47 +1378,454 @@ type BoardList { Returns the last _n_ elements from the list. """ last: Int - ): IssueConnection + ): DiscussionConnection! """ - Count of issues in the list + Number of downvotes the epic has received """ - issuesCount: Int + downvotes: Int! """ - Label of the list + Due date of the epic """ - label: Label + dueDate: Time """ - The current limit metric for the list + Fixed due date of the epic """ - limitMetric: ListLimitMetric + dueDateFixed: Time """ - Type of the list + Inherited due date of the epic from milestones """ - listType: String! + dueDateFromMilestones: Time """ - Maximum number of issues in the list + Indicates if the due date has been manually set """ - maxIssueCount: Int + dueDateIsFixed: Boolean """ - Maximum weight of issues in the list + Group to which the epic belongs """ - maxIssueWeight: Int + group: Group! """ - Milestone of the list + Indicates if the epic has children """ - milestone: Milestone + hasChildren: Boolean! """ - Position of list within the board + Indicates if the epic has direct issues """ - position: Int + hasIssues: Boolean! + + """ + Indicates if the epic has a parent epic + """ + hasParent: Boolean! + + """ + Current health status of the epic + """ + healthStatus: EpicHealthStatus + + """ + ID of the epic + """ + id: ID! + + """ + Internal ID of the epic + """ + iid: ID! + + """ + A list of issues associated with the epic + """ + issues( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): EpicIssueConnection + + """ + Labels assigned to the epic + """ + labels( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): LabelConnection + + """ + All notes on this noteable + """ + notes( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): NoteConnection! + + """ + Parent epic of the epic + """ + parent: Epic + + """ + List of participants for the epic + """ + participants( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): UserConnection + + """ + Internal reference of the epic. Returned in shortened format by default + """ + reference( + """ + Indicates if the reference should be returned in full + """ + full: Boolean = false + ): String! + + """ + URI path of the epic-issue relationship + """ + relationPath: String + + """ + The relative position of the epic in the epic tree + """ + relativePosition: Int + + """ + Start date of the epic + """ + startDate: Time + + """ + Fixed start date of the epic + """ + startDateFixed: Time + + """ + Inherited start date of the epic from milestones + """ + startDateFromMilestones: Time + + """ + Indicates if the start date has been manually set + """ + startDateIsFixed: Boolean + + """ + State of the epic + """ + state: EpicState! + + """ + Indicates the currently logged in user is subscribed to the epic + """ + subscribed: Boolean! + + """ + Title of the epic + """ + title: String + + """ + Timestamp of when the epic was updated + """ + updatedAt: Time + + """ + Number of upvotes the epic has received + """ + upvotes: Int! + + """ + Permissions for the current user on the resource + """ + userPermissions: EpicPermissions! + + """ + User preferences for the epic on the issue board + """ + userPreferences: BoardEpicUserPreferences + + """ + Web path of the epic + """ + webPath: String! + + """ + Web URL of the epic + """ + webUrl: String! +} + +""" +The connection type for BoardEpic. +""" +type BoardEpicConnection { + """ + A list of edges. + """ + edges: [BoardEpicEdge] + + """ + A list of nodes. + """ + nodes: [BoardEpic] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type BoardEpicEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: BoardEpic +} + +""" +Represents user preferences for a board epic +""" +type BoardEpicUserPreferences { + """ + Indicates epic should be displayed as collapsed + """ + collapsed: Boolean! +} + +""" +Identifier of Board +""" +scalar BoardID + +input BoardIssueInput { + """ + Filter by assignee username + """ + assigneeUsername: [String] + + """ + Filter by author username + """ + authorUsername: String + + """ + Filter by epic ID. Incompatible with epicWildcardId + """ + epicId: ID + + """ + Filter by epic ID wildcard. Incompatible with epicId + """ + epicWildcardId: EpicWildcardId + + """ + Filter by label name + """ + labelName: [String] + + """ + Filter by milestone title + """ + milestoneTitle: String + + """ + Filter by reaction emoji + """ + myReactionEmoji: String + + """ + List of negated params. Warning: this argument is experimental and a subject to change in future + """ + not: NegatedBoardIssueInput + + """ + Filter by release tag + """ + releaseTag: String + + """ + Search query for issue title or description + """ + search: String + + """ + Filter by weight + """ + weight: String +} + +""" +Represents a list for an issue board +""" +type BoardList { + """ + Assignee in the list + """ + assignee: User + + """ + Indicates if list is collapsed for this user + """ + collapsed: Boolean + + """ + ID (global ID) of the list + """ + id: ID! + + """ + Board issues + """ + issues( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Filters applied when selecting issues in the board list + """ + filters: BoardIssueInput + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): IssueConnection + + """ + Count of issues in the list + """ + issuesCount: Int + + """ + Label of the list + """ + label: Label + + """ + The current limit metric for the list + """ + limitMetric: ListLimitMetric + + """ + Type of the list + """ + listType: String! + + """ + Maximum number of issues in the list + """ + maxIssueCount: Int + + """ + Maximum weight of issues in the list + """ + maxIssueWeight: Int + + """ + Milestone of the list + """ + milestone: Milestone + + """ + Position of list within the board + """ + position: Int """ Title of the list @@ -1402,7 +1945,7 @@ input BoardListUpdateLimitMetricsInput { """ The global ID of the list. """ - listId: ID! + listId: ListID! """ The new maximum issue count limit. @@ -1478,6 +2021,11 @@ type BurnupChartDailyTotals { } type CiGroup { + """ + Detailed status of the group + """ + detailedStatus: DetailedStatus + """ Jobs in group """ @@ -1550,6 +2098,11 @@ type CiGroupEdge { } type CiJob { + """ + Detailed status of the job + """ + detailedStatus: DetailedStatus + """ Name of the job """ @@ -1579,6 +2132,11 @@ type CiJob { """ last: Int ): CiJobConnection + + """ + Schedule for the build + """ + scheduledAt: Time } """ @@ -1622,6 +2180,11 @@ Identifier of Ci::Pipeline scalar CiPipelineID type CiStage { + """ + Detailed status of the stage + """ + detailedStatus: DetailedStatus + """ Group of jobs for the stage """ @@ -1937,6 +2500,11 @@ Identifier of Clusters::AgentToken """ scalar ClustersAgentTokenID +""" +Identifier of Clusters::Cluster +""" +scalar ClustersClusterID + type Commit { """ Author of the commit @@ -2431,22 +2999,92 @@ input CreateAlertIssueInput { """ The iid of the alert to mutate """ - iid: String! + iid: String! + + """ + The project the alert to mutate is in + """ + projectPath: ID! +} + +""" +Autogenerated return type of CreateAlertIssue +""" +type CreateAlertIssuePayload { + """ + The alert after mutation + """ + alert: AlertManagementAlert + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The issue created after mutation + """ + issue: Issue + + """ + The todo after mutation + """ + todo: Todo +} + +""" +Autogenerated input type of CreateAnnotation +""" +input CreateAnnotationInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The global id of the cluster to add an annotation to + """ + clusterId: ClustersClusterID + + """ + The path to a file defining the dashboard on which the annotation should be added + """ + dashboardPath: String! + + """ + The description of the annotation + """ + description: String! + + """ + Timestamp indicating ending moment to which the annotation relates + """ + endingAt: Time + + """ + The global id of the environment to add an annotation to + """ + environmentId: EnvironmentID """ - The project the alert to mutate is in + Timestamp indicating starting moment to which the annotation relates """ - projectPath: ID! + startingAt: Time! } """ -Autogenerated return type of CreateAlertIssue +Autogenerated return type of CreateAnnotation """ -type CreateAlertIssuePayload { +type CreateAnnotationPayload { """ - The alert after mutation + The created annotation """ - alert: AlertManagementAlert + annotation: MetricsDashboardAnnotation """ A unique identifier for the client performing the mutation. @@ -2457,66 +3095,61 @@ type CreateAlertIssuePayload { Errors encountered during execution of the mutation. """ errors: [String!]! - - """ - The issue created after mutation - """ - issue: Issue - - """ - The todo after mutation - """ - todo: Todo } """ -Autogenerated input type of CreateAnnotation +Autogenerated input type of CreateBoard """ -input CreateAnnotationInput { +input CreateBoardInput { + """ + The ID of the user to be assigned to the board. + """ + assigneeId: String + """ A unique identifier for the client performing the mutation. """ clientMutationId: String """ - The global id of the cluster to add an annotation to + The group full path the board is associated with. """ - clusterId: ID + groupPath: ID """ - The path to a file defining the dashboard on which the annotation should be added + The IDs of labels to be added to the board. """ - dashboardPath: String! + labelIds: [ID!] """ - The description of the annotation + The ID of the milestone to be assigned to the board. """ - description: String! + milestoneId: ID """ - Timestamp indicating ending moment to which the annotation relates + The board name. """ - endingAt: Time + name: String """ - The global id of the environment to add an annotation to + The project full path the board is associated with. """ - environmentId: ID + projectPath: ID """ - Timestamp indicating starting moment to which the annotation relates + The weight of the board. """ - startingAt: Time! + weight: Boolean } """ -Autogenerated return type of CreateAnnotation +Autogenerated return type of CreateBoard """ -type CreateAnnotationPayload { +type CreateBoardPayload { """ - The created annotation + The board after mutation. """ - annotation: MetricsDashboardAnnotation + board: Board """ A unique identifier for the client performing the mutation. @@ -2636,7 +3269,7 @@ input CreateDiffNoteInput { """ The global id of the resource to add a note to """ - noteableId: ID! + noteableId: NoteableID! """ The position of this note on a diff @@ -2766,7 +3399,7 @@ input CreateImageDiffNoteInput { """ The global id of the resource to add a note to """ - noteableId: ID! + noteableId: NoteableID! """ The position of this note on a diff @@ -2794,6 +3427,121 @@ type CreateImageDiffNotePayload { note: Note } +""" +Autogenerated input type of CreateIssue +""" +input CreateIssueInput { + """ + The array of user IDs to assign to the issue + """ + assigneeIds: [UserID!] + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Indicates the issue is confidential + """ + confidential: Boolean + + """ + Timestamp when the issue was created. Available only for admins and project owners + """ + createdAt: Time + + """ + Description of the issue + """ + description: String + + """ + The ID of a discussion to resolve. Also pass `merge_request_to_resolve_discussions_of` + """ + discussionToResolve: String + + """ + Due date of the issue + """ + dueDate: ISO8601Date + + """ + The ID of an epic to associate the issue with + """ + epicId: EpicID + + """ + The desired health status + """ + healthStatus: HealthStatus + + """ + The IID (internal ID) of a project issue. Only admins and project owners can modify + """ + iid: Int + + """ + The IDs of labels to be added to the issue + """ + labelIds: [LabelID!] + + """ + Labels of the issue + """ + labels: [String!] + + """ + Indicates discussion is locked on the issue + """ + locked: Boolean + + """ + The IID of a merge request for which to resolve discussions + """ + mergeRequestToResolveDiscussionsOf: MergeRequestID + + """ + The ID of the milestone to assign to the issue. On update milestone will be removed if set to null + """ + milestoneId: MilestoneID + + """ + Project full path the issue is associated with + """ + projectPath: ID! + + """ + Title of the issue + """ + title: String! + + """ + The weight of the issue + """ + weight: Int +} + +""" +Autogenerated return type of CreateIssue +""" +type CreateIssuePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The issue after mutation + """ + issue: Issue +} + """ Autogenerated input type of CreateIteration """ @@ -2876,12 +3624,12 @@ input CreateNoteInput { """ The global id of the discussion this note is in reply to """ - discussionId: ID + discussionId: DiscussionID """ The global id of the resource to add a note to """ - noteableId: ID! + noteableId: NoteableID! } """ @@ -2914,14 +3662,19 @@ input CreateRequirementInput { clientMutationId: String """ - The project full path the requirement is associated with + Description of the requirement + """ + description: String + + """ + Full project path the requirement is associated with """ projectPath: ID! """ Title of the requirement """ - title: String! + title: String } """ @@ -2939,7 +3692,7 @@ type CreateRequirementPayload { errors: [String!]! """ - The requirement after mutation + Requirement after mutation """ requirement: Requirement } @@ -3002,6 +3755,11 @@ type CreateSnippetPayload { The snippet after mutation """ snippet: Snippet + + """ + Indicates whether the operation returns a record detected as spam + """ + spam: Boolean } """ @@ -3132,6 +3890,11 @@ type DastOnDemandScanCreatePayload { } enum DastScanTypeEnum { + """ + Active DAST scan. This scan will make active attacks against the target site. + """ + ACTIVE + """ Passive DAST scan. This scan will not make active attacks against the target site. """ @@ -3162,6 +3925,16 @@ type DastScannerProfile { """ profileName: String + """ + Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. + """ + scanType: DastScanTypeEnum + + """ + Indicates if debug messages should be included in DAST console output. True to include the debug messages. + """ + showDebugMessages: Boolean! + """ The maximum number of minutes allowed for the spider to traverse the site """ @@ -3171,6 +3944,13 @@ type DastScannerProfile { The maximum number of seconds allowed for the site under test to respond to a request """ targetTimeout: Int + + """ + Indicates if the AJAX spider should be used to crawl the target site. True to + run the AJAX spider in addition to the traditional spider, and false to run + only the traditional spider. + """ + useAjaxSpider: Boolean! } """ @@ -3212,6 +3992,16 @@ input DastScannerProfileCreateInput { """ profileName: String! + """ + Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. + """ + scanType: DastScanTypeEnum = PASSIVE + + """ + Indicates if debug messages should be included in DAST console output. True to include the debug messages. + """ + showDebugMessages: Boolean = false + """ The maximum number of minutes allowed for the spider to traverse the site. """ @@ -3221,6 +4011,13 @@ input DastScannerProfileCreateInput { The maximum number of seconds allowed for the site under test to respond to a request. """ targetTimeout: Int + + """ + Indicates if the AJAX spider should be used to crawl the target site. True to + run the AJAX spider in addition to the traditional spider, and false to run + only the traditional spider. + """ + useAjaxSpider: Boolean = false } """ @@ -3327,6 +4124,16 @@ input DastScannerProfileUpdateInput { """ profileName: String! + """ + Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. + """ + scanType: DastScanTypeEnum + + """ + Indicates if debug messages should be included in DAST console output. True to include the debug messages. + """ + showDebugMessages: Boolean + """ The maximum number of minutes allowed for the spider to traverse the site. """ @@ -3336,6 +4143,13 @@ input DastScannerProfileUpdateInput { The maximum number of seconds allowed for the site under test to respond to a request. """ targetTimeout: Int! + + """ + Indicates if the AJAX spider should be used to crawl the target site. True to + run the AJAX spider in addition to the traditional spider, and false to run + only the traditional spider. + """ + useAjaxSpider: Boolean } """ @@ -3524,39 +4338,101 @@ type DastSiteProfilePermissions { } """ -Autogenerated input type of DastSiteProfileUpdate +Autogenerated input type of DastSiteProfileUpdate +""" +input DastSiteProfileUpdateInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The project the site profile belongs to. + """ + fullPath: ID! + + """ + ID of the site profile to be updated. + """ + id: DastSiteProfileID! + + """ + The name of the site profile. + """ + profileName: String! + + """ + The URL of the target to be scanned. + """ + targetUrl: String +} + +""" +Autogenerated return type of DastSiteProfileUpdate +""" +type DastSiteProfileUpdatePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + ID of the site profile. + """ + id: DastSiteProfileID +} + +enum DastSiteProfileValidationStatusEnum { + """ + Site validation process finished but failed + """ + FAILED_VALIDATION + + """ + Site validation process is in progress + """ + INPROGRESS_VALIDATION + + """ + Site validation process finished successfully + """ + PASSED_VALIDATION + + """ + Site validation process has not started + """ + PENDING_VALIDATION +} + +""" +Autogenerated input type of DastSiteTokenCreate """ -input DastSiteProfileUpdateInput { +input DastSiteTokenCreateInput { """ A unique identifier for the client performing the mutation. """ clientMutationId: String """ - The project the site profile belongs to. + The project the site token belongs to. """ fullPath: ID! """ - ID of the site profile to be updated. - """ - id: DastSiteProfileID! - - """ - The name of the site profile. - """ - profileName: String! - - """ - The URL of the target to be scanned. + The URL of the target to be validated. """ targetUrl: String } """ -Autogenerated return type of DastSiteProfileUpdate +Autogenerated return type of DastSiteTokenCreate """ -type DastSiteProfileUpdatePayload { +type DastSiteTokenCreatePayload { """ A unique identifier for the client performing the mutation. """ @@ -3568,32 +4444,30 @@ type DastSiteProfileUpdatePayload { errors: [String!]! """ - ID of the site profile. + ID of the site token. """ - id: DastSiteProfileID -} + id: DastSiteTokenID -enum DastSiteProfileValidationStatusEnum { """ - Site validation process finished but failed + The current validation status of the target. """ - FAILED_VALIDATION + status: DastSiteProfileValidationStatusEnum """ - Site validation process is in progress + Token string. """ - INPROGRESS_VALIDATION + token: String +} - """ - Site validation process finished successfully - """ - PASSED_VALIDATION +""" +Identifier of DastSiteToken +""" +scalar DastSiteTokenID - """ - Site validation process has not started - """ - PENDING_VALIDATION -} +""" +Date represented in ISO 8601 +""" +scalar Date """ Autogenerated input type of DeleteAnnotation @@ -3919,6 +4793,11 @@ type DesignAtVersionEdge { A collection of designs """ type DesignCollection { + """ + Copy state of the design collection + """ + copyState: DesignCollectionCopyState + """ Find a specific design """ @@ -4046,6 +4925,26 @@ type DesignCollection { ): DesignVersionConnection! } +""" +Copy state of a DesignCollection +""" +enum DesignCollectionCopyState { + """ + The DesignCollection encountered an error during a copy + """ + ERROR + + """ + The DesignCollection is being copied + """ + IN_PROGRESS + + """ + The DesignCollection has no copy in progress + """ + READY +} + """ The connection type for Design. """ @@ -4470,6 +5369,41 @@ input DestroyBoardInput { id: BoardID! } +""" +Autogenerated input type of DestroyBoardList +""" +input DestroyBoardListInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Global ID of the list to destroy. Only label lists are accepted. + """ + listId: ListID! +} + +""" +Autogenerated return type of DestroyBoardList +""" +type DestroyBoardListPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The list after mutation. + """ + list: BoardList +} + """ Autogenerated return type of DestroyBoard """ @@ -4502,7 +5436,7 @@ input DestroyNoteInput { """ The global id of the note to destroy """ - id: ID! + id: NoteID! } """ @@ -4562,44 +5496,49 @@ type DestroySnippetPayload { type DetailedStatus { """ - Path of the details for the pipeline status + Action information for the status. This includes method, button title, icon, path, and title + """ + action: StatusAction + + """ + Path of the details for the status """ - detailsPath: String! + detailsPath: String """ - Favicon of the pipeline status + Favicon of the status """ - favicon: String! + favicon: String """ - Group of the pipeline status + Group of the status """ - group: String! + group: String """ - Indicates if the pipeline status has further details + Indicates if the status has further details """ - hasDetails: Boolean! + hasDetails: Boolean """ - Icon of the pipeline status + Icon of the status """ - icon: String! + icon: String """ - Label of the pipeline status + Label of the status """ - label: String! + label: String """ - Text of the pipeline status + Text of the status """ - text: String! + text: String """ - Tooltip associated with the pipeline status + Tooltip associated with the status """ - tooltip: String! + tooltip: String } input DiffImagePositionInput { @@ -4914,6 +5853,11 @@ type DiscussionEdge { node: Discussion } +""" +Identifier of Discussion +""" +scalar DiscussionID + """ Autogenerated input type of DiscussionToggleResolve """ @@ -4926,7 +5870,7 @@ input DiscussionToggleResolveInput { """ The global id of the discussion """ - id: ID! + id: DiscussionID! """ Will resolve the discussion when true, and unresolve the discussion when false @@ -4971,7 +5915,7 @@ input DismissVulnerabilityInput { """ ID of the vulnerability to be dismissed """ - id: ID! + id: VulnerabilityID! } """ @@ -5045,7 +5989,7 @@ type Environment { id: ID! """ - The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. + The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned """ latestOpenedMostSevereAlert: AlertManagementAlert @@ -5064,6 +6008,12 @@ type Environment { """ name: String! + """ + The path to the environment. Will always return null if + `expose_environment_path_in_alert_details` feature flag is disabled + """ + path: String + """ State of the environment, for example: available/stopped """ @@ -5105,6 +6055,11 @@ type EnvironmentEdge { node: Environment } +""" +Identifier of Environment +""" +scalar EnvironmentID + """ Represents an epic """ @@ -5134,8 +6089,8 @@ type Epic implements CurrentUserTodos & Noteable { before: String """ - List items within a time frame where items.end_date is between startDate and - endDate parameters (startDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use timeframe.end """ endDate: Time @@ -5185,8 +6140,9 @@ type Epic implements CurrentUserTodos & Noteable { sort: EpicSort """ - List items within a time frame where items.start_date is between startDate - and endDate parameters (endDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use + timeframe.start """ startDate: Time @@ -5194,10 +6150,15 @@ type Epic implements CurrentUserTodos & Noteable { Filter epics by state """ state: EpicState + + """ + List items overlapping the given timeframe + """ + timeframe: Timeframe ): EpicConnection """ - Timestamp of the epic's closure + Timestamp of when the epic was closed """ closedAt: Time @@ -5207,7 +6168,7 @@ type Epic implements CurrentUserTodos & Noteable { confidential: Boolean """ - Timestamp of the epic's creation + Timestamp of when the epic was created """ createdAt: Time @@ -5502,7 +6463,7 @@ type Epic implements CurrentUserTodos & Noteable { title: String """ - Timestamp of the epic's last activity + Timestamp of when the epic was updated """ updatedAt: Time @@ -5966,6 +6927,11 @@ type EpicIssue implements CurrentUserTodos & Noteable { """ severity: IssuableSeverity + """ + Timestamp of when the issue SLA expires. + """ + slaDueAt: Time + """ State of the issue """ @@ -6233,17 +7199,17 @@ input EpicTreeNodeFieldsInputType { """ The id of the epic_issue or issue that the actual epic or issue is switched with """ - adjacentReferenceId: ID + adjacentReferenceId: EpicTreeSortingID """ The id of the epic_issue or epic that is being moved """ - id: ID! + id: EpicTreeSortingID! """ ID of the new parent epic """ - newParentId: ID + newParentId: EpicID """ The type of the switch, after or before allowed @@ -6258,7 +7224,7 @@ input EpicTreeReorderInput { """ The id of the base epic of the tree """ - baseEpicId: ID! + baseEpicId: EpicID! """ A unique identifier for the client performing the mutation. @@ -6286,6 +7252,11 @@ type EpicTreeReorderPayload { errors: [String!]! } +""" +Identifier of EpicTreeSorting +""" +scalar EpicTreeSortingID + """ Epic ID wildcard values """ @@ -6327,6 +7298,36 @@ type GeoNode { """ internalUrl: String + """ + Find merge request diff registries on this Geo node + """ + mergeRequestDiffRegistries( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Filters registries by their ID + """ + ids: [ID!] + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): MergeRequestDiffRegistryConnection + """ The interval (in days) in which the repository verification is valid. Once expired, it will be reverified """ @@ -6418,10 +7419,9 @@ type GeoNode { syncObjectStorage: Boolean """ - Find terraform state registries on this Geo node. Available only when feature - flag `geo_terraform_state_replication` is enabled + Find terraform state version registries on this Geo node """ - terraformStateRegistries( + terraformStateVersionRegistries( """ Returns the elements in the list that come after the specified cursor. """ @@ -6446,7 +7446,7 @@ type GeoNode { Returns the last _n_ elements from the list. """ last: Int - ): TerraformStateRegistryConnection + ): TerraformStateVersionRegistryConnection """ The user-facing URL for this Geo node @@ -6492,6 +7492,16 @@ type GrafanaIntegration { } type Group { + """ + Size limit for repositories in the namespace in bytes + """ + actualRepositorySizeLimit: Float + + """ + Additional storage purchased for the root namespace in bytes + """ + additionalPurchasedStorageSize: Float + """ Indicates whether Auto DevOps is enabled for all projects within this group """ @@ -6507,9 +7517,9 @@ type Group { """ board( """ - Find a board by its ID + The board's ID """ - id: ID + id: BoardID! ): Board """ @@ -6542,6 +7552,11 @@ type Group { last: Int ): BoardConnection + """ + Includes at least one project where the repository size exceeds the limit + """ + containsLockedProjects: Boolean! + """ Description of the namespace """ @@ -6567,8 +7582,8 @@ type Group { authorUsername: String """ - List items within a time frame where items.end_date is between startDate and - endDate parameters (startDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use timeframe.end """ endDate: Time @@ -6608,8 +7623,9 @@ type Group { sort: EpicSort """ - List items within a time frame where items.start_date is between startDate - and endDate parameters (endDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use + timeframe.start """ startDate: Time @@ -6617,6 +7633,11 @@ type Group { Filter epics by state """ state: EpicState + + """ + List items overlapping the given timeframe + """ + timeframe: Timeframe ): Epic """ @@ -6639,8 +7660,8 @@ type Group { before: String """ - List items within a time frame where items.end_date is between startDate and - endDate parameters (startDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use timeframe.end """ endDate: Time @@ -6690,8 +7711,9 @@ type Group { sort: EpicSort """ - List items within a time frame where items.start_date is between startDate - and endDate parameters (endDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use + timeframe.start """ startDate: Time @@ -6699,6 +7721,11 @@ type Group { Filter epics by state """ state: EpicState + + """ + List items overlapping the given timeframe + """ + timeframe: Timeframe ): EpicConnection """ @@ -6762,7 +7789,7 @@ type Group { isTemporaryStorageIncreaseEnabled: Boolean! """ - Issues of the group + Issues for projects in this group """ issues( """ @@ -6780,6 +7807,16 @@ type Group { """ assigneeUsername: String + """ + Usernames of users assigned to the issue + """ + assigneeUsernames: [String!] + + """ + Username of the author of the issue + """ + authorUsername: String + """ Returns the elements in the list that come before the specified cursor. """ @@ -6821,7 +7858,7 @@ type Group { iids: [String!] """ - Include issues belonging to subgroups. + Include issues belonging to subgroups """ includeSubgroups: Boolean = false @@ -6891,8 +7928,8 @@ type Group { before: String """ - List items within a time frame where items.end_date is between startDate and - endDate parameters (startDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use timeframe.end """ endDate: Time @@ -6922,8 +7959,9 @@ type Group { last: Int """ - List items within a time frame where items.start_date is between startDate - and endDate parameters (endDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use + timeframe.start """ startDate: Time @@ -6932,6 +7970,11 @@ type Group { """ state: IterationState + """ + List items overlapping the given timeframe + """ + timeframe: Timeframe + """ Fuzzy search by title """ @@ -6963,30 +8006,115 @@ type Group { before: String """ - Returns the first _n_ elements from the list. + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + A search term to find labels with + """ + searchTerm: String + ): LabelConnection + + """ + Indicates if Large File Storage (LFS) is enabled for namespace + """ + lfsEnabled: Boolean + + """ + Indicates if a group is disabled from getting mentioned + """ + mentionsDisabled: Boolean + + """ + Merge requests for projects in this group + """ + mergeRequests( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Username of the assignee + """ + assigneeUsername: String + + """ + Username of the author + """ + authorUsername: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Array of IIDs of merge requests, for example `[1, 2]` + """ + iids: [String!] + + """ + Include merge requests belonging to subgroups + """ + includeSubgroups: Boolean = false + + """ + Array of label names. All resolved merge requests will have all of these labels. + """ + labels: [String!] + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Merge requests merged after this date + """ + mergedAfter: Time + + """ + Merge requests merged before this date + """ + mergedBefore: Time + + """ + Title of the milestone + """ + milestoneTitle: String + + """ + Sort merge requests by this criteria + """ + sort: MergeRequestSort = created_desc + + """ + Array of source branch names. All resolved merge requests will have one of these branches as their source. """ - first: Int + sourceBranches: [String!] """ - Returns the last _n_ elements from the list. + A merge request state. If provided, all resolved merge requests will have this state. """ - last: Int + state: MergeRequestState """ - A search term to find labels with + Array of target branch names. All resolved merge requests will have one of these branches as their target. """ - searchTerm: String - ): LabelConnection - - """ - Indicates if Large File Storage (LFS) is enabled for namespace - """ - lfsEnabled: Boolean - - """ - Indicates if a group is disabled from getting mentioned - """ - mentionsDisabled: Boolean + targetBranches: [String!] + ): MergeRequestConnection """ Milestones of the group @@ -7003,8 +8131,13 @@ type Group { before: String """ - List items within a time frame where items.end_date is between startDate and - endDate parameters (startDate parameter must be present) + A date that the milestone contains + """ + containingDate: Time + + """ + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use timeframe.end """ endDate: Time @@ -7029,8 +8162,14 @@ type Group { last: Int """ - List items within a time frame where items.start_date is between startDate - and endDate parameters (endDate parameter must be present) + A search string for the title + """ + searchTitle: String + + """ + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use + timeframe.start """ startDate: Time @@ -7038,6 +8177,16 @@ type Group { Filter milestones by state """ state: MilestoneStateEnum + + """ + List items overlapping the given timeframe + """ + timeframe: Timeframe + + """ + The title of the milestone + """ + title: String ): MilestoneConnection """ @@ -7105,6 +8254,11 @@ type Group { sort: NamespaceProjectSort = null ): ProjectConnection! + """ + Number of projects in the root namespace where the repository size exceeds the limit + """ + repositorySizeExcessProjectCount: Int! + """ Indicates if users can request access to namespace """ @@ -7185,6 +8339,16 @@ type Group { startTime: Time ): TimelogConnection! + """ + Total repository size of all projects in the root namespace in bytes + """ + totalRepositorySize: Float + + """ + Total excess repository size of all projects in the root namespace in bytes + """ + totalRepositorySizeExcess: Float + """ Time before two-factor authentication is enforced """ @@ -7961,6 +9125,11 @@ type Issue implements CurrentUserTodos & Noteable { """ severity: IssuableSeverity + """ + Timestamp of when the issue SLA expires. + """ + slaDueAt: Time + """ State of the issue """ @@ -8087,6 +9256,31 @@ Identifier of Issue """ scalar IssueID +""" +Autogenerated input type of IssueMove +""" +input IssueMoveInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The IID of the issue to mutate + """ + iid: String! + + """ + The project the issue to mutate is in + """ + projectPath: ID! + + """ + The project to move the issue to + """ + targetProjectPath: ID! +} + """ Autogenerated input type of IssueMoveList """ @@ -8157,6 +9351,26 @@ type IssueMoveListPayload { issue: Issue } +""" +Autogenerated return type of IssueMove +""" +type IssueMovePayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The issue after mutation + """ + issue: Issue +} + """ Check permissions for the current user on a issue """ @@ -8404,7 +9618,7 @@ input IssueSetIterationInput { """ The iteration to assign to the issue. """ - iterationId: ID + iterationId: IterationID """ The project the issue to mutate is in @@ -8616,6 +9830,16 @@ type IssueSetWeightPayload { Values for sorting issues """ enum IssueSort { + """ + Created at ascending order + """ + CREATED_ASC + + """ + Created at descending order + """ + CREATED_DESC + """ Due date by ascending order """ @@ -8656,11 +9880,41 @@ enum IssueSort { """ PRIORITY_DESC + """ + Published issues shown last + """ + PUBLISHED_ASC + + """ + Published issues shown first + """ + PUBLISHED_DESC + """ Relative position by ascending order """ RELATIVE_POSITION_ASC + """ + Severity from less critical to more critical + """ + SEVERITY_ASC + + """ + Severity from more critical to less critical + """ + SEVERITY_DESC + + """ + Updated at ascending order + """ + UPDATED_ASC + + """ + Updated at descending order + """ + UPDATED_DESC + """ Weight by ascending order """ @@ -8674,22 +9928,22 @@ enum IssueSort { """ Created at ascending order """ - created_asc + created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5") """ Created at descending order """ - created_desc + created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5") """ Updated at ascending order """ - updated_asc + updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5") """ Updated at descending order """ - updated_desc + updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5") } """ @@ -8702,6 +9956,21 @@ enum IssueState { opened } +""" +Values for issue state events +""" +enum IssueStateEvent { + """ + Closes the issue + """ + CLOSE + + """ + Reopens the issue + """ + REOPEN +} + """ Represents total number of issues for the represented statuses """ @@ -9214,6 +10483,11 @@ type Label { The connection type for Label. """ type LabelConnection { + """ + Total count of collection + """ + count: Int! + """ A list of edges. """ @@ -9250,6 +10524,11 @@ Identifier of Label """ scalar LabelID +""" +Identifier of List +""" +scalar ListID + """ List limit metric setting """ @@ -9318,6 +10597,26 @@ enum MeasurementIdentifier { """ PIPELINES + """ + Pipeline count with canceled status + """ + PIPELINES_CANCELED + + """ + Pipeline count with failed status + """ + PIPELINES_FAILED + + """ + Pipeline count with skipped status + """ + PIPELINES_SKIPPED + + """ + Pipeline count with success status + """ + PIPELINES_SUCCEEDED + """ Project count """ @@ -10018,6 +11317,86 @@ type MergeRequestCreatePayload { mergeRequest: MergeRequest } +""" +Represents the Geo sync and verification state of a Merge Request diff +""" +type MergeRequestDiffRegistry { + """ + Timestamp when the MergeRequestDiffRegistry was created + """ + createdAt: Time + + """ + ID of the MergeRequestDiffRegistry + """ + id: ID! + + """ + Error message during sync of the MergeRequestDiffRegistry + """ + lastSyncFailure: String + + """ + Timestamp of the most recent successful sync of the MergeRequestDiffRegistry + """ + lastSyncedAt: Time + + """ + ID of the Merge Request diff + """ + mergeRequestDiffId: ID! + + """ + Timestamp after which the MergeRequestDiffRegistry should be resynced + """ + retryAt: Time + + """ + Number of consecutive failed sync attempts of the MergeRequestDiffRegistry + """ + retryCount: Int + + """ + Sync state of the MergeRequestDiffRegistry + """ + state: RegistryState +} + +""" +The connection type for MergeRequestDiffRegistry. +""" +type MergeRequestDiffRegistryConnection { + """ + A list of edges. + """ + edges: [MergeRequestDiffRegistryEdge] + + """ + A list of nodes. + """ + nodes: [MergeRequestDiffRegistry] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type MergeRequestDiffRegistryEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: MergeRequestDiffRegistry +} + """ An edge in a connection. """ @@ -10033,6 +11412,11 @@ type MergeRequestEdge { node: MergeRequest } +""" +Identifier of MergeRequest +""" +scalar MergeRequestID + """ Check permissions for the current user on a merge request """ @@ -10245,7 +11629,7 @@ input MergeRequestSetMilestoneInput { """ The milestone to assign to the merge request. """ - milestoneId: ID + milestoneId: MilestoneID """ The project the merge request to mutate is in @@ -10367,6 +11751,16 @@ type MergeRequestSetWipPayload { Values for sorting merge requests """ enum MergeRequestSort { + """ + Created at ascending order + """ + CREATED_ASC + + """ + Created at descending order + """ + CREATED_DESC + """ Label priority by ascending order """ @@ -10407,25 +11801,35 @@ enum MergeRequestSort { """ PRIORITY_DESC + """ + Updated at ascending order + """ + UPDATED_ASC + + """ + Updated at descending order + """ + UPDATED_DESC + """ Created at ascending order """ - created_asc + created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5") """ Created at descending order """ - created_desc + created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5") """ Updated at ascending order """ - updated_asc + updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5") """ Updated at descending order """ - updated_desc + updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5") } """ @@ -10783,11 +12187,13 @@ type Mutation { configureSast(input: ConfigureSastInput!): ConfigureSastPayload createAlertIssue(input: CreateAlertIssueInput!): CreateAlertIssuePayload createAnnotation(input: CreateAnnotationInput!): CreateAnnotationPayload + createBoard(input: CreateBoardInput!): CreateBoardPayload createBranch(input: CreateBranchInput!): CreateBranchPayload createClusterAgent(input: CreateClusterAgentInput!): CreateClusterAgentPayload createDiffNote(input: CreateDiffNoteInput!): CreateDiffNotePayload createEpic(input: CreateEpicInput!): CreateEpicPayload createImageDiffNote(input: CreateImageDiffNoteInput!): CreateImageDiffNotePayload + createIssue(input: CreateIssueInput!): CreateIssuePayload createIteration(input: CreateIterationInput!): CreateIterationPayload createNote(input: CreateNoteInput!): CreateNotePayload createRequirement(input: CreateRequirementInput!): CreateRequirementPayload @@ -10800,11 +12206,13 @@ type Mutation { dastSiteProfileCreate(input: DastSiteProfileCreateInput!): DastSiteProfileCreatePayload dastSiteProfileDelete(input: DastSiteProfileDeleteInput!): DastSiteProfileDeletePayload dastSiteProfileUpdate(input: DastSiteProfileUpdateInput!): DastSiteProfileUpdatePayload + dastSiteTokenCreate(input: DastSiteTokenCreateInput!): DastSiteTokenCreatePayload deleteAnnotation(input: DeleteAnnotationInput!): DeleteAnnotationPayload designManagementDelete(input: DesignManagementDeleteInput!): DesignManagementDeletePayload designManagementMove(input: DesignManagementMoveInput!): DesignManagementMovePayload designManagementUpload(input: DesignManagementUploadInput!): DesignManagementUploadPayload destroyBoard(input: DestroyBoardInput!): DestroyBoardPayload + destroyBoardList(input: DestroyBoardListInput!): DestroyBoardListPayload destroyNote(input: DestroyNoteInput!): DestroyNotePayload destroySnippet(input: DestroySnippetInput!): DestroySnippetPayload @@ -10812,10 +12220,11 @@ type Mutation { Toggles the resolved state of a discussion """ discussionToggleResolve(input: DiscussionToggleResolveInput!): DiscussionToggleResolvePayload - dismissVulnerability(input: DismissVulnerabilityInput!): DismissVulnerabilityPayload + dismissVulnerability(input: DismissVulnerabilityInput!): DismissVulnerabilityPayload @deprecated(reason: "Use vulnerabilityDismiss. Deprecated in 13.5") epicAddIssue(input: EpicAddIssueInput!): EpicAddIssuePayload epicSetSubscription(input: EpicSetSubscriptionInput!): EpicSetSubscriptionPayload epicTreeReorder(input: EpicTreeReorderInput!): EpicTreeReorderPayload + issueMove(input: IssueMoveInput!): IssueMovePayload issueMoveList(input: IssueMoveListInput!): IssueMoveListPayload issueSetAssignees(input: IssueSetAssigneesInput!): IssueSetAssigneesPayload issueSetConfidential(input: IssueSetConfidentialInput!): IssueSetConfidentialPayload @@ -10847,6 +12256,7 @@ type Mutation { pipelineRetry(input: PipelineRetryInput!): PipelineRetryPayload removeAwardEmoji(input: RemoveAwardEmojiInput!): RemoveAwardEmojiPayload @deprecated(reason: "Use awardEmojiRemove. Deprecated in 13.2") removeProjectFromSecurityDashboard(input: RemoveProjectFromSecurityDashboardInput!): RemoveProjectFromSecurityDashboardPayload + revertVulnerabilityToDetected(input: RevertVulnerabilityToDetectedInput!): RevertVulnerabilityToDetectedPayload @deprecated(reason: "Use vulnerabilityRevertToDetected. Deprecated in 13.5") runDastScan(input: RunDASTScanInput!): RunDASTScanPayload @deprecated(reason: "Use DastOnDemandScanCreate. Deprecated in 13.4") todoMarkDone(input: TodoMarkDoneInput!): TodoMarkDonePayload todoRestore(input: TodoRestoreInput!): TodoRestorePayload @@ -10855,6 +12265,7 @@ type Mutation { toggleAwardEmoji(input: ToggleAwardEmojiInput!): ToggleAwardEmojiPayload @deprecated(reason: "Use awardEmojiToggle. Deprecated in 13.2") updateAlertStatus(input: UpdateAlertStatusInput!): UpdateAlertStatusPayload updateBoard(input: UpdateBoardInput!): UpdateBoardPayload + updateBoardEpicUserPreferences(input: UpdateBoardEpicUserPreferencesInput!): UpdateBoardEpicUserPreferencesPayload updateBoardList(input: UpdateBoardListInput!): UpdateBoardListPayload updateContainerExpirationPolicy(input: UpdateContainerExpirationPolicyInput!): UpdateContainerExpirationPolicyPayload updateEpic(input: UpdateEpicInput!): UpdateEpicPayload @@ -10875,7 +12286,10 @@ type Mutation { updateNote(input: UpdateNoteInput!): UpdateNotePayload updateRequirement(input: UpdateRequirementInput!): UpdateRequirementPayload updateSnippet(input: UpdateSnippetInput!): UpdateSnippetPayload + vulnerabilityConfirm(input: VulnerabilityConfirmInput!): VulnerabilityConfirmPayload + vulnerabilityDismiss(input: VulnerabilityDismissInput!): VulnerabilityDismissPayload vulnerabilityResolve(input: VulnerabilityResolveInput!): VulnerabilityResolvePayload + vulnerabilityRevertToDetected(input: VulnerabilityRevertToDetectedInput!): VulnerabilityRevertToDetectedPayload } """ @@ -10899,6 +12313,21 @@ enum MutationOperationMode { } type Namespace { + """ + Size limit for repositories in the namespace in bytes + """ + actualRepositorySizeLimit: Float + + """ + Additional storage purchased for the root namespace in bytes + """ + additionalPurchasedStorageSize: Float + + """ + Includes at least one project where the repository size exceeds the limit + """ + containsLockedProjects: Boolean! + """ Description of the namespace """ @@ -10989,6 +12418,11 @@ type Namespace { sort: NamespaceProjectSort = null ): ProjectConnection! + """ + Number of projects in the root namespace where the repository size exceeds the limit + """ + repositorySizeExcessProjectCount: Int! + """ Indicates if users can request access to namespace """ @@ -11009,6 +12443,16 @@ type Namespace { """ temporaryStorageIncreaseEndsOn: Time + """ + Total repository size of all projects in the root namespace in bytes + """ + totalRepositorySize: Float + + """ + Total excess repository size of all projects in the root namespace in bytes + """ + totalRepositorySizeExcess: Float + """ Visibility of the namespace """ @@ -11050,6 +12494,11 @@ type NamespaceEdge { node: Namespace } +""" +Identifier of Namespace +""" +scalar NamespaceID + """ Autogenerated input type of NamespaceIncreaseStorageTemporarily """ @@ -11062,7 +12511,7 @@ input NamespaceIncreaseStorageTemporarilyInput { """ The global id of the namespace to mutate """ - id: ID! + id: NamespaceID! } """ @@ -11259,6 +12708,11 @@ type NoteEdge { node: Note } +""" +Identifier of Note +""" +scalar NoteID + type NotePermissions { """ Indicates the user can perform `admin_note` on this resource @@ -11338,6 +12792,11 @@ interface Noteable { ): NoteConnection! } +""" +Identifier of Noteable +""" +scalar NoteableID + """ Represents a package """ @@ -11409,7 +12868,7 @@ type PackageEdge { } """ -Represents the sync and verification state of a package file +Represents the Geo sync and verification state of a package file """ type PackageFileRegistry { """ @@ -11490,37 +12949,47 @@ type PackageFileRegistryEdge { enum PackageTypeEnum { """ - Packages from the composer package manager + Packages from the Composer package manager """ COMPOSER """ - Packages from the conan package manager + Packages from the Conan package manager """ CONAN """ - Packages from the generic package manager + Packages from the Debian package manager + """ + DEBIAN + + """ + Packages from the Generic package manager """ GENERIC """ - Packages from the maven package manager + Packages from the Golang package manager + """ + GOLANG + + """ + Packages from the Maven package manager """ MAVEN """ - Packages from the npm package manager + Packages from the NPM package manager """ NPM """ - Packages from the nuget package manager + Packages from the Nuget package manager """ NUGET """ - Packages from the pypi package manager + Packages from the PyPI package manager """ PYPI } @@ -11853,10 +13322,20 @@ enum PipelineStatusEnum { } type Project { + """ + Size limit for the repository in bytes + """ + actualRepositorySizeLimit: Float + """ A single Alert Management alert of the project """ alertManagementAlert( + """ + Username of a user assigned to the issue + """ + assigneeUsername: String + """ IID of the alert. For example, "1" """ @@ -11882,6 +13361,11 @@ type Project { Counts of alerts by status for the project """ alertManagementAlertStatusCounts( + """ + Username of a user assigned to the issue + """ + assigneeUsername: String + """ Search criteria for filtering alerts. This will search on title, description, service, monitoring_tool. """ @@ -11897,6 +13381,11 @@ type Project { """ after: String + """ + Username of a user assigned to the issue + """ + assigneeUsername: String + """ Returns the elements in the list that come before the specified cursor. """ @@ -11959,9 +13448,9 @@ type Project { """ board( """ - Find a board by its ID + The board's ID """ - id: ID + id: BoardID! ): Board """ @@ -12248,6 +13737,16 @@ type Project { """ assigneeUsername: String + """ + Usernames of users assigned to the issue + """ + assigneeUsernames: [String!] + + """ + Username of the author of the issue + """ + authorUsername: String + """ Issues closed after this date """ @@ -12338,6 +13837,16 @@ type Project { """ assigneeUsername: String + """ + Usernames of users assigned to the issue + """ + assigneeUsernames: [String!] + + """ + Username of the author of the issue + """ + authorUsername: String + """ Issues closed after this date """ @@ -12418,6 +13927,16 @@ type Project { """ assigneeUsername: String + """ + Usernames of users assigned to the issue + """ + assigneeUsernames: [String!] + + """ + Username of the author of the issue + """ + authorUsername: String + """ Returns the elements in the list that come before the specified cursor. """ @@ -12529,8 +14048,8 @@ type Project { before: String """ - List items within a time frame where items.end_date is between startDate and - endDate parameters (startDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use timeframe.end """ endDate: Time @@ -12560,8 +14079,9 @@ type Project { last: Int """ - List items within a time frame where items.start_date is between startDate - and endDate parameters (endDate parameter must be present) + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use + timeframe.start """ startDate: Time @@ -12570,6 +14090,11 @@ type Project { """ state: IterationState + """ + List items overlapping the given timeframe + """ + timeframe: Timeframe + """ Fuzzy search by title """ @@ -12778,8 +14303,13 @@ type Project { before: String """ - List items within a time frame where items.end_date is between startDate and - endDate parameters (startDate parameter must be present) + A date that the milestone contains + """ + containingDate: Time + + """ + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use timeframe.end """ endDate: Time @@ -12804,8 +14334,14 @@ type Project { last: Int """ - List items within a time frame where items.start_date is between startDate - and endDate parameters (endDate parameter must be present) + A search string for the title + """ + searchTitle: String + + """ + List items overlapping a time frame defined by startDate..endDate (if one + date is provided, both must be present). Deprecated in 13.5: Use + timeframe.start """ startDate: Time @@ -12813,6 +14349,16 @@ type Project { Filter milestones by state """ state: MilestoneStateEnum + + """ + List items overlapping the given timeframe + """ + timeframe: Timeframe + + """ + The title of the milestone + """ + title: String ): MilestoneConnection """ @@ -13011,13 +14557,18 @@ type Project { """ repository: Repository + """ + Size of repository that exceeds the limit in bytes + """ + repositorySizeExcess: Float + """ Indicates if users can request member access to the project """ requestAccessEnabled: Boolean """ - Find a single requirement. Available only when feature flag `requirements_management` is enabled. + Find a single requirement """ requirement( """ @@ -13057,7 +14608,7 @@ type Project { requirementStatesCount: RequirementStatesCount """ - Find requirements. Available only when feature flag `requirements_management` is enabled. + Find requirements """ requirements( """ @@ -13256,6 +14807,31 @@ type Project { """ tagList: String + """ + Terraform states associated with the project + """ + terraformStates( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): TerraformStateConnection + """ Permissions for the current user on the resource """ @@ -13467,6 +15043,11 @@ type ProjectEdge { node: Project } +""" +Identifier of Project +""" +scalar ProjectID + """ Represents a Project Membership """ @@ -14001,8 +15582,43 @@ type Query { Search query for project name, path, or description """ search: String + + """ + Include namespace in project search + """ + searchNamespaces: Boolean + + """ + Sort order of results + """ + sort: String ): ProjectConnection + """ + Supported runner platforms + """ + runnerPlatforms( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): RunnerPlatformConnection + """ Find Snippets visible to the current user """ @@ -14249,6 +15865,16 @@ type Query { """ startDate: ISO8601Date! ): VulnerabilitiesCountByDayAndSeverityConnection @deprecated(reason: "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3") + + """ + Find a vulnerability + """ + vulnerability( + """ + The Global ID of the Vulnerability + """ + id: VulnerabilityID! + ): Vulnerability } """ @@ -14725,7 +16351,7 @@ input RemoveAwardEmojiInput { """ The global id of the awardable resource """ - awardableId: ID! + awardableId: AwardableID! """ A unique identifier for the client performing the mutation. @@ -14770,7 +16396,7 @@ input RemoveProjectFromSecurityDashboardInput { """ ID of the project to remove from the Instance Security Dashboard """ - id: ID! + id: ProjectID! } """ @@ -14839,6 +16465,16 @@ type Requirement { """ createdAt: Time! + """ + Description of the requirement + """ + description: String + + """ + The GitLab Flavored Markdown rendering of `description` + """ + descriptionHtml: String + """ ID of the requirement """ @@ -14849,6 +16485,11 @@ type Requirement { """ iid: ID! + """ + Indicates if latest test report was created by user + """ + lastTestReportManuallyCreated: Boolean + """ Latest requirement test report state """ @@ -14899,6 +16540,11 @@ type Requirement { """ title: String + """ + The GitLab Flavored Markdown rendering of `title` + """ + titleHtml: String + """ Timestamp of when the requirement was last updated """ @@ -15020,6 +16666,41 @@ interface ResolvableInterface { resolvedBy: User } +""" +Autogenerated input type of RevertVulnerabilityToDetected +""" +input RevertVulnerabilityToDetectedInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the vulnerability to be reverted + """ + id: VulnerabilityID! +} + +""" +Autogenerated return type of RevertVulnerabilityToDetected +""" +type RevertVulnerabilityToDetectedPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The vulnerability after revert + """ + vulnerability: Vulnerability +} + type RootStorageStatistics { """ The CI artifacts size in bytes @@ -15027,84 +16708,208 @@ type RootStorageStatistics { buildArtifactsSize: Float! """ - The LFS objects size in bytes + The LFS objects size in bytes + """ + lfsObjectsSize: Float! + + """ + The packages size in bytes + """ + packagesSize: Float! + + """ + The CI pipeline artifacts size in bytes + """ + pipelineArtifactsSize: Float! + + """ + The Git repository size in bytes + """ + repositorySize: Float! + + """ + The snippets size in bytes + """ + snippetsSize: Float! + + """ + The total storage in bytes + """ + storageSize: Float! + + """ + The wiki size in bytes + """ + wikiSize: Float! +} + +""" +Autogenerated input type of RunDASTScan +""" +input RunDASTScanInput { + """ + The branch to be associated with the scan. + """ + branch: String! + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + The project the DAST scan belongs to. + """ + projectPath: ID! + + """ + The type of scan to be run. + """ + scanType: DastScanTypeEnum! + + """ + The URL of the target to be scanned. + """ + targetUrl: String! +} + +""" +Autogenerated return type of RunDASTScan +""" +type RunDASTScanPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + URL of the pipeline that was created. """ - lfsObjectsSize: Float! + pipelineUrl: String +} +type RunnerArchitecture { """ - The packages size in bytes + Download location for the runner for the platform architecture """ - packagesSize: Float! + downloadLocation: String! """ - The Git repository size in bytes + Name of the runner platform architecture """ - repositorySize: Float! + name: String! +} +""" +The connection type for RunnerArchitecture. +""" +type RunnerArchitectureConnection { """ - The snippets size in bytes + A list of edges. """ - snippetsSize: Float! + edges: [RunnerArchitectureEdge] """ - The total storage in bytes + A list of nodes. """ - storageSize: Float! + nodes: [RunnerArchitecture] """ - The wiki size in bytes + Information to aid in pagination. """ - wikiSize: Float! + pageInfo: PageInfo! } """ -Autogenerated input type of RunDASTScan +An edge in a connection. """ -input RunDASTScanInput { +type RunnerArchitectureEdge { """ - The branch to be associated with the scan. + A cursor for use in pagination. """ - branch: String! + cursor: String! """ - A unique identifier for the client performing the mutation. + The item at the end of the edge. """ - clientMutationId: String + node: RunnerArchitecture +} +type RunnerPlatform { """ - The project the DAST scan belongs to. + Runner architectures supported for the platform """ - projectPath: ID! + architectures( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): RunnerArchitectureConnection """ - The type of scan to be run. + Human readable name of the runner platform """ - scanType: DastScanTypeEnum! + humanReadableName: String! """ - The URL of the target to be scanned. + Name slug of the runner platform """ - targetUrl: String! + name: String! } """ -Autogenerated return type of RunDASTScan +The connection type for RunnerPlatform. """ -type RunDASTScanPayload { +type RunnerPlatformConnection { """ - A unique identifier for the client performing the mutation. + A list of edges. """ - clientMutationId: String + edges: [RunnerPlatformEdge] """ - Errors encountered during execution of the mutation. + A list of nodes. """ - errors: [String!]! + nodes: [RunnerPlatform] """ - URL of the pipeline that was created. + Information to aid in pagination. """ - pipelineUrl: String + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type RunnerPlatformEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: RunnerPlatform } """ @@ -15272,6 +17077,26 @@ type SastCiConfigurationAnalyzersEntityEdge { node: SastCiConfigurationAnalyzersEntity } +""" +Represents the analyzers entity in SAST CI configuration +""" +input SastCiConfigurationAnalyzersEntityInput { + """ + State of the analyzer + """ + enabled: Boolean! + + """ + Name of analyzer + """ + name: String! + + """ + List of variables for the analyzer + """ + variables: [SastCiConfigurationEntityInput!] +} + """ Represents an entity in SAST CI configuration """ @@ -15396,6 +17221,11 @@ input SastCiConfigurationEntityInput { Represents a CI configuration of SAST """ input SastCiConfigurationInput { + """ + List of analyzers and related variables for the SAST configuration + """ + analyzers: [SastCiConfigurationAnalyzersEntityInput!] + """ List of global entities related to SAST configuration """ @@ -15520,6 +17350,11 @@ type ScannedResourceEdge { Represents summary of a security report """ type SecurityReportSummary { + """ + Aggregated counts for the api_fuzzing scan + """ + apiFuzzing: SecurityReportSummarySection + """ Aggregated counts for the container_scanning scan """ @@ -15600,6 +17435,7 @@ type SecurityReportSummarySection { The type of the security scanner """ enum SecurityScannerType { + API_FUZZING CONTAINER_SCANNING COVERAGE_FUZZING DAST @@ -16183,7 +18019,32 @@ type Snippet implements Noteable { """ Snippet blobs """ - blobs: [SnippetBlob!]! + blobs( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Paths of the blobs + """ + paths: [String!] + ): SnippetBlobConnection """ Timestamp this snippet was created @@ -16406,6 +18267,41 @@ input SnippetBlobActionInputType { previousPath: String } +""" +The connection type for SnippetBlob. +""" +type SnippetBlobConnection { + """ + A list of edges. + """ + edges: [SnippetBlobEdge] + + """ + A list of nodes. + """ + nodes: [SnippetBlob] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type SnippetBlobEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: SnippetBlob +} + """ Represents how the blob content should be displayed """ @@ -16520,22 +18416,69 @@ enum Sort { """ Created at ascending order """ - created_asc + CREATED_ASC + + """ + Created at descending order + """ + CREATED_DESC + + """ + Updated at ascending order + """ + UPDATED_ASC + + """ + Updated at descending order + """ + UPDATED_DESC + + """ + Created at ascending order + """ + created_asc @deprecated(reason: "Use CREATED_ASC. Deprecated in 13.5") """ Created at descending order """ - created_desc + created_desc @deprecated(reason: "Use CREATED_DESC. Deprecated in 13.5") """ Updated at ascending order """ - updated_asc + updated_asc @deprecated(reason: "Use UPDATED_ASC. Deprecated in 13.5") """ Updated at descending order """ - updated_desc + updated_desc @deprecated(reason: "Use UPDATED_DESC. Deprecated in 13.5") +} + +type StatusAction { + """ + Title for the button, for example: Retry this job + """ + buttonTitle: String + + """ + Icon used in the action button + """ + icon: String + + """ + Method for the action, for example: :post + """ + method: String + + """ + Path for the action + """ + path: String + + """ + Title for the action, for example: Retry + """ + title: String } type Submodule implements Entry { @@ -16630,64 +18573,131 @@ type TaskCompletionStatus { count: Int! } +type TerraformState { + """ + Timestamp the Terraform state was created + """ + createdAt: Time! + + """ + ID of the Terraform state + """ + id: ID! + + """ + Timestamp the Terraform state was locked + """ + lockedAt: Time + + """ + The user currently holding a lock on the Terraform state + """ + lockedByUser: User + + """ + Name of the Terraform state + """ + name: String! + + """ + Timestamp the Terraform state was updated + """ + updatedAt: Time! +} + +""" +The connection type for TerraformState. +""" +type TerraformStateConnection { + """ + A list of edges. + """ + edges: [TerraformStateEdge] + + """ + A list of nodes. + """ + nodes: [TerraformState] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type TerraformStateEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: TerraformState +} + """ -Represents the sync and verification state of a terraform state +Represents the Geo sync and verification state of a terraform state version """ -type TerraformStateRegistry { +type TerraformStateVersionRegistry { """ - Timestamp when the TerraformStateRegistry was created + Timestamp when the TerraformStateVersionRegistry was created """ createdAt: Time """ - ID of the TerraformStateRegistry + ID of the TerraformStateVersionRegistry """ id: ID! """ - Error message during sync of the TerraformStateRegistry + Error message during sync of the TerraformStateVersionRegistry """ lastSyncFailure: String """ - Timestamp of the most recent successful sync of the TerraformStateRegistry + Timestamp of the most recent successful sync of the TerraformStateVersionRegistry """ lastSyncedAt: Time """ - Timestamp after which the TerraformStateRegistry should be resynced + Timestamp after which the TerraformStateVersionRegistry should be resynced """ retryAt: Time """ - Number of consecutive failed sync attempts of the TerraformStateRegistry + Number of consecutive failed sync attempts of the TerraformStateVersionRegistry """ retryCount: Int """ - Sync state of the TerraformStateRegistry + Sync state of the TerraformStateVersionRegistry """ state: RegistryState """ - ID of the TerraformState + ID of the terraform state version """ - terraformStateId: ID! + terraformStateVersionId: ID! } """ -The connection type for TerraformStateRegistry. +The connection type for TerraformStateVersionRegistry. """ -type TerraformStateRegistryConnection { +type TerraformStateVersionRegistryConnection { """ A list of edges. """ - edges: [TerraformStateRegistryEdge] + edges: [TerraformStateVersionRegistryEdge] """ A list of nodes. """ - nodes: [TerraformStateRegistry] + nodes: [TerraformStateVersionRegistry] """ Information to aid in pagination. @@ -16698,7 +18708,7 @@ type TerraformStateRegistryConnection { """ An edge in a connection. """ -type TerraformStateRegistryEdge { +type TerraformStateVersionRegistryEdge { """ A cursor for use in pagination. """ @@ -16707,7 +18717,7 @@ type TerraformStateRegistryEdge { """ The item at the end of the edge. """ - node: TerraformStateRegistry + node: TerraformStateVersionRegistry } """ @@ -16779,15 +18789,30 @@ enum TestReportState { } """ -Time represented in ISO 8601 +Time represented in ISO 8601 +""" +scalar Time + +interface TimeboxBurnupTimeSeriesInterface { + """ + Daily scope and completed totals for burnup charts + """ + burnupTimeSeries: [BurnupChartDailyTotals!] +} + +""" +A time-frame defined as a closed inclusive range of two dates """ -scalar Time +input Timeframe { + """ + The end of the range + """ + end: Date! -interface TimeboxBurnupTimeSeriesInterface { """ - Daily scope and completed totals for burnup charts + The start of the range """ - burnupTimeSeries: [BurnupChartDailyTotals!] + start: Date! } type Timelog { @@ -16952,6 +18977,11 @@ type TodoEdge { node: Todo } +""" +Identifier of Todo +""" +scalar TodoID + """ Autogenerated input type of TodoMarkDone """ @@ -16964,7 +18994,7 @@ input TodoMarkDoneInput { """ The global id of the todo to mark as done """ - id: ID! + id: TodoID! } """ @@ -16999,7 +19029,7 @@ input TodoRestoreInput { """ The global id of the todo to restore """ - id: ID! + id: TodoID! } """ @@ -17014,7 +19044,7 @@ input TodoRestoreManyInput { """ The global ids of the todos to restore (a maximum of 50 is supported at once) """ - ids: [ID!]! + ids: [TodoID!]! } """ @@ -17141,7 +19171,7 @@ input ToggleAwardEmojiInput { """ The global id of the awardable resource """ - awardableId: ID! + awardableId: AwardableID! """ A unique identifier for the client performing the mutation. @@ -17406,6 +19436,51 @@ type UpdateAlertStatusPayload { todo: Todo } +""" +Autogenerated input type of UpdateBoardEpicUserPreferences +""" +input UpdateBoardEpicUserPreferencesInput { + """ + The board global ID + """ + boardId: BoardID! + + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Whether the epic should be collapsed in the board + """ + collapsed: Boolean! + + """ + ID of an epic to set preferences for + """ + epicId: EpicID! +} + +""" +Autogenerated return type of UpdateBoardEpicUserPreferences +""" +type UpdateBoardEpicUserPreferencesPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + User preferences for the epic in the board after mutation + """ + epicUserPreferences: BoardEpicUserPreferences + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! +} + """ Autogenerated input type of UpdateBoard """ @@ -17413,7 +19488,7 @@ input UpdateBoardInput { """ The id of user to be assigned to the board. """ - assigneeId: ID + assigneeId: UserID """ A unique identifier for the client performing the mutation. @@ -17433,12 +19508,22 @@ input UpdateBoardInput { """ The board global id. """ - id: ID! + id: BoardID! + + """ + The IDs of labels to be added to the board. + """ + labelIds: [LabelID!] + + """ + Labels of the issue + """ + labels: [String!] """ The id of milestone to be assigned to the board. """ - milestoneId: ID + milestoneId: MilestoneID """ Name of the board @@ -17710,7 +19795,7 @@ input UpdateImageDiffNoteInput { """ The global id of the note to update """ - id: ID! + id: NoteID! """ The position of this note on a diff @@ -17743,7 +19828,7 @@ Autogenerated input type of UpdateIssue """ input UpdateIssueInput { """ - The IDs of labels to be added to the issue. + The IDs of labels to be added to the issue """ addLabelIds: [ID!] @@ -17765,7 +19850,7 @@ input UpdateIssueInput { """ Due date of the issue """ - dueDate: Time + dueDate: ISO8601Date """ The ID of the parent epic. NULL when removing the association @@ -17788,7 +19873,7 @@ input UpdateIssueInput { locked: Boolean """ - The ID of the milestone to be assigned, milestone will be removed if set to null. + The ID of the milestone to assign to the issue. On update milestone will be removed if set to null """ milestoneId: ID @@ -17798,14 +19883,24 @@ input UpdateIssueInput { projectPath: ID! """ - The IDs of labels to be removed from the issue. + The IDs of labels to be removed from the issue """ removeLabelIds: [ID!] + """ + Close or reopen an issue + """ + stateEvent: IssueStateEvent + """ Title of the issue """ title: String + + """ + The weight of the issue + """ + weight: Int } """ @@ -17910,7 +20005,7 @@ input UpdateNoteInput { """ The global id of the note to update """ - id: ID! + id: NoteID! } """ @@ -17942,6 +20037,11 @@ input UpdateRequirementInput { """ clientMutationId: String + """ + Description of the requirement + """ + description: String + """ The iid of the requirement to update """ @@ -17953,7 +20053,7 @@ input UpdateRequirementInput { lastTestReportState: TestReportState """ - The project full path the requirement is associated with + Full project path the requirement is associated with """ projectPath: ID! @@ -17983,7 +20083,7 @@ type UpdateRequirementPayload { errors: [String!]! """ - The requirement after mutation + Requirement after mutation """ requirement: Requirement } @@ -18041,6 +20141,11 @@ type UpdateSnippetPayload { The snippet after mutation """ snippet: Snippet + + """ + Indicates whether the operation returns a record detected as spam + """ + spam: Boolean } scalar Upload @@ -18055,6 +20160,11 @@ type User { """ after: String + """ + Username of the author + """ + authorUsername: String + """ Returns the elements in the list that come before the specified cursor. """ @@ -18135,6 +20245,11 @@ type User { """ after: String + """ + Username of the assignee + """ + assigneeUsername: String + """ Returns the elements in the list that come before the specified cursor. """ @@ -18666,7 +20781,7 @@ type VulnerabilitiesCountByDayEdge { """ Represents a vulnerability """ -type Vulnerability { +type Vulnerability implements Noteable { """ Description of the vulnerability """ @@ -18677,6 +20792,31 @@ type Vulnerability { """ detectedAt: Time! + """ + All discussions on this noteable + """ + discussions( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): DiscussionConnection! + """ GraphQL ID of the vulnerability """ @@ -18722,6 +20862,31 @@ type Vulnerability { """ location: VulnerabilityLocation + """ + All notes on this noteable + """ + notes( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + ): NoteConnection! + """ Primary identifier of the vulnerability. """ @@ -18735,7 +20900,7 @@ type Vulnerability { """ Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, - COVERAGE_FUZZING) + COVERAGE_FUZZING, API_FUZZING) """ reportType: VulnerabilityReportType @@ -18755,7 +20920,7 @@ type Vulnerability { severity: VulnerabilitySeverity """ - State of the vulnerability (DETECTED, DISMISSED, RESOLVED, CONFIRMED) + State of the vulnerability (DETECTED, CONFIRMED, RESOLVED, DISMISSED) """ state: VulnerabilityState @@ -18780,6 +20945,41 @@ type Vulnerability { vulnerabilityPath: String } +""" +Autogenerated input type of VulnerabilityConfirm +""" +input VulnerabilityConfirmInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the vulnerability to be confirmed + """ + id: VulnerabilityID! +} + +""" +Autogenerated return type of VulnerabilityConfirm +""" +type VulnerabilityConfirmPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The vulnerability after state change + """ + vulnerability: Vulnerability +} + """ The connection type for Vulnerability. """ @@ -18800,6 +21000,46 @@ type VulnerabilityConnection { pageInfo: PageInfo! } +""" +Autogenerated input type of VulnerabilityDismiss +""" +input VulnerabilityDismissInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Reason why vulnerability should be dismissed + """ + comment: String + + """ + ID of the vulnerability to be dismissed + """ + id: VulnerabilityID! +} + +""" +Autogenerated return type of VulnerabilityDismiss +""" +type VulnerabilityDismissPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The vulnerability after dismissal + """ + vulnerability: Vulnerability +} + """ An edge in a connection. """ @@ -19123,6 +21363,7 @@ type VulnerabilityPermissions { The type of the security scan that found the vulnerability """ enum VulnerabilityReportType { + API_FUZZING CONTAINER_SCANNING COVERAGE_FUZZING DAST @@ -19141,7 +21382,7 @@ input VulnerabilityResolveInput { clientMutationId: String """ - ID of the vulnerability to be resolveed + ID of the vulnerability to be resolved """ id: VulnerabilityID! } @@ -19166,6 +21407,41 @@ type VulnerabilityResolvePayload { vulnerability: Vulnerability } +""" +Autogenerated input type of VulnerabilityRevertToDetected +""" +input VulnerabilityRevertToDetectedInput { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + ID of the vulnerability to be reverted + """ + id: VulnerabilityID! +} + +""" +Autogenerated return type of VulnerabilityRevertToDetected +""" +type VulnerabilityRevertToDetectedPayload { + """ + A unique identifier for the client performing the mutation. + """ + clientMutationId: String + + """ + Errors encountered during execution of the mutation. + """ + errors: [String!]! + + """ + The vulnerability after revert + """ + vulnerability: Vulnerability +} + """ Represents a vulnerability scanner """ @@ -19277,6 +21553,26 @@ enum VulnerabilitySeverity { Vulnerability sort values """ enum VulnerabilitySort { + """ + Detection timestamp in ascending order + """ + detected_asc + + """ + Detection timestamp in descending order + """ + detected_desc + + """ + Report Type in ascending order + """ + report_type_asc + + """ + Report Type in descending order + """ + report_type_desc + """ Severity in ascending order """ @@ -19286,6 +21582,26 @@ enum VulnerabilitySort { Severity in descending order """ severity_desc + + """ + State in ascending order + """ + state_asc + + """ + State in descending order + """ + state_desc + + """ + Title in ascending order + """ + title_asc + + """ + Title in descending order + """ + title_desc } """ diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index 173415ca164..6914ba29c57 100644 --- a/doc/api/graphql/reference/gitlab_schema.json +++ b/doc/api/graphql/reference/gitlab_schema.json @@ -111,7 +111,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "AwardableID", "ofType": null } }, @@ -227,7 +227,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "ProjectID", "ofType": null } }, @@ -381,6 +381,16 @@ }, "defaultValue": null }, + { + "name": "featureCategory", + "description": "Delete jobs matching feature_category in the context metadata", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, { "name": "queueName", "description": "The name of the queue to delete jobs from", @@ -666,6 +676,20 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "environment", + "description": "Environment for the alert", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Environment", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "eventCount", "description": "Number of events of this alert", @@ -1227,23 +1251,47 @@ { "name": "updated_desc", "description": "Updated at descending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5" + }, + { + "name": "updated_asc", + "description": "Updated at ascending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5" + }, + { + "name": "created_desc", + "description": "Created at descending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5" + }, + { + "name": "created_asc", + "description": "Created at ascending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5" + }, + { + "name": "UPDATED_DESC", + "description": "Updated at descending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "updated_asc", + "name": "UPDATED_ASC", "description": "Updated at ascending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "created_desc", + "name": "CREATED_DESC", "description": "Created at descending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "created_asc", + "name": "CREATED_ASC", "description": "Created at ascending order", "isDeprecated": false, "deprecationReason": null @@ -1969,7 +2017,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "AwardableID", "ofType": null } }, @@ -2085,7 +2133,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "AwardableID", "ofType": null } }, @@ -2201,7 +2249,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "AwardableID", "ofType": null } }, @@ -2321,6 +2369,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "AwardableID", + "description": "Identifier of Awardable", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "BaseService", @@ -2764,7 +2822,7 @@ ], "type": { "kind": "OBJECT", - "name": "EpicConnection", + "name": "BoardEpicConnection", "ofType": null }, "isDeprecated": false, @@ -2816,6 +2874,59 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "labels", + "description": "Labels of the board", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "LabelConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "lists", "description": "Lists of the board", @@ -2830,6 +2941,16 @@ }, "defaultValue": null }, + { + "name": "issueFilters", + "description": "Filters applied when getting issue metadata in the board list", + "type": { + "kind": "INPUT_OBJECT", + "name": "BoardIssueInput", + "ofType": null + }, + "defaultValue": null + }, { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", @@ -3041,181 +3162,14 @@ "enumValues": null, "possibleTypes": null }, - { - "kind": "SCALAR", - "name": "BoardID", - "description": "Identifier of Board", - "fields": null, - "inputFields": null, - "interfaces": null, - "enumValues": null, - "possibleTypes": null - }, - { - "kind": "INPUT_OBJECT", - "name": "BoardIssueInput", - "description": null, - "fields": null, - "inputFields": [ - { - "name": "labelName", - "description": "Filter by label name", - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } - }, - "defaultValue": null - }, - { - "name": "milestoneTitle", - "description": "Filter by milestone title", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "assigneeUsername", - "description": "Filter by assignee username", - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } - }, - "defaultValue": null - }, - { - "name": "authorUsername", - "description": "Filter by author username", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "releaseTag", - "description": "Filter by release tag", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "myReactionEmoji", - "description": "Filter by reaction emoji", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "epicId", - "description": "Filter by epic ID. Incompatible with epicWildcardId", - "type": { - "kind": "SCALAR", - "name": "ID", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "weight", - "description": "Filter by weight", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "not", - "description": "List of negated params. Warning: this argument is experimental and a subject to change in future", - "type": { - "kind": "INPUT_OBJECT", - "name": "NegatedBoardIssueInput", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "search", - "description": "Search query for issue title or description", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "epicWildcardId", - "description": "Filter by epic ID wildcard. Incompatible with epicId", - "type": { - "kind": "ENUM", - "name": "EpicWildcardId", - "ofType": null - }, - "defaultValue": null - } - ], - "interfaces": null, - "enumValues": null, - "possibleTypes": null - }, { "kind": "OBJECT", - "name": "BoardList", - "description": "Represents a list for an issue board", + "name": "BoardEpic", + "description": "Represents an epic on an issue board", "fields": [ { - "name": "assignee", - "description": "Assignee in the list", - "args": [ - - ], - "type": { - "kind": "OBJECT", - "name": "User", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "collapsed", - "description": "Indicates if list is collapsed for this user", - "args": [ - - ], - "type": { - "kind": "SCALAR", - "name": "Boolean", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "id", - "description": "ID (global ID) of the list", + "name": "author", + "description": "Author of the epic", "args": [ ], @@ -3223,8 +3177,8 @@ "kind": "NON_NULL", "name": null, "ofType": { - "kind": "SCALAR", - "name": "ID", + "kind": "OBJECT", + "name": "User", "ofType": null } }, @@ -3232,15 +3186,1449 @@ "deprecationReason": null }, { - "name": "issues", - "description": "Board issues", + "name": "children", + "description": "Children (sub-epics) of the epic", "args": [ { - "name": "filters", - "description": "Filters applied when selecting issues in the board list", + "name": "startDate", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "endDate", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "timeframe", + "description": "List items overlapping the given timeframe", "type": { "kind": "INPUT_OBJECT", - "name": "BoardIssueInput", + "name": "Timeframe", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "iid", + "description": "IID of the epic, e.g., \"1\"", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "iids", + "description": "List of IIDs of epics, e.g., [1, 2]", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "state", + "description": "Filter epics by state", + "type": { + "kind": "ENUM", + "name": "EpicState", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "search", + "description": "Search query for epic title or description", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "sort", + "description": "List epics by sort order", + "type": { + "kind": "ENUM", + "name": "EpicSort", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "authorUsername", + "description": "Filter epics by author", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "labelName", + "description": "Filter epics by labels", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "milestoneTitle", + "description": "Filter epics by milestone title, computed from epic's issues", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "iidStartsWith", + "description": "Filter epics by iid for autocomplete", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "EpicConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "closedAt", + "description": "Timestamp of when the epic was closed", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "confidential", + "description": "Indicates if the epic is confidential", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "createdAt", + "description": "Timestamp of when the epic was created", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "currentUserTodos", + "description": "Todos for the current user", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "state", + "description": "State of the todos", + "type": { + "kind": "ENUM", + "name": "TodoStateEnum", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TodoConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "descendantCounts", + "description": "Number of open and closed descendant epics and issues", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "EpicDescendantCount", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "descendantWeightSum", + "description": "Total weight of open and closed issues in the epic and its descendants", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "EpicDescendantWeights", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "description", + "description": "Description of the epic", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "discussions", + "description": "All discussions on this noteable", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DiscussionConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "downvotes", + "description": "Number of downvotes the epic has received", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "dueDate", + "description": "Due date of the epic", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "dueDateFixed", + "description": "Fixed due date of the epic", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "dueDateFromMilestones", + "description": "Inherited due date of the epic from milestones", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "dueDateIsFixed", + "description": "Indicates if the due date has been manually set", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "group", + "description": "Group to which the epic belongs", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Group", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "hasChildren", + "description": "Indicates if the epic has children", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "hasIssues", + "description": "Indicates if the epic has direct issues", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "hasParent", + "description": "Indicates if the epic has a parent epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "healthStatus", + "description": "Current health status of the epic", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "EpicHealthStatus", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "iid", + "description": "Internal ID of the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "issues", + "description": "A list of issues associated with the epic", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "EpicIssueConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "labels", + "description": "Labels assigned to the epic", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "LabelConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "notes", + "description": "All notes on this noteable", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "NoteConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "parent", + "description": "Parent epic of the epic", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Epic", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "participants", + "description": "List of participants for the epic", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "UserConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "reference", + "description": "Internal reference of the epic. Returned in shortened format by default", + "args": [ + { + "name": "full", + "description": "Indicates if the reference should be returned in full", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "relationPath", + "description": "URI path of the epic-issue relationship", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "relativePosition", + "description": "The relative position of the epic in the epic tree", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "startDate", + "description": "Start date of the epic", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "startDateFixed", + "description": "Fixed start date of the epic", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "startDateFromMilestones", + "description": "Inherited start date of the epic from milestones", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "startDateIsFixed", + "description": "Indicates if the start date has been manually set", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "state", + "description": "State of the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "EpicState", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "subscribed", + "description": "Indicates the currently logged in user is subscribed to the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "title", + "description": "Title of the epic", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updatedAt", + "description": "Timestamp of when the epic was updated", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "upvotes", + "description": "Number of upvotes the epic has received", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "userPermissions", + "description": "Permissions for the current user on the resource", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "EpicPermissions", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "userPreferences", + "description": "User preferences for the epic on the issue board", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "BoardEpicUserPreferences", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "webPath", + "description": "Web path of the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "webUrl", + "description": "Web URL of the epic", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + { + "kind": "INTERFACE", + "name": "Noteable", + "ofType": null + }, + { + "kind": "INTERFACE", + "name": "CurrentUserTodos", + "ofType": null + } + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "BoardEpicConnection", + "description": "The connection type for BoardEpic.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "BoardEpicEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "BoardEpic", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "BoardEpicEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "BoardEpic", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "BoardEpicUserPreferences", + "description": "Represents user preferences for a board epic", + "fields": [ + { + "name": "collapsed", + "description": "Indicates epic should be displayed as collapsed", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "BoardID", + "description": "Identifier of Board", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "BoardIssueInput", + "description": null, + "fields": null, + "inputFields": [ + { + "name": "labelName", + "description": "Filter by label name", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "milestoneTitle", + "description": "Filter by milestone title", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "assigneeUsername", + "description": "Filter by assignee username", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "authorUsername", + "description": "Filter by author username", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "releaseTag", + "description": "Filter by release tag", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "myReactionEmoji", + "description": "Filter by reaction emoji", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "epicId", + "description": "Filter by epic ID. Incompatible with epicWildcardId", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "weight", + "description": "Filter by weight", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "not", + "description": "List of negated params. Warning: this argument is experimental and a subject to change in future", + "type": { + "kind": "INPUT_OBJECT", + "name": "NegatedBoardIssueInput", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "search", + "description": "Search query for issue title or description", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "epicWildcardId", + "description": "Filter by epic ID wildcard. Incompatible with epicId", + "type": { + "kind": "ENUM", + "name": "EpicWildcardId", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "BoardList", + "description": "Represents a list for an issue board", + "fields": [ + { + "name": "assignee", + "description": "Assignee in the list", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "User", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "collapsed", + "description": "Indicates if list is collapsed for this user", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID (global ID) of the list", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "issues", + "description": "Board issues", + "args": [ + { + "name": "filters", + "description": "Filters applied when selecting issues in the board list", + "type": { + "kind": "INPUT_OBJECT", + "name": "BoardIssueInput", "ofType": null }, "defaultValue": null @@ -3718,7 +5106,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "ListID", "ofType": null } }, @@ -3999,6 +5387,20 @@ "name": "CiGroup", "description": null, "fields": [ + { + "name": "detailedStatus", + "description": "Detailed status of the group", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DetailedStatus", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "jobs", "description": "Jobs in group", @@ -4186,87 +5588,227 @@ ], "type": { "kind": "OBJECT", - "name": "CiGroup", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - } - ], - "inputFields": null, - "interfaces": [ - - ], - "enumValues": null, - "possibleTypes": null - }, - { - "kind": "OBJECT", - "name": "CiJob", - "description": null, - "fields": [ - { - "name": "name", - "description": "Name of the job", - "args": [ - - ], - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "needs", - "description": "Builds that must complete before the jobs run", - "args": [ - { - "name": "after", - "description": "Returns the elements in the list that come after the specified cursor.", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "before", - "description": "Returns the elements in the list that come before the specified cursor.", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "first", - "description": "Returns the first _n_ elements from the list.", - "type": { - "kind": "SCALAR", - "name": "Int", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "last", - "description": "Returns the last _n_ elements from the list.", - "type": { - "kind": "SCALAR", - "name": "Int", - "ofType": null - }, - "defaultValue": null - } - ], - "type": { - "kind": "OBJECT", - "name": "CiJobConnection", + "name": "CiGroup", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiJob", + "description": null, + "fields": [ + { + "name": "detailedStatus", + "description": "Detailed status of the job", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "DetailedStatus", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the job", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "needs", + "description": "Builds that must complete before the jobs run", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CiJobConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "scheduledAt", + "description": "Schedule for the build", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiJobConnection", + "description": "The connection type for CiJob.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CiJobEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "CiJob", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CiJobEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "CiJob", "ofType": null }, "isDeprecated": false, @@ -4281,132 +5823,34 @@ "possibleTypes": null }, { - "kind": "OBJECT", - "name": "CiJobConnection", - "description": "The connection type for CiJob.", - "fields": [ - { - "name": "edges", - "description": "A list of edges.", - "args": [ - - ], - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "CiJobEdge", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "nodes", - "description": "A list of nodes.", - "args": [ - - ], - "type": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "CiJob", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "pageInfo", - "description": "Information to aid in pagination.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "OBJECT", - "name": "PageInfo", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - } - ], + "kind": "SCALAR", + "name": "CiPipelineID", + "description": "Identifier of Ci::Pipeline", + "fields": null, "inputFields": null, - "interfaces": [ - - ], + "interfaces": null, "enumValues": null, "possibleTypes": null }, { "kind": "OBJECT", - "name": "CiJobEdge", - "description": "An edge in a connection.", + "name": "CiStage", + "description": null, "fields": [ { - "name": "cursor", - "description": "A cursor for use in pagination.", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "node", - "description": "The item at the end of the edge.", + "name": "detailedStatus", + "description": "Detailed status of the stage", "args": [ ], "type": { "kind": "OBJECT", - "name": "CiJob", + "name": "DetailedStatus", "ofType": null }, "isDeprecated": false, "deprecationReason": null - } - ], - "inputFields": null, - "interfaces": [ - - ], - "enumValues": null, - "possibleTypes": null - }, - { - "kind": "SCALAR", - "name": "CiPipelineID", - "description": "Identifier of Ci::Pipeline", - "fields": null, - "inputFields": null, - "interfaces": null, - "enumValues": null, - "possibleTypes": null - }, - { - "kind": "OBJECT", - "name": "CiStage", - "description": null, - "fields": [ + }, { "name": "groups", "description": "Group of jobs for the stage", @@ -5329,6 +6773,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "ClustersClusterID", + "description": "Identifier of Clusters::Cluster", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "Commit", @@ -6695,7 +8149,7 @@ "description": "The global id of the environment to add an annotation to", "type": { "kind": "SCALAR", - "name": "ID", + "name": "EnvironmentID", "ofType": null }, "defaultValue": null @@ -6705,7 +8159,7 @@ "description": "The global id of the cluster to add an annotation to", "type": { "kind": "SCALAR", - "name": "ID", + "name": "ClustersClusterID", "ofType": null }, "defaultValue": null @@ -6844,6 +8298,172 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "INPUT_OBJECT", + "name": "CreateBoardInput", + "description": "Autogenerated input type of CreateBoard", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project full path the board is associated with.", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "groupPath", + "description": "The group full path the board is associated with.", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "name", + "description": "The board name.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "assigneeId", + "description": "The ID of the user to be assigned to the board.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "milestoneId", + "description": "The ID of the milestone to be assigned to the board.", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "weight", + "description": "The weight of the board.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "labelIds", + "description": "The IDs of labels to be added to the board.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CreateBoardPayload", + "description": "Autogenerated return type of CreateBoard", + "fields": [ + { + "name": "board", + "description": "The board after mutation.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Board", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "INPUT_OBJECT", "name": "CreateBranchInput", @@ -7104,7 +8724,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "NoteableID", "ofType": null } }, @@ -7452,7 +9072,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "NoteableID", "ofType": null } }, @@ -7578,6 +9198,296 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "INPUT_OBJECT", + "name": "CreateIssueInput", + "description": "Autogenerated input type of CreateIssue", + "fields": null, + "inputFields": [ + { + "name": "description", + "description": "Description of the issue", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "dueDate", + "description": "Due date of the issue", + "type": { + "kind": "SCALAR", + "name": "ISO8601Date", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "confidential", + "description": "Indicates the issue is confidential", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "locked", + "description": "Indicates discussion is locked on the issue", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "projectPath", + "description": "Project full path the issue is associated with", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "iid", + "description": "The IID (internal ID) of a project issue. Only admins and project owners can modify", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "title", + "description": "Title of the issue", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "milestoneId", + "description": "The ID of the milestone to assign to the issue. On update milestone will be removed if set to null", + "type": { + "kind": "SCALAR", + "name": "MilestoneID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "labels", + "description": "Labels of the issue", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "labelIds", + "description": "The IDs of labels to be added to the issue", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "LabelID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "createdAt", + "description": "Timestamp when the issue was created. Available only for admins and project owners", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "mergeRequestToResolveDiscussionsOf", + "description": "The IID of a merge request for which to resolve discussions", + "type": { + "kind": "SCALAR", + "name": "MergeRequestID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "discussionToResolve", + "description": "The ID of a discussion to resolve. Also pass `merge_request_to_resolve_discussions_of`", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "assigneeIds", + "description": "The array of user IDs to assign to the issue", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "UserID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "healthStatus", + "description": "The desired health status", + "type": { + "kind": "ENUM", + "name": "HealthStatus", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "weight", + "description": "The weight of the issue", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "epicId", + "description": "The ID of an epic to associate the issue with", + "type": { + "kind": "SCALAR", + "name": "EpicID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "CreateIssuePayload", + "description": "Autogenerated return type of CreateIssue", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "issue", + "description": "The issue after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "INPUT_OBJECT", "name": "CreateIterationInput", @@ -7740,7 +9650,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "NoteableID", "ofType": null } }, @@ -7775,7 +9685,7 @@ "description": "The global id of the discussion this note is in reply to", "type": { "kind": "SCALAR", - "name": "ID", + "name": "DiscussionID", "ofType": null }, "defaultValue": null @@ -7872,19 +9782,25 @@ "name": "title", "description": "Title of the requirement", "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "description", + "description": "Description of the requirement", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null }, "defaultValue": null }, { "name": "projectPath", - "description": "The project full path the requirement is associated with", + "description": "Full project path the requirement is associated with", "type": { "kind": "NON_NULL", "name": null, @@ -7958,7 +9874,7 @@ }, { "name": "requirement", - "description": "The requirement after mutation", + "description": "Requirement after mutation", "args": [ ], @@ -8141,6 +10057,20 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "spam", + "description": "Indicates whether the operation returns a record detected as spam", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -8371,6 +10301,11 @@ "interfaces": null, "enumValues": null, "possibleTypes": [ + { + "kind": "OBJECT", + "name": "BoardEpic", + "ofType": null + }, { "kind": "OBJECT", "name": "Design", @@ -8537,6 +10472,12 @@ "description": "Passive DAST scan. This scan will not make active attacks against the target site.", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "ACTIVE", + "description": "Active DAST scan. This scan will make active attacks against the target site.", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -8610,6 +10551,38 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "scanType", + "description": "Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan.", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "DastScanTypeEnum", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "showDebugMessages", + "description": "Indicates if debug messages should be included in DAST console output. True to include the debug messages.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "spiderTimeout", "description": "The maximum number of minutes allowed for the spider to traverse the site", @@ -8637,6 +10610,24 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "useAjaxSpider", + "description": "Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -8767,6 +10758,36 @@ }, "defaultValue": null }, + { + "name": "scanType", + "description": "Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan.", + "type": { + "kind": "ENUM", + "name": "DastScanTypeEnum", + "ofType": null + }, + "defaultValue": "PASSIVE" + }, + { + "name": "useAjaxSpider", + "description": "Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + }, + { + "name": "showDebugMessages", + "description": "Indicates if debug messages should be included in DAST console output. True to include the debug messages.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + }, { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", @@ -9096,6 +11117,36 @@ }, "defaultValue": null }, + { + "name": "scanType", + "description": "Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan.", + "type": { + "kind": "ENUM", + "name": "DastScanTypeEnum", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "useAjaxSpider", + "description": "Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "showDebugMessages", + "description": "Indicates if debug messages should be included in DAST console output. True to include the debug messages.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", @@ -9839,6 +11890,166 @@ ], "possibleTypes": null }, + { + "kind": "INPUT_OBJECT", + "name": "DastSiteTokenCreateInput", + "description": "Autogenerated input type of DastSiteTokenCreate", + "fields": null, + "inputFields": [ + { + "name": "fullPath", + "description": "The project the site token belongs to.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "targetUrl", + "description": "The URL of the target to be validated.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DastSiteTokenCreatePayload", + "description": "Autogenerated return type of DastSiteTokenCreate", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the site token.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "DastSiteTokenID", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "status", + "description": "The current validation status of the target.", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "DastSiteProfileValidationStatusEnum", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "token", + "description": "Token string.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "DastSiteTokenID", + "description": "Identifier of DastSiteToken", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "SCALAR", + "name": "Date", + "description": "Date represented in ISO 8601", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "INPUT_OBJECT", "name": "DeleteAnnotationInput", @@ -10789,6 +13000,20 @@ "name": "DesignCollection", "description": "A collection of designs", "fields": [ + { + "name": "copyState", + "description": "Copy state of the design collection", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "DesignCollectionCopyState", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "design", "description": "Find a specific design", @@ -11106,6 +13331,35 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "ENUM", + "name": "DesignCollectionCopyState", + "description": "Copy state of a DesignCollection", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "READY", + "description": "The DesignCollection has no copy in progress", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "IN_PROGRESS", + "description": "The DesignCollection is being copied", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "ERROR", + "description": "The DesignCollection encountered an error during a copy", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, { "kind": "OBJECT", "name": "DesignConnection", @@ -12357,6 +14611,108 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "INPUT_OBJECT", + "name": "DestroyBoardListInput", + "description": "Autogenerated input type of DestroyBoardList", + "fields": null, + "inputFields": [ + { + "name": "listId", + "description": "Global ID of the list to destroy. Only label lists are accepted.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ListID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "DestroyBoardListPayload", + "description": "Autogenerated return type of DestroyBoardList", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "list", + "description": "The list after mutation.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "BoardList", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "DestroyBoardPayload", @@ -12438,7 +14794,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "NoteID", "ofType": null } }, @@ -12633,146 +14989,128 @@ "name": "DetailedStatus", "description": null, "fields": [ + { + "name": "action", + "description": "Action information for the status. This includes method, button title, icon, path, and title", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "StatusAction", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "detailsPath", - "description": "Path of the details for the pipeline status", + "description": "Path of the details for the status", "args": [ ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } + "kind": "SCALAR", + "name": "String", + "ofType": null }, "isDeprecated": false, "deprecationReason": null }, { "name": "favicon", - "description": "Favicon of the pipeline status", + "description": "Favicon of the status", "args": [ ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } + "kind": "SCALAR", + "name": "String", + "ofType": null }, "isDeprecated": false, "deprecationReason": null }, { "name": "group", - "description": "Group of the pipeline status", + "description": "Group of the status", "args": [ ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } + "kind": "SCALAR", + "name": "String", + "ofType": null }, "isDeprecated": false, "deprecationReason": null }, { "name": "hasDetails", - "description": "Indicates if the pipeline status has further details", + "description": "Indicates if the status has further details", "args": [ ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "Boolean", - "ofType": null - } + "kind": "SCALAR", + "name": "Boolean", + "ofType": null }, "isDeprecated": false, "deprecationReason": null }, { "name": "icon", - "description": "Icon of the pipeline status", + "description": "Icon of the status", "args": [ ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } + "kind": "SCALAR", + "name": "String", + "ofType": null }, "isDeprecated": false, "deprecationReason": null }, { "name": "label", - "description": "Label of the pipeline status", + "description": "Label of the status", "args": [ ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } + "kind": "SCALAR", + "name": "String", + "ofType": null }, "isDeprecated": false, "deprecationReason": null }, { "name": "text", - "description": "Text of the pipeline status", + "description": "Text of the status", "args": [ ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } + "kind": "SCALAR", + "name": "String", + "ofType": null }, "isDeprecated": false, "deprecationReason": null }, { "name": "tooltip", - "description": "Tooltip associated with the pipeline status", + "description": "Tooltip associated with the status", "args": [ ], "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } + "kind": "SCALAR", + "name": "String", + "ofType": null }, "isDeprecated": false, "deprecationReason": null @@ -13743,6 +16081,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "DiscussionID", + "description": "Identifier of Discussion", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "INPUT_OBJECT", "name": "DiscussionToggleResolveInput", @@ -13757,7 +16105,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "DiscussionID", "ofType": null } }, @@ -13873,7 +16221,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "VulnerabilityID", "ofType": null } }, @@ -14160,7 +16508,7 @@ }, { "name": "latestOpenedMostSevereAlert", - "description": "The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned.", + "description": "The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned", "args": [ ], @@ -14217,6 +16565,20 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "path", + "description": "The path to the environment. Will always return null if `expose_environment_path_in_alert_details` feature flag is disabled", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "state", "description": "State of the environment, for example: available/stopped", @@ -14355,6 +16717,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "EnvironmentID", + "description": "Identifier of Environment", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "Epic", @@ -14384,7 +16756,7 @@ "args": [ { "name": "startDate", - "description": "List items within a time frame where items.start_date is between startDate and endDate parameters (endDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", "type": { "kind": "SCALAR", "name": "Time", @@ -14394,7 +16766,7 @@ }, { "name": "endDate", - "description": "List items within a time frame where items.end_date is between startDate and endDate parameters (startDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", "type": { "kind": "SCALAR", "name": "Time", @@ -14402,6 +16774,16 @@ }, "defaultValue": null }, + { + "name": "timeframe", + "description": "List items overlapping the given timeframe", + "type": { + "kind": "INPUT_OBJECT", + "name": "Timeframe", + "ofType": null + }, + "defaultValue": null + }, { "name": "iid", "description": "IID of the epic, e.g., \"1\"", @@ -14559,7 +16941,7 @@ }, { "name": "closedAt", - "description": "Timestamp of the epic's closure", + "description": "Timestamp of when the epic was closed", "args": [ ], @@ -14587,7 +16969,7 @@ }, { "name": "createdAt", - "description": "Timestamp of the epic's creation", + "description": "Timestamp of when the epic was created", "args": [ ], @@ -15354,7 +17736,7 @@ }, { "name": "updatedAt", - "description": "Timestamp of the epic's last activity", + "description": "Timestamp of when the epic was updated", "args": [ ], @@ -16626,6 +19008,20 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "slaDueAt", + "description": "Timestamp of when the issue SLA expires.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "state", "description": "State of the issue", @@ -17433,7 +19829,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "EpicTreeSortingID", "ofType": null } }, @@ -17444,7 +19840,7 @@ "description": "The id of the epic_issue or issue that the actual epic or issue is switched with", "type": { "kind": "SCALAR", - "name": "ID", + "name": "EpicTreeSortingID", "ofType": null }, "defaultValue": null @@ -17464,7 +19860,7 @@ "description": "ID of the new parent epic", "type": { "kind": "SCALAR", - "name": "ID", + "name": "EpicID", "ofType": null }, "defaultValue": null @@ -17488,7 +19884,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "EpicID", "ofType": null } }, @@ -17576,6 +19972,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "EpicTreeSortingID", + "description": "Identifier of EpicTreeSorting", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "ENUM", "name": "EpicWildcardId", @@ -17688,6 +20094,77 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "mergeRequestDiffRegistries", + "description": "Find merge request diff registries on this Geo node", + "args": [ + { + "name": "ids", + "description": "Filters registries by their ID", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "MergeRequestDiffRegistryConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "minimumReverificationInterval", "description": "The interval (in days) in which the repository verification is valid. Once expired, it will be reverified", @@ -17919,8 +20396,8 @@ "deprecationReason": null }, { - "name": "terraformStateRegistries", - "description": "Find terraform state registries on this Geo node. Available only when feature flag `geo_terraform_state_replication` is enabled", + "name": "terraformStateVersionRegistries", + "description": "Find terraform state version registries on this Geo node", "args": [ { "name": "ids", @@ -17983,74 +20460,323 @@ ], "type": { "kind": "OBJECT", - "name": "TerraformStateRegistryConnection", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "url", - "description": "The user-facing URL for this Geo node", - "args": [ - - ], - "type": { - "kind": "SCALAR", - "name": "String", + "name": "TerraformStateVersionRegistryConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "url", + "description": "The user-facing URL for this Geo node", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "verificationMaxCapacity", + "description": "The maximum concurrency of repository verification for this secondary node", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "GrafanaIntegration", + "description": null, + "fields": [ + { + "name": "createdAt", + "description": "Timestamp of the issue's creation", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "enabled", + "description": "Indicates whether Grafana integration is enabled", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "grafanaUrl", + "description": "URL for the Grafana host for the Grafana integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "Internal ID of the Grafana integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "token", + "description": "API token for the Grafana integration. Deprecated in 12.7: Plain text token has been masked for security reasons", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": true, + "deprecationReason": "Plain text token has been masked for security reasons. Deprecated in 12.7" + }, + { + "name": "updatedAt", + "description": "Timestamp of the issue's last activity", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "Group", + "description": null, + "fields": [ + { + "name": "actualRepositorySizeLimit", + "description": "Size limit for repositories in the namespace in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "additionalPurchasedStorageSize", + "description": "Additional storage purchased for the root namespace in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "autoDevopsEnabled", + "description": "Indicates whether Auto DevOps is enabled for all projects within this group", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "avatarUrl", + "description": "Avatar URL of the group", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "board", + "description": "A single board of the group", + "args": [ + { + "name": "id", + "description": "The board's ID", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "BoardID", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "Board", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "boards", + "description": "Boards of the group", + "args": [ + { + "name": "id", + "description": "Find a board by its ID", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "BoardConnection", "ofType": null }, "isDeprecated": false, "deprecationReason": null }, { - "name": "verificationMaxCapacity", - "description": "The maximum concurrency of repository verification for this secondary node", - "args": [ - - ], - "type": { - "kind": "SCALAR", - "name": "Int", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - } - ], - "inputFields": null, - "interfaces": [ - - ], - "enumValues": null, - "possibleTypes": null - }, - { - "kind": "OBJECT", - "name": "GrafanaIntegration", - "description": null, - "fields": [ - { - "name": "createdAt", - "description": "Timestamp of the issue's creation", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "Time", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "enabled", - "description": "Indicates whether Grafana integration is enabled", + "name": "containsLockedProjects", + "description": "Includes at least one project where the repository size exceeds the limit", "args": [ ], @@ -18066,205 +20792,6 @@ "isDeprecated": false, "deprecationReason": null }, - { - "name": "grafanaUrl", - "description": "URL for the Grafana host for the Grafana integration", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "id", - "description": "Internal ID of the Grafana integration", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "ID", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "token", - "description": "API token for the Grafana integration. Deprecated in 12.7: Plain text token has been masked for security reasons", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "String", - "ofType": null - } - }, - "isDeprecated": true, - "deprecationReason": "Plain text token has been masked for security reasons. Deprecated in 12.7" - }, - { - "name": "updatedAt", - "description": "Timestamp of the issue's last activity", - "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "SCALAR", - "name": "Time", - "ofType": null - } - }, - "isDeprecated": false, - "deprecationReason": null - } - ], - "inputFields": null, - "interfaces": [ - - ], - "enumValues": null, - "possibleTypes": null - }, - { - "kind": "OBJECT", - "name": "Group", - "description": null, - "fields": [ - { - "name": "autoDevopsEnabled", - "description": "Indicates whether Auto DevOps is enabled for all projects within this group", - "args": [ - - ], - "type": { - "kind": "SCALAR", - "name": "Boolean", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "avatarUrl", - "description": "Avatar URL of the group", - "args": [ - - ], - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "board", - "description": "A single board of the group", - "args": [ - { - "name": "id", - "description": "Find a board by its ID", - "type": { - "kind": "SCALAR", - "name": "ID", - "ofType": null - }, - "defaultValue": null - } - ], - "type": { - "kind": "OBJECT", - "name": "Board", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, - { - "name": "boards", - "description": "Boards of the group", - "args": [ - { - "name": "id", - "description": "Find a board by its ID", - "type": { - "kind": "SCALAR", - "name": "ID", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "after", - "description": "Returns the elements in the list that come after the specified cursor.", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "before", - "description": "Returns the elements in the list that come before the specified cursor.", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "first", - "description": "Returns the first _n_ elements from the list.", - "type": { - "kind": "SCALAR", - "name": "Int", - "ofType": null - }, - "defaultValue": null - }, - { - "name": "last", - "description": "Returns the last _n_ elements from the list.", - "type": { - "kind": "SCALAR", - "name": "Int", - "ofType": null - }, - "defaultValue": null - } - ], - "type": { - "kind": "OBJECT", - "name": "BoardConnection", - "ofType": null - }, - "isDeprecated": false, - "deprecationReason": null - }, { "name": "description", "description": "Description of the namespace", @@ -18313,7 +20840,7 @@ "args": [ { "name": "startDate", - "description": "List items within a time frame where items.start_date is between startDate and endDate parameters (endDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", "type": { "kind": "SCALAR", "name": "Time", @@ -18323,7 +20850,7 @@ }, { "name": "endDate", - "description": "List items within a time frame where items.end_date is between startDate and endDate parameters (startDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", "type": { "kind": "SCALAR", "name": "Time", @@ -18331,6 +20858,16 @@ }, "defaultValue": null }, + { + "name": "timeframe", + "description": "List items overlapping the given timeframe", + "type": { + "kind": "INPUT_OBJECT", + "name": "Timeframe", + "ofType": null + }, + "defaultValue": null + }, { "name": "iid", "description": "IID of the epic, e.g., \"1\"", @@ -18452,7 +20989,7 @@ "args": [ { "name": "startDate", - "description": "List items within a time frame where items.start_date is between startDate and endDate parameters (endDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", "type": { "kind": "SCALAR", "name": "Time", @@ -18462,7 +20999,7 @@ }, { "name": "endDate", - "description": "List items within a time frame where items.end_date is between startDate and endDate parameters (startDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", "type": { "kind": "SCALAR", "name": "Time", @@ -18470,6 +21007,16 @@ }, "defaultValue": null }, + { + "name": "timeframe", + "description": "List items overlapping the given timeframe", + "type": { + "kind": "INPUT_OBJECT", + "name": "Timeframe", + "ofType": null + }, + "defaultValue": null + }, { "name": "iid", "description": "IID of the epic, e.g., \"1\"", @@ -18790,7 +21337,7 @@ }, { "name": "issues", - "description": "Issues of the group", + "description": "Issues for projects in this group", "args": [ { "name": "iid", @@ -18848,6 +21395,16 @@ }, "defaultValue": null }, + { + "name": "authorUsername", + "description": "Username of the author of the issue", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, { "name": "assigneeUsername", "description": "Username of a user assigned to the issue", @@ -18858,6 +21415,24 @@ }, "defaultValue": null }, + { + "name": "assigneeUsernames", + "description": "Usernames of users assigned to the issue", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, { "name": "assigneeId", "description": "ID of a user assigned to the issues, \"none\" and \"any\" values supported", @@ -18992,7 +21567,7 @@ }, { "name": "includeSubgroups", - "description": "Include issues belonging to subgroups.", + "description": "Include issues belonging to subgroups", "type": { "kind": "SCALAR", "name": "Boolean", @@ -19055,7 +21630,7 @@ "args": [ { "name": "startDate", - "description": "List items within a time frame where items.start_date is between startDate and endDate parameters (endDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", "type": { "kind": "SCALAR", "name": "Time", @@ -19065,7 +21640,7 @@ }, { "name": "endDate", - "description": "List items within a time frame where items.end_date is between startDate and endDate parameters (startDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", "type": { "kind": "SCALAR", "name": "Time", @@ -19073,6 +21648,16 @@ }, "defaultValue": null }, + { + "name": "timeframe", + "description": "List items overlapping the given timeframe", + "type": { + "kind": "INPUT_OBJECT", + "name": "Timeframe", + "ofType": null + }, + "defaultValue": null + }, { "name": "state", "description": "Filter iterations by state", @@ -19290,13 +21875,218 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "mergeRequests", + "description": "Merge requests for projects in this group", + "args": [ + { + "name": "iids", + "description": "Array of IIDs of merge requests, for example `[1, 2]`", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "sourceBranches", + "description": "Array of source branch names. All resolved merge requests will have one of these branches as their source.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "targetBranches", + "description": "Array of target branch names. All resolved merge requests will have one of these branches as their target.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "state", + "description": "A merge request state. If provided, all resolved merge requests will have this state.", + "type": { + "kind": "ENUM", + "name": "MergeRequestState", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "labels", + "description": "Array of label names. All resolved merge requests will have all of these labels.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "mergedAfter", + "description": "Merge requests merged after this date", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "mergedBefore", + "description": "Merge requests merged before this date", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "milestoneTitle", + "description": "Title of the milestone", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "sort", + "description": "Sort merge requests by this criteria", + "type": { + "kind": "ENUM", + "name": "MergeRequestSort", + "ofType": null + }, + "defaultValue": "created_desc" + }, + { + "name": "includeSubgroups", + "description": "Include merge requests belonging to subgroups", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + }, + { + "name": "assigneeUsername", + "description": "Username of the assignee", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "authorUsername", + "description": "Username of the author", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "MergeRequestConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "milestones", "description": "Milestones of the group", "args": [ { "name": "startDate", - "description": "List items within a time frame where items.start_date is between startDate and endDate parameters (endDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", "type": { "kind": "SCALAR", "name": "Time", @@ -19306,7 +22096,7 @@ }, { "name": "endDate", - "description": "List items within a time frame where items.end_date is between startDate and endDate parameters (startDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", "type": { "kind": "SCALAR", "name": "Time", @@ -19314,6 +22104,16 @@ }, "defaultValue": null }, + { + "name": "timeframe", + "description": "List items overlapping the given timeframe", + "type": { + "kind": "INPUT_OBJECT", + "name": "Timeframe", + "ofType": null + }, + "defaultValue": null + }, { "name": "ids", "description": "Array of global milestone IDs, e.g., \"gid://gitlab/Milestone/1\"", @@ -19342,6 +22142,36 @@ }, "defaultValue": null }, + { + "name": "title", + "description": "The title of the milestone", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "searchTitle", + "description": "A search string for the title", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "containingDate", + "description": "A date that the milestone contains", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, { "name": "includeDescendants", "description": "Also return milestones in all subgroups and subprojects", @@ -19562,6 +22392,24 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "repositorySizeExcessProjectCount", + "description": "Number of projects in the root namespace where the repository size exceeds the limit", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "requestAccessEnabled", "description": "Indicates if users can request access to namespace", @@ -19757,6 +22605,34 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "totalRepositorySize", + "description": "Total repository size of all projects in the root namespace in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "totalRepositorySizeExcess", + "description": "Total excess repository size of all projects in the root namespace in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "twoFactorGracePeriod", "description": "Time before two-factor authentication is enforced", @@ -21904,6 +24780,20 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "slaDueAt", + "description": "Timestamp of when the issue SLA expires.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "state", "description": "State of the issue", @@ -22333,6 +25223,69 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "INPUT_OBJECT", + "name": "IssueMoveInput", + "description": "Autogenerated input type of IssueMove", + "fields": null, + "inputFields": [ + { + "name": "projectPath", + "description": "The project the issue to mutate is in", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "iid", + "description": "The IID of the issue to mutate", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "targetProjectPath", + "description": "The project to move the issue to", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "INPUT_OBJECT", "name": "IssueMoveListInput", @@ -22513,6 +25466,73 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "OBJECT", + "name": "IssueMovePayload", + "description": "Autogenerated return type of IssueMove", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "issue", + "description": "The issue after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "IssuePermissions", @@ -23243,7 +26263,7 @@ "description": "The iteration to assign to the issue.\n", "type": { "kind": "SCALAR", - "name": "ID", + "name": "IterationID", "ofType": null }, "defaultValue": null @@ -23861,23 +26881,47 @@ { "name": "updated_desc", "description": "Updated at descending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5" + }, + { + "name": "updated_asc", + "description": "Updated at ascending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5" + }, + { + "name": "created_desc", + "description": "Created at descending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5" + }, + { + "name": "created_asc", + "description": "Created at ascending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5" + }, + { + "name": "UPDATED_DESC", + "description": "Updated at descending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "updated_asc", + "name": "UPDATED_ASC", "description": "Updated at ascending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "created_desc", + "name": "CREATED_DESC", "description": "Created at descending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "created_asc", + "name": "CREATED_ASC", "description": "Created at ascending order", "isDeprecated": false, "deprecationReason": null @@ -23936,6 +26980,18 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "SEVERITY_ASC", + "description": "Severity from less critical to more critical", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "SEVERITY_DESC", + "description": "Severity from more critical to less critical", + "isDeprecated": false, + "deprecationReason": null + }, { "name": "WEIGHT_ASC", "description": "Weight by ascending order", @@ -23947,6 +27003,18 @@ "description": "Weight by descending order", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "PUBLISHED_ASC", + "description": "Published issues shown last", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "PUBLISHED_DESC", + "description": "Published issues shown first", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -23986,6 +27054,29 @@ ], "possibleTypes": null }, + { + "kind": "ENUM", + "name": "IssueStateEvent", + "description": "Values for issue state events", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "REOPEN", + "description": "Reopens the issue", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "CLOSE", + "description": "Closes the issue", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, { "kind": "OBJECT", "name": "IssueStatusCountsType", @@ -25554,6 +28645,24 @@ "name": "LabelConnection", "description": "The connection type for Label.", "fields": [ + { + "name": "count", + "description": "Total count of collection", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "edges", "description": "A list of edges.", @@ -25671,6 +28780,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "ListID", + "description": "Identifier of List", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "ENUM", "name": "ListLimitMetric", @@ -25845,6 +28964,30 @@ "description": "Pipeline count", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "PIPELINES_SUCCEEDED", + "description": "Pipeline count with success status", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "PIPELINES_FAILED", + "description": "Pipeline count with failed status", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "PIPELINES_CANCELED", + "description": "Pipeline count with canceled status", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "PIPELINES_SKIPPED", + "description": "Pipeline count with skipped status", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -27830,6 +30973,251 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "OBJECT", + "name": "MergeRequestDiffRegistry", + "description": "Represents the Geo sync and verification state of a Merge Request diff", + "fields": [ + { + "name": "createdAt", + "description": "Timestamp when the MergeRequestDiffRegistry was created", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the MergeRequestDiffRegistry", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lastSyncFailure", + "description": "Error message during sync of the MergeRequestDiffRegistry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lastSyncedAt", + "description": "Timestamp of the most recent successful sync of the MergeRequestDiffRegistry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "mergeRequestDiffId", + "description": "ID of the Merge Request diff", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "retryAt", + "description": "Timestamp after which the MergeRequestDiffRegistry should be resynced", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "retryCount", + "description": "Number of consecutive failed sync attempts of the MergeRequestDiffRegistry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "state", + "description": "Sync state of the MergeRequestDiffRegistry", + "args": [ + + ], + "type": { + "kind": "ENUM", + "name": "RegistryState", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "MergeRequestDiffRegistryConnection", + "description": "The connection type for MergeRequestDiffRegistry.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "MergeRequestDiffRegistryEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "MergeRequestDiffRegistry", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "MergeRequestDiffRegistryEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "MergeRequestDiffRegistry", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "MergeRequestEdge", @@ -27875,6 +31263,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "MergeRequestID", + "description": "Identifier of MergeRequest", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "MergeRequestPermissions", @@ -28515,7 +31913,7 @@ "description": "The milestone to assign to the merge request.\n", "type": { "kind": "SCALAR", - "name": "ID", + "name": "MilestoneID", "ofType": null }, "defaultValue": null @@ -28873,23 +32271,47 @@ { "name": "updated_desc", "description": "Updated at descending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5" + }, + { + "name": "updated_asc", + "description": "Updated at ascending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5" + }, + { + "name": "created_desc", + "description": "Created at descending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5" + }, + { + "name": "created_asc", + "description": "Created at ascending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5" + }, + { + "name": "UPDATED_DESC", + "description": "Updated at descending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "updated_asc", + "name": "UPDATED_ASC", "description": "Updated at ascending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "created_desc", + "name": "CREATED_DESC", "description": "Created at descending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "created_asc", + "name": "CREATED_ASC", "description": "Created at ascending order", "isDeprecated": false, "deprecationReason": null @@ -30436,6 +33858,33 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "createBoard", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "CreateBoardInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CreateBoardPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "createBranch", "description": null, @@ -30571,6 +34020,33 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "createIssue", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "CreateIssueInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "CreateIssuePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "createIteration", "description": null, @@ -30895,6 +34371,33 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "dastSiteTokenCreate", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DastSiteTokenCreateInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DastSiteTokenCreatePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "deleteAnnotation", "description": null, @@ -31030,6 +34533,33 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "destroyBoardList", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "DestroyBoardListInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "DestroyBoardListPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "destroyNote", "description": null, @@ -31135,8 +34665,8 @@ "name": "DismissVulnerabilityPayload", "ofType": null }, - "isDeprecated": false, - "deprecationReason": null + "isDeprecated": true, + "deprecationReason": "Use vulnerabilityDismiss. Deprecated in 13.5" }, { "name": "epicAddIssue", @@ -31219,6 +34749,33 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "issueMove", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "IssueMoveInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "IssueMovePayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "issueMoveList", "description": null, @@ -31948,6 +35505,33 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "revertVulnerabilityToDetected", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "RevertVulnerabilityToDetectedInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "RevertVulnerabilityToDetectedPayload", + "ofType": null + }, + "isDeprecated": true, + "deprecationReason": "Use vulnerabilityRevertToDetected. Deprecated in 13.5" + }, { "name": "runDastScan", "description": null, @@ -32164,6 +35748,33 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "updateBoardEpicUserPreferences", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "UpdateBoardEpicUserPreferencesInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "UpdateBoardEpicUserPreferencesPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "updateBoardList", "description": null, @@ -32407,6 +36018,60 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "vulnerabilityConfirm", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityConfirmInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilityConfirmPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "vulnerabilityDismiss", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityDismissInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilityDismissPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "vulnerabilityResolve", "description": null, @@ -32433,6 +36098,33 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "vulnerabilityRevertToDetected", + "description": null, + "args": [ + { + "name": "input", + "description": null, + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityRevertToDetectedInput", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "VulnerabilityRevertToDetectedPayload", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -32476,6 +36168,52 @@ "name": "Namespace", "description": null, "fields": [ + { + "name": "actualRepositorySizeLimit", + "description": "Size limit for repositories in the namespace in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "additionalPurchasedStorageSize", + "description": "Additional storage purchased for the root namespace in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "containsLockedProjects", + "description": "Includes at least one project where the repository size exceeds the limit", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "description", "description": "Description of the namespace", @@ -32723,6 +36461,24 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "repositorySizeExcessProjectCount", + "description": "Number of projects in the root namespace where the repository size exceeds the limit", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "requestAccessEnabled", "description": "Indicates if users can request access to namespace", @@ -32779,6 +36535,34 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "totalRepositorySize", + "description": "Total repository size of all projects in the root namespace in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "totalRepositorySizeExcess", + "description": "Total excess repository size of all projects in the root namespace in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "visibility", "description": "Visibility of the namespace", @@ -32913,6 +36697,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "NamespaceID", + "description": "Identifier of Namespace", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "INPUT_OBJECT", "name": "NamespaceIncreaseStorageTemporarilyInput", @@ -32927,7 +36721,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "NamespaceID", "ofType": null } }, @@ -33534,6 +37328,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "NoteID", + "description": "Identifier of Note", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "NotePermissions", @@ -33766,6 +37570,11 @@ "name": "AlertManagementAlert", "ofType": null }, + { + "kind": "OBJECT", + "name": "BoardEpic", + "ofType": null + }, { "kind": "OBJECT", "name": "Design", @@ -33795,9 +37604,24 @@ "kind": "OBJECT", "name": "Snippet", "ofType": null + }, + { + "kind": "OBJECT", + "name": "Vulnerability", + "ofType": null } ] }, + { + "kind": "SCALAR", + "name": "NoteableID", + "description": "Identifier of Noteable", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "Package", @@ -34030,7 +37854,7 @@ { "kind": "OBJECT", "name": "PackageFileRegistry", - "description": "Represents the sync and verification state of a package file", + "description": "Represents the Geo sync and verification state of a package file", "fields": [ { "name": "createdAt", @@ -34282,43 +38106,55 @@ "enumValues": [ { "name": "MAVEN", - "description": "Packages from the maven package manager", + "description": "Packages from the Maven package manager", "isDeprecated": false, "deprecationReason": null }, { "name": "NPM", - "description": "Packages from the npm package manager", + "description": "Packages from the NPM package manager", "isDeprecated": false, "deprecationReason": null }, { "name": "CONAN", - "description": "Packages from the conan package manager", + "description": "Packages from the Conan package manager", "isDeprecated": false, "deprecationReason": null }, { "name": "NUGET", - "description": "Packages from the nuget package manager", + "description": "Packages from the Nuget package manager", "isDeprecated": false, "deprecationReason": null }, { "name": "PYPI", - "description": "Packages from the pypi package manager", + "description": "Packages from the PyPI package manager", "isDeprecated": false, "deprecationReason": null }, { "name": "COMPOSER", - "description": "Packages from the composer package manager", + "description": "Packages from the Composer package manager", "isDeprecated": false, "deprecationReason": null }, { "name": "GENERIC", - "description": "Packages from the generic package manager", + "description": "Packages from the Generic package manager", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "GOLANG", + "description": "Packages from the Golang package manager", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DEBIAN", + "description": "Packages from the Debian package manager", "isDeprecated": false, "deprecationReason": null } @@ -35390,6 +39226,20 @@ "name": "Project", "description": null, "fields": [ + { + "name": "actualRepositorySizeLimit", + "description": "Size limit for the repository in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "alertManagementAlert", "description": "A single Alert Management alert of the project", @@ -35441,6 +39291,16 @@ "ofType": null }, "defaultValue": null + }, + { + "name": "assigneeUsername", + "description": "Username of a user assigned to the issue", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null } ], "type": { @@ -35464,6 +39324,16 @@ "ofType": null }, "defaultValue": null + }, + { + "name": "assigneeUsername", + "description": "Username of a user assigned to the issue", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null } ], "type": { @@ -35526,6 +39396,16 @@ }, "defaultValue": null }, + { + "name": "assigneeUsername", + "description": "Username of a user assigned to the issue", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", @@ -35637,11 +39517,15 @@ "args": [ { "name": "id", - "description": "Find a board by its ID", + "description": "The board's ID", "type": { - "kind": "SCALAR", - "name": "ID", - "ofType": null + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "BoardID", + "ofType": null + } }, "defaultValue": null } @@ -36365,6 +40249,16 @@ }, "defaultValue": null }, + { + "name": "authorUsername", + "description": "Username of the author of the issue", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, { "name": "assigneeUsername", "description": "Username of a user assigned to the issue", @@ -36375,6 +40269,24 @@ }, "defaultValue": null }, + { + "name": "assigneeUsernames", + "description": "Usernames of users assigned to the issue", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, { "name": "assigneeId", "description": "ID of a user assigned to the issues, \"none\" and \"any\" values supported", @@ -36576,6 +40488,16 @@ }, "defaultValue": null }, + { + "name": "authorUsername", + "description": "Username of the author of the issue", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, { "name": "assigneeUsername", "description": "Username of a user assigned to the issue", @@ -36586,6 +40508,24 @@ }, "defaultValue": null }, + { + "name": "assigneeUsernames", + "description": "Usernames of users assigned to the issue", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, { "name": "assigneeId", "description": "ID of a user assigned to the issues, \"none\" and \"any\" values supported", @@ -36753,6 +40693,16 @@ }, "defaultValue": null }, + { + "name": "authorUsername", + "description": "Username of the author of the issue", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, { "name": "assigneeUsername", "description": "Username of a user assigned to the issue", @@ -36763,6 +40713,24 @@ }, "defaultValue": null }, + { + "name": "assigneeUsernames", + "description": "Usernames of users assigned to the issue", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, { "name": "assigneeId", "description": "ID of a user assigned to the issues, \"none\" and \"any\" values supported", @@ -36964,7 +40932,7 @@ "args": [ { "name": "startDate", - "description": "List items within a time frame where items.start_date is between startDate and endDate parameters (endDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", "type": { "kind": "SCALAR", "name": "Time", @@ -36974,7 +40942,7 @@ }, { "name": "endDate", - "description": "List items within a time frame where items.end_date is between startDate and endDate parameters (startDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", "type": { "kind": "SCALAR", "name": "Time", @@ -36982,6 +40950,16 @@ }, "defaultValue": null }, + { + "name": "timeframe", + "description": "List items overlapping the given timeframe", + "type": { + "kind": "INPUT_OBJECT", + "name": "Timeframe", + "ofType": null + }, + "defaultValue": null + }, { "name": "state", "description": "Filter iterations by state", @@ -37536,7 +41514,7 @@ "args": [ { "name": "startDate", - "description": "List items within a time frame where items.start_date is between startDate and endDate parameters (endDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.start", "type": { "kind": "SCALAR", "name": "Time", @@ -37546,7 +41524,7 @@ }, { "name": "endDate", - "description": "List items within a time frame where items.end_date is between startDate and endDate parameters (startDate parameter must be present)", + "description": "List items overlapping a time frame defined by startDate..endDate (if one date is provided, both must be present). Deprecated in 13.5: Use timeframe.end", "type": { "kind": "SCALAR", "name": "Time", @@ -37554,6 +41532,16 @@ }, "defaultValue": null }, + { + "name": "timeframe", + "description": "List items overlapping the given timeframe", + "type": { + "kind": "INPUT_OBJECT", + "name": "Timeframe", + "ofType": null + }, + "defaultValue": null + }, { "name": "ids", "description": "Array of global milestone IDs, e.g., \"gid://gitlab/Milestone/1\"", @@ -37582,6 +41570,36 @@ }, "defaultValue": null }, + { + "name": "title", + "description": "The title of the milestone", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "searchTitle", + "description": "A search string for the title", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "containingDate", + "description": "A date that the milestone contains", + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "defaultValue": null + }, { "name": "includeAncestors", "description": "Also return milestones in the project's parent group and its ancestors", @@ -38113,6 +42131,20 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "repositorySizeExcess", + "description": "Size of repository that exceeds the limit in bytes", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "requestAccessEnabled", "description": "Indicates if users can request member access to the project", @@ -38129,7 +42161,7 @@ }, { "name": "requirement", - "description": "Find a single requirement. Available only when feature flag `requirements_management` is enabled.", + "description": "Find a single requirement", "args": [ { "name": "iid", @@ -38232,7 +42264,7 @@ }, { "name": "requirements", - "description": "Find requirements. Available only when feature flag `requirements_management` is enabled.", + "description": "Find requirements", "args": [ { "name": "iid", @@ -38726,6 +42758,59 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "terraformStates", + "description": "Terraform states associated with the project", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "TerraformStateConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "userPermissions", "description": "Permissions for the current user on the resource", @@ -39316,6 +43401,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "ProjectID", + "description": "Identifier of Project", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "ProjectMember", @@ -40981,6 +45076,26 @@ }, "defaultValue": null }, + { + "name": "searchNamespaces", + "description": "Include namespace in project search", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "sort", + "description": "Sort order of results", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", @@ -41030,6 +45145,59 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "runnerPlatforms", + "description": "Supported runner platforms", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "RunnerPlatformConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "snippets", "description": "Find Snippets visible to the current user", @@ -41617,6 +45785,33 @@ }, "isDeprecated": true, "deprecationReason": "Use `vulnerabilitiesCountByDay`. Deprecated in 13.3" + }, + { + "name": "vulnerability", + "description": "Find a vulnerability", + "args": [ + { + "name": "id", + "description": "The Global ID of the Vulnerability", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "VulnerabilityID", + "ofType": null + } + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "Vulnerability", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -42880,7 +47075,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "AwardableID", "ofType": null } }, @@ -42996,7 +47191,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "ProjectID", "ofType": null } }, @@ -43217,6 +47412,34 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "description", + "description": "Description of the requirement", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "descriptionHtml", + "description": "The GitLab Flavored Markdown rendering of `description`", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "id", "description": "ID of the requirement", @@ -43253,6 +47476,20 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "lastTestReportManuallyCreated", + "description": "Indicates if latest test report was created by user", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "lastTestReportState", "description": "Latest requirement test report state", @@ -43380,6 +47617,20 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "titleHtml", + "description": "The GitLab Flavored Markdown rendering of `title`", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "updatedAt", "description": "Timestamp of when the requirement was last updated", @@ -43789,6 +48040,108 @@ } ] }, + { + "kind": "INPUT_OBJECT", + "name": "RevertVulnerabilityToDetectedInput", + "description": "Autogenerated input type of RevertVulnerabilityToDetected", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the vulnerability to be reverted", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "VulnerabilityID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "RevertVulnerabilityToDetectedPayload", + "description": "Autogenerated return type of RevertVulnerabilityToDetected", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "vulnerability", + "description": "The vulnerability after revert", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Vulnerability", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "RootStorageStatistics", @@ -43848,6 +48201,24 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "pipelineArtifactsSize", + "description": "The CI pipeline artifacts size in bytes", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Float", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "repositorySize", "description": "The Git repository size in bytes", @@ -44072,6 +48443,381 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "OBJECT", + "name": "RunnerArchitecture", + "description": null, + "fields": [ + { + "name": "downloadLocation", + "description": "Download location for the runner for the platform architecture", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the runner platform architecture", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "RunnerArchitectureConnection", + "description": "The connection type for RunnerArchitecture.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "RunnerArchitectureEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "RunnerArchitecture", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "RunnerArchitectureEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "RunnerArchitecture", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "RunnerPlatform", + "description": null, + "fields": [ + { + "name": "architectures", + "description": "Runner architectures supported for the platform", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "RunnerArchitectureConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "humanReadableName", + "description": "Human readable name of the runner platform", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name slug of the runner platform", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "RunnerPlatformConnection", + "description": "The connection type for RunnerPlatform.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "RunnerPlatformEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "RunnerPlatform", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "RunnerPlatformEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "RunnerPlatform", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "SastCiConfiguration", @@ -44478,6 +49224,63 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "INPUT_OBJECT", + "name": "SastCiConfigurationAnalyzersEntityInput", + "description": "Represents the analyzers entity in SAST CI configuration", + "fields": null, + "inputFields": [ + { + "name": "name", + "description": "Name of analyzer", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "enabled", + "description": "State of the analyzer", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "variables", + "description": "List of variables for the analyzer", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "SastCiConfigurationEntityInput", + "ofType": null + } + } + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "SastCiConfigurationEntity", @@ -44848,6 +49651,24 @@ } }, "defaultValue": null + }, + { + "name": "analyzers", + "description": "List of analyzers and related variables for the SAST configuration", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "SastCiConfigurationAnalyzersEntityInput", + "ofType": null + } + } + }, + "defaultValue": null } ], "interfaces": null, @@ -45194,6 +50015,20 @@ "name": "SecurityReportSummary", "description": "Represents summary of a security report", "fields": [ + { + "name": "apiFuzzing", + "description": "Aggregated counts for the api_fuzzing scan", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "SecurityReportSummarySection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "containerScanning", "description": "Aggregated counts for the container_scanning scan", @@ -45437,6 +50272,12 @@ "description": null, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "API_FUZZING", + "description": null, + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -47364,24 +52205,69 @@ "name": "blobs", "description": "Snippet blobs", "args": [ - - ], - "type": { - "kind": "NON_NULL", - "name": null, - "ofType": { - "kind": "LIST", - "name": null, - "ofType": { - "kind": "NON_NULL", + { + "name": "paths", + "description": "Paths of the blobs", + "type": { + "kind": "LIST", "name": null, "ofType": { - "kind": "OBJECT", - "name": "SnippetBlob", - "ofType": null + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } } - } + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null } + ], + "type": { + "kind": "OBJECT", + "name": "SnippetBlobConnection", + "ofType": null }, "isDeprecated": false, "deprecationReason": null @@ -48035,6 +52921,118 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "OBJECT", + "name": "SnippetBlobConnection", + "description": "The connection type for SnippetBlob.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "SnippetBlobEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "SnippetBlob", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "SnippetBlobEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "SnippetBlob", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "SnippetBlobViewer", @@ -48414,23 +53412,47 @@ { "name": "updated_desc", "description": "Updated at descending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_DESC. Deprecated in 13.5" + }, + { + "name": "updated_asc", + "description": "Updated at ascending order", + "isDeprecated": true, + "deprecationReason": "Use UPDATED_ASC. Deprecated in 13.5" + }, + { + "name": "created_desc", + "description": "Created at descending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_DESC. Deprecated in 13.5" + }, + { + "name": "created_asc", + "description": "Created at ascending order", + "isDeprecated": true, + "deprecationReason": "Use CREATED_ASC. Deprecated in 13.5" + }, + { + "name": "UPDATED_DESC", + "description": "Updated at descending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "updated_asc", + "name": "UPDATED_ASC", "description": "Updated at ascending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "created_desc", + "name": "CREATED_DESC", "description": "Created at descending order", "isDeprecated": false, "deprecationReason": null }, { - "name": "created_asc", + "name": "CREATED_ASC", "description": "Created at ascending order", "isDeprecated": false, "deprecationReason": null @@ -48438,6 +53460,89 @@ ], "possibleTypes": null }, + { + "kind": "OBJECT", + "name": "StatusAction", + "description": null, + "fields": [ + { + "name": "buttonTitle", + "description": "Title for the button, for example: Retry this job", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "icon", + "description": "Icon used in the action button", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "method", + "description": "Method for the action, for example: :post", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "path", + "description": "Path for the action", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "title", + "description": "Title for the action, for example: Retry", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "SCALAR", "name": "String", @@ -48764,12 +53869,237 @@ }, { "kind": "OBJECT", - "name": "TerraformStateRegistry", - "description": "Represents the sync and verification state of a terraform state", + "name": "TerraformState", + "description": null, + "fields": [ + { + "name": "createdAt", + "description": "Timestamp the Terraform state was created", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "ID of the Terraform state", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lockedAt", + "description": "Timestamp the Terraform state was locked", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "lockedByUser", + "description": "The user currently holding a lock on the Terraform state", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "User", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Name of the Terraform state", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updatedAt", + "description": "Timestamp the Terraform state was updated", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TerraformStateConnection", + "description": "The connection type for TerraformState.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TerraformStateEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "TerraformState", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TerraformStateEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "TerraformState", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "TerraformStateVersionRegistry", + "description": "Represents the Geo sync and verification state of a terraform state version", "fields": [ { "name": "createdAt", - "description": "Timestamp when the TerraformStateRegistry was created", + "description": "Timestamp when the TerraformStateVersionRegistry was created", "args": [ ], @@ -48783,7 +54113,7 @@ }, { "name": "id", - "description": "ID of the TerraformStateRegistry", + "description": "ID of the TerraformStateVersionRegistry", "args": [ ], @@ -48801,7 +54131,7 @@ }, { "name": "lastSyncFailure", - "description": "Error message during sync of the TerraformStateRegistry", + "description": "Error message during sync of the TerraformStateVersionRegistry", "args": [ ], @@ -48815,7 +54145,7 @@ }, { "name": "lastSyncedAt", - "description": "Timestamp of the most recent successful sync of the TerraformStateRegistry", + "description": "Timestamp of the most recent successful sync of the TerraformStateVersionRegistry", "args": [ ], @@ -48829,7 +54159,7 @@ }, { "name": "retryAt", - "description": "Timestamp after which the TerraformStateRegistry should be resynced", + "description": "Timestamp after which the TerraformStateVersionRegistry should be resynced", "args": [ ], @@ -48843,7 +54173,7 @@ }, { "name": "retryCount", - "description": "Number of consecutive failed sync attempts of the TerraformStateRegistry", + "description": "Number of consecutive failed sync attempts of the TerraformStateVersionRegistry", "args": [ ], @@ -48857,7 +54187,7 @@ }, { "name": "state", - "description": "Sync state of the TerraformStateRegistry", + "description": "Sync state of the TerraformStateVersionRegistry", "args": [ ], @@ -48870,8 +54200,8 @@ "deprecationReason": null }, { - "name": "terraformStateId", - "description": "ID of the TerraformState", + "name": "terraformStateVersionId", + "description": "ID of the terraform state version", "args": [ ], @@ -48897,8 +54227,8 @@ }, { "kind": "OBJECT", - "name": "TerraformStateRegistryConnection", - "description": "The connection type for TerraformStateRegistry.", + "name": "TerraformStateVersionRegistryConnection", + "description": "The connection type for TerraformStateVersionRegistry.", "fields": [ { "name": "edges", @@ -48911,7 +54241,7 @@ "name": null, "ofType": { "kind": "OBJECT", - "name": "TerraformStateRegistryEdge", + "name": "TerraformStateVersionRegistryEdge", "ofType": null } }, @@ -48929,7 +54259,7 @@ "name": null, "ofType": { "kind": "OBJECT", - "name": "TerraformStateRegistry", + "name": "TerraformStateVersionRegistry", "ofType": null } }, @@ -48964,7 +54294,7 @@ }, { "kind": "OBJECT", - "name": "TerraformStateRegistryEdge", + "name": "TerraformStateVersionRegistryEdge", "description": "An edge in a connection.", "fields": [ { @@ -48993,7 +54323,7 @@ ], "type": { "kind": "OBJECT", - "name": "TerraformStateRegistry", + "name": "TerraformStateVersionRegistry", "ofType": null }, "isDeprecated": false, @@ -49277,6 +54607,45 @@ } ] }, + { + "kind": "INPUT_OBJECT", + "name": "Timeframe", + "description": "A time-frame defined as a closed inclusive range of two dates", + "fields": null, + "inputFields": [ + { + "name": "start", + "description": "The start of the range", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Date", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "end", + "description": "The end of the range", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Date", + "ofType": null + } + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "Timelog", @@ -49830,6 +55199,16 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "SCALAR", + "name": "TodoID", + "description": "Identifier of Todo", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, { "kind": "INPUT_OBJECT", "name": "TodoMarkDoneInput", @@ -49844,7 +55223,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "TodoID", "ofType": null } }, @@ -49950,7 +55329,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "TodoID", "ofType": null } }, @@ -49991,7 +55370,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "TodoID", "ofType": null } } @@ -50400,7 +55779,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "AwardableID", "ofType": null } }, @@ -51174,6 +56553,136 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "INPUT_OBJECT", + "name": "UpdateBoardEpicUserPreferencesInput", + "description": "Autogenerated input type of UpdateBoardEpicUserPreferences", + "fields": null, + "inputFields": [ + { + "name": "boardId", + "description": "The board global ID", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "BoardID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "epicId", + "description": "ID of an epic to set preferences for", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "EpicID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "collapsed", + "description": "Whether the epic should be collapsed in the board", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "UpdateBoardEpicUserPreferencesPayload", + "description": "Autogenerated return type of UpdateBoardEpicUserPreferences", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "epicUserPreferences", + "description": "User preferences for the epic in the board after mutation", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "BoardEpicUserPreferences", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "INPUT_OBJECT", "name": "UpdateBoardInput", @@ -51188,7 +56697,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "BoardID", "ofType": null } }, @@ -51229,7 +56738,7 @@ "description": "The id of user to be assigned to the board.", "type": { "kind": "SCALAR", - "name": "ID", + "name": "UserID", "ofType": null }, "defaultValue": null @@ -51239,7 +56748,7 @@ "description": "The id of milestone to be assigned to the board.", "type": { "kind": "SCALAR", - "name": "ID", + "name": "MilestoneID", "ofType": null }, "defaultValue": null @@ -51254,6 +56763,42 @@ }, "defaultValue": null }, + { + "name": "labels", + "description": "Labels of the issue", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + }, + "defaultValue": null + }, + { + "name": "labelIds", + "description": "The IDs of labels to be added to the board.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "LabelID", + "ofType": null + } + } + }, + "defaultValue": null + }, { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", @@ -51917,7 +57462,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "NoteID", "ofType": null } }, @@ -52059,16 +57604,6 @@ }, "defaultValue": null }, - { - "name": "title", - "description": "Title of the issue", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "defaultValue": null - }, { "name": "description", "description": "Description of the issue", @@ -52084,7 +57619,7 @@ "description": "Due date of the issue", "type": { "kind": "SCALAR", - "name": "Time", + "name": "ISO8601Date", "ofType": null }, "defaultValue": null @@ -52109,9 +57644,29 @@ }, "defaultValue": null }, + { + "name": "title", + "description": "Title of the issue", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "milestoneId", + "description": "The ID of the milestone to assign to the issue. On update milestone will be removed if set to null", + "type": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + }, + "defaultValue": null + }, { "name": "addLabelIds", - "description": "The IDs of labels to be added to the issue.", + "description": "The IDs of labels to be added to the issue", "type": { "kind": "LIST", "name": null, @@ -52129,7 +57684,7 @@ }, { "name": "removeLabelIds", - "description": "The IDs of labels to be removed from the issue.", + "description": "The IDs of labels to be removed from the issue", "type": { "kind": "LIST", "name": null, @@ -52146,11 +57701,11 @@ "defaultValue": null }, { - "name": "milestoneId", - "description": "The ID of the milestone to be assigned, milestone will be removed if set to null.", + "name": "stateEvent", + "description": "Close or reopen an issue", "type": { - "kind": "SCALAR", - "name": "ID", + "kind": "ENUM", + "name": "IssueStateEvent", "ofType": null }, "defaultValue": null @@ -52165,6 +57720,16 @@ }, "defaultValue": null }, + { + "name": "weight", + "description": "The weight of the issue", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, { "name": "epicId", "description": "The ID of the parent epic. NULL when removing the association", @@ -52427,7 +57992,7 @@ "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "NoteID", "ofType": null } }, @@ -52552,38 +58117,48 @@ "defaultValue": null }, { - "name": "state", - "description": "State of the requirement", + "name": "description", + "description": "Description of the requirement", "type": { - "kind": "ENUM", - "name": "RequirementState", + "kind": "SCALAR", + "name": "String", "ofType": null }, "defaultValue": null }, { - "name": "iid", - "description": "The iid of the requirement to update", + "name": "projectPath", + "description": "Full project path the requirement is associated with", "type": { "kind": "NON_NULL", "name": null, "ofType": { "kind": "SCALAR", - "name": "String", + "name": "ID", "ofType": null } }, "defaultValue": null }, { - "name": "projectPath", - "description": "The project full path the requirement is associated with", + "name": "state", + "description": "State of the requirement", + "type": { + "kind": "ENUM", + "name": "RequirementState", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "iid", + "description": "The iid of the requirement to update", "type": { "kind": "NON_NULL", "name": null, "ofType": { "kind": "SCALAR", - "name": "ID", + "name": "String", "ofType": null } }, @@ -52661,7 +58236,7 @@ }, { "name": "requirement", - "description": "The requirement after mutation", + "description": "Requirement after mutation", "args": [ ], @@ -52822,6 +58397,20 @@ }, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "spam", + "description": "Indicates whether the operation returns a record detected as spam", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null } ], "inputFields": null, @@ -52992,6 +58581,16 @@ }, "defaultValue": null }, + { + "name": "authorUsername", + "description": "Username of the author", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", @@ -53187,6 +58786,16 @@ }, "defaultValue": null }, + { + "name": "assigneeUsername", + "description": "Username of the assignee", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", @@ -54605,6 +60214,63 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "discussions", + "description": "All discussions on this noteable", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DiscussionConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "id", "description": "GraphQL ID of the vulnerability", @@ -54730,6 +60396,63 @@ "isDeprecated": false, "deprecationReason": null }, + { + "name": "notes", + "description": "All notes on this noteable", + "args": [ + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "NoteConnection", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, { "name": "primaryIdentifier", "description": "Primary identifier of the vulnerability.", @@ -54760,7 +60483,7 @@ }, { "name": "reportType", - "description": "Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING)", + "description": "Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING)", "args": [ ], @@ -54820,7 +60543,7 @@ }, { "name": "state", - "description": "State of the vulnerability (DETECTED, DISMISSED, RESOLVED, CONFIRMED)", + "description": "State of the vulnerability (DETECTED, CONFIRMED, RESOLVED, DISMISSED)", "args": [ ], @@ -54898,6 +60621,112 @@ } ], "inputFields": null, + "interfaces": [ + { + "kind": "INTERFACE", + "name": "Noteable", + "ofType": null + } + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityConfirmInput", + "description": "Autogenerated input type of VulnerabilityConfirm", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the vulnerability to be confirmed", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "VulnerabilityID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityConfirmPayload", + "description": "Autogenerated return type of VulnerabilityConfirm", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "vulnerability", + "description": "The vulnerability after state change", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Vulnerability", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, "interfaces": [ ], @@ -54971,6 +60800,118 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityDismissInput", + "description": "Autogenerated input type of VulnerabilityDismiss", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the vulnerability to be dismissed", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "VulnerabilityID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "comment", + "description": "Reason why vulnerability should be dismissed", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityDismissPayload", + "description": "Autogenerated return type of VulnerabilityDismiss", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "vulnerability", + "description": "The vulnerability after dismissal", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Vulnerability", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "VulnerabilityEdge", @@ -55993,6 +61934,12 @@ "description": null, "isDeprecated": false, "deprecationReason": null + }, + { + "name": "API_FUZZING", + "description": null, + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -56005,7 +61952,7 @@ "inputFields": [ { "name": "id", - "description": "ID of the vulnerability to be resolveed", + "description": "ID of the vulnerability to be resolved", "type": { "kind": "NON_NULL", "name": null, @@ -56099,6 +62046,108 @@ "enumValues": null, "possibleTypes": null }, + { + "kind": "INPUT_OBJECT", + "name": "VulnerabilityRevertToDetectedInput", + "description": "Autogenerated input type of VulnerabilityRevertToDetected", + "fields": null, + "inputFields": [ + { + "name": "id", + "description": "ID of the vulnerability to be reverted", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "VulnerabilityID", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "VulnerabilityRevertToDetectedPayload", + "description": "Autogenerated return type of VulnerabilityRevertToDetected", + "fields": [ + { + "name": "clientMutationId", + "description": "A unique identifier for the client performing the mutation.", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "errors", + "description": "Errors encountered during execution of the mutation.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "vulnerability", + "description": "The vulnerability after revert", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Vulnerability", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, { "kind": "OBJECT", "name": "VulnerabilityScanner", @@ -56443,6 +62492,54 @@ "description": "Severity in ascending order", "isDeprecated": false, "deprecationReason": null + }, + { + "name": "title_desc", + "description": "Title in descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "title_asc", + "description": "Title in ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "detected_desc", + "description": "Detection timestamp in descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "detected_asc", + "description": "Detection timestamp in ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "report_type_desc", + "description": "Report Type in descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "report_type_asc", + "description": "Report Type in ascending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "state_desc", + "description": "State in descending order", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "state_asc", + "description": "State in ascending order", + "isDeprecated": false, + "deprecationReason": null } ], "possibleTypes": null @@ -56462,7 +62559,7 @@ "deprecationReason": null }, { - "name": "DISMISSED", + "name": "CONFIRMED", "description": null, "isDeprecated": false, "deprecationReason": null @@ -56474,7 +62571,7 @@ "deprecationReason": null }, { - "name": "CONFIRMED", + "name": "DISMISSED", "description": null, "isDeprecated": false, "deprecationReason": null diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index fc27298aff2..dca00fc1286 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -77,6 +77,7 @@ Describes an alert from the project's Alert Management. | `details` | JSON | Alert details | | `detailsUrl` | String! | The URL of the alert detail page | | `endedAt` | Time | Timestamp the alert ended | +| `environment` | Environment | Environment for the alert | | `eventCount` | Int | Number of events of this alert | | `hosts` | String! => Array | List of hosts the alert came from | | `iid` | ID! | Internal ID of the alert | @@ -209,6 +210,57 @@ Represents a project or group board. | `name` | String | Name of the board | | `weight` | Int | Weight of the board. | +### BoardEpic + +Represents an epic on an issue board. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `author` | User! | Author of the epic | +| `closedAt` | Time | Timestamp of when the epic was closed | +| `confidential` | Boolean | Indicates if the epic is confidential | +| `createdAt` | Time | Timestamp of when the epic was created | +| `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues | +| `descendantWeightSum` | EpicDescendantWeights | Total weight of open and closed issues in the epic and its descendants | +| `description` | String | Description of the epic | +| `downvotes` | Int! | Number of downvotes the epic has received | +| `dueDate` | Time | Due date of the epic | +| `dueDateFixed` | Time | Fixed due date of the epic | +| `dueDateFromMilestones` | Time | Inherited due date of the epic from milestones | +| `dueDateIsFixed` | Boolean | Indicates if the due date has been manually set | +| `group` | Group! | Group to which the epic belongs | +| `hasChildren` | Boolean! | Indicates if the epic has children | +| `hasIssues` | Boolean! | Indicates if the epic has direct issues | +| `hasParent` | Boolean! | Indicates if the epic has a parent epic | +| `healthStatus` | EpicHealthStatus | Current health status of the epic | +| `id` | ID! | ID of the epic | +| `iid` | ID! | Internal ID of the epic | +| `parent` | Epic | Parent epic of the epic | +| `reference` | String! | Internal reference of the epic. Returned in shortened format by default | +| `relationPath` | String | URI path of the epic-issue relationship | +| `relativePosition` | Int | The relative position of the epic in the epic tree | +| `startDate` | Time | Start date of the epic | +| `startDateFixed` | Time | Fixed start date of the epic | +| `startDateFromMilestones` | Time | Inherited start date of the epic from milestones | +| `startDateIsFixed` | Boolean | Indicates if the start date has been manually set | +| `state` | EpicState! | State of the epic | +| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the epic | +| `title` | String | Title of the epic | +| `updatedAt` | Time | Timestamp of when the epic was updated | +| `upvotes` | Int! | Number of upvotes the epic has received | +| `userPermissions` | EpicPermissions! | Permissions for the current user on the resource | +| `userPreferences` | BoardEpicUserPreferences | User preferences for the epic on the issue board | +| `webPath` | String! | Web path of the epic | +| `webUrl` | String! | Web URL of the epic | + +### BoardEpicUserPreferences + +Represents user preferences for a board epic. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `collapsed` | Boolean! | Indicates epic should be displayed as collapsed | + ### BoardList Represents a list for an issue board. @@ -272,6 +324,7 @@ Represents the total number of issues and their weights for a particular day. | Field | Type | Description | | ----- | ---- | ----------- | +| `detailedStatus` | DetailedStatus | Detailed status of the group | | `name` | String | Name of the job group | | `size` | Int | Size of the group | @@ -279,12 +332,15 @@ Represents the total number of issues and their weights for a particular day. | Field | Type | Description | | ----- | ---- | ----------- | +| `detailedStatus` | DetailedStatus | Detailed status of the job | | `name` | String | Name of the job | +| `scheduledAt` | Time | Schedule for the build | ### CiStage | Field | Type | Description | | ----- | ---- | ----------- | +| `detailedStatus` | DetailedStatus | Detailed status of the stage | | `name` | String | Name of the stage | ### ClusterAgent @@ -421,6 +477,16 @@ Autogenerated return type of CreateAnnotation. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | +### CreateBoardPayload + +Autogenerated return type of CreateBoard. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `board` | Board | The board after mutation. | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### CreateBranchPayload Autogenerated return type of CreateBranch. @@ -471,6 +537,16 @@ Autogenerated return type of CreateImageDiffNote. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `note` | Note | The note after mutation | +### CreateIssuePayload + +Autogenerated return type of CreateIssue. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `issue` | Issue | The issue after mutation | + ### CreateIterationPayload Autogenerated return type of CreateIteration. @@ -499,7 +575,7 @@ Autogenerated return type of CreateRequirement. | ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `requirement` | Requirement | The requirement after mutation | +| `requirement` | Requirement | Requirement after mutation | ### CreateSnippetPayload @@ -510,6 +586,7 @@ Autogenerated return type of CreateSnippet. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `snippet` | Snippet | The snippet after mutation | +| `spam` | Boolean | Indicates whether the operation returns a record detected as spam | ### CreateTestCasePayload @@ -541,8 +618,11 @@ Represents a DAST scanner profile. | `globalId` | DastScannerProfileID! | ID of the DAST scanner profile | | `id` **{warning-solid}** | ID! | **Deprecated:** Use `global_id`. Deprecated in 13.4 | | `profileName` | String | Name of the DAST scanner profile | +| `scanType` | DastScanTypeEnum | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | +| `showDebugMessages` | Boolean! | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | | `spiderTimeout` | Int | The maximum number of minutes allowed for the spider to traverse the site | | `targetTimeout` | Int | The maximum number of seconds allowed for the site under test to respond to a request | +| `useAjaxSpider` | Boolean! | Indicates if the AJAX spider should be used to crawl the target site. True to run the AJAX spider in addition to the traditional spider, and false to run only the traditional spider. | ### DastScannerProfileCreatePayload @@ -624,6 +704,18 @@ Autogenerated return type of DastSiteProfileUpdate. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `id` | DastSiteProfileID | ID of the site profile. | +### DastSiteTokenCreatePayload + +Autogenerated return type of DastSiteTokenCreate. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `id` | DastSiteTokenID | ID of the site token. | +| `status` | DastSiteProfileValidationStatusEnum | The current validation status of the target. | +| `token` | String | Token string. | + ### DeleteAnnotationPayload Autogenerated return type of DeleteAnnotation. @@ -685,6 +777,7 @@ A collection of designs. | Field | Type | Description | | ----- | ---- | ----------- | +| `copyState` | DesignCollectionCopyState | Copy state of the design collection | | `design` | Design | Find a specific design | | `designAtVersion` | DesignAtVersion | Find a design as of a version | | `issue` | Issue! | Issue associated with the design collection | @@ -739,6 +832,16 @@ A specific version in which designs were added, modified or deleted. | `id` | ID! | ID of the design version | | `sha` | ID! | SHA of the design version | +### DestroyBoardListPayload + +Autogenerated return type of DestroyBoardList. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `list` | BoardList | The list after mutation. | + ### DestroyBoardPayload Autogenerated return type of DestroyBoard. @@ -773,14 +876,15 @@ Autogenerated return type of DestroySnippet. | Field | Type | Description | | ----- | ---- | ----------- | -| `detailsPath` | String! | Path of the details for the pipeline status | -| `favicon` | String! | Favicon of the pipeline status | -| `group` | String! | Group of the pipeline status | -| `hasDetails` | Boolean! | Indicates if the pipeline status has further details | -| `icon` | String! | Icon of the pipeline status | -| `label` | String! | Label of the pipeline status | -| `text` | String! | Text of the pipeline status | -| `tooltip` | String! | Tooltip associated with the pipeline status | +| `action` | StatusAction | Action information for the status. This includes method, button title, icon, path, and title | +| `detailsPath` | String | Path of the details for the status | +| `favicon` | String | Favicon of the status | +| `group` | String | Group of the status | +| `hasDetails` | Boolean | Indicates if the status has further details | +| `icon` | String | Icon of the status | +| `label` | String | Label of the status | +| `text` | String | Text of the status | +| `tooltip` | String | Tooltip associated with the status | ### DiffPosition @@ -866,9 +970,10 @@ Describes where code is deployed for a project. | Field | Type | Description | | ----- | ---- | ----------- | | `id` | ID! | ID of the environment | -| `latestOpenedMostSevereAlert` | AlertManagementAlert | The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. | +| `latestOpenedMostSevereAlert` | AlertManagementAlert | The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned | | `metricsDashboard` | MetricsDashboard | Metrics dashboard schema for the environment | | `name` | String! | Human-readable name of the environment | +| `path` | String | The path to the environment. Will always return null if `expose_environment_path_in_alert_details` feature flag is disabled | | `state` | String! | State of the environment, for example: available/stopped | ### Epic @@ -878,9 +983,9 @@ Represents an epic. | Field | Type | Description | | ----- | ---- | ----------- | | `author` | User! | Author of the epic | -| `closedAt` | Time | Timestamp of the epic's closure | +| `closedAt` | Time | Timestamp of when the epic was closed | | `confidential` | Boolean | Indicates if the epic is confidential | -| `createdAt` | Time | Timestamp of the epic's creation | +| `createdAt` | Time | Timestamp of when the epic was created | | `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues | | `descendantWeightSum` | EpicDescendantWeights | Total weight of open and closed issues in the epic and its descendants | | `description` | String | Description of the epic | @@ -907,7 +1012,7 @@ Represents an epic. | `state` | EpicState! | State of the epic | | `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the epic | | `title` | String | Title of the epic | -| `updatedAt` | Time | Timestamp of the epic's last activity | +| `updatedAt` | Time | Timestamp of when the epic was updated | | `upvotes` | Int! | Number of upvotes the epic has received | | `userPermissions` | EpicPermissions! | Permissions for the current user on the resource | | `webPath` | String! | Web path of the epic | @@ -984,6 +1089,7 @@ Relationship between an epic and an issue. | `relationPath` | String | URI path of the epic-issue relation | | `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | | `severity` | IssuableSeverity | Severity level of the incident | +| `slaDueAt` | Time | Timestamp of when the issue SLA expires. | | `state` | IssueState! | State of the issue | | `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page | | `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | @@ -1069,9 +1175,12 @@ Autogenerated return type of EpicTreeReorder. | Field | Type | Description | | ----- | ---- | ----------- | +| `actualRepositorySizeLimit` | Float | Size limit for repositories in the namespace in bytes | +| `additionalPurchasedStorageSize` | Float | Additional storage purchased for the root namespace in bytes | | `autoDevopsEnabled` | Boolean | Indicates whether Auto DevOps is enabled for all projects within this group | | `avatarUrl` | String | Avatar URL of the group | | `board` | Board | A single board of the group | +| `containsLockedProjects` | Boolean! | Includes at least one project where the repository size exceeds the limit | | `description` | String | Description of the namespace | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `emailsDisabled` | Boolean | Indicates if a group has email notifications disabled | @@ -1089,6 +1198,7 @@ Autogenerated return type of EpicTreeReorder. | `parent` | Group | Parent group | | `path` | String! | Path of the namespace | | `projectCreationLevel` | String | The permission level required to create projects in the group | +| `repositorySizeExcessProjectCount` | Int! | Number of projects in the root namespace where the repository size exceeds the limit | | `requestAccessEnabled` | Boolean | Indicates if users can request access to namespace | | `requireTwoFactorAuthentication` | Boolean | Indicates if all users in this group are required to set up two-factor authentication | | `rootStorageStatistics` | RootStorageStatistics | Aggregated storage statistics of the namespace. Only available for root namespaces | @@ -1096,6 +1206,8 @@ Autogenerated return type of EpicTreeReorder. | `storageSizeLimit` | Float | Total storage limit of the root namespace in bytes | | `subgroupCreationLevel` | String | The permission level required to create subgroups within the group | | `temporaryStorageIncreaseEndsOn` | Time | Date until the temporary storage increase is active | +| `totalRepositorySize` | Float | Total repository size of all projects in the root namespace in bytes | +| `totalRepositorySizeExcess` | Float | Total excess repository size of all projects in the root namespace in bytes | | `twoFactorGracePeriod` | Int | Time before two-factor authentication is enforced | | `userPermissions` | GroupPermissions! | Permissions for the current user on the resource | | `visibility` | String | Visibility of the namespace | @@ -1168,6 +1280,7 @@ Represents a recorded measurement (object count) for the Admins. | `reference` | String! | Internal reference of the issue. Returned in shortened format by default | | `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | | `severity` | IssuableSeverity | Severity level of the incident | +| `slaDueAt` | Time | Timestamp of when the issue SLA expires. | | `state` | IssueState! | State of the issue | | `statusPagePublishedIncident` | Boolean | Indicates whether an issue is published to the status page | | `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | @@ -1195,6 +1308,16 @@ Autogenerated return type of IssueMoveList. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `issue` | Issue | The issue after mutation | +### IssueMovePayload + +Autogenerated return type of IssueMove. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `issue` | Issue | The issue after mutation | + ### IssuePermissions Check permissions for the current user on a issue. @@ -1486,6 +1609,21 @@ Autogenerated return type of MergeRequestCreate. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `mergeRequest` | MergeRequest | The merge request after mutation | +### MergeRequestDiffRegistry + +Represents the Geo sync and verification state of a Merge Request diff. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `createdAt` | Time | Timestamp when the MergeRequestDiffRegistry was created | +| `id` | ID! | ID of the MergeRequestDiffRegistry | +| `lastSyncFailure` | String | Error message during sync of the MergeRequestDiffRegistry | +| `lastSyncedAt` | Time | Timestamp of the most recent successful sync of the MergeRequestDiffRegistry | +| `mergeRequestDiffId` | ID! | ID of the Merge Request diff | +| `retryAt` | Time | Timestamp after which the MergeRequestDiffRegistry should be resynced | +| `retryCount` | Int | Number of consecutive failed sync attempts of the MergeRequestDiffRegistry | +| `state` | RegistryState | Sync state of the MergeRequestDiffRegistry | + ### MergeRequestPermissions Check permissions for the current user on a merge request. @@ -1630,6 +1768,9 @@ Contains statistics about a milestone. | Field | Type | Description | | ----- | ---- | ----------- | +| `actualRepositorySizeLimit` | Float | Size limit for repositories in the namespace in bytes | +| `additionalPurchasedStorageSize` | Float | Additional storage purchased for the root namespace in bytes | +| `containsLockedProjects` | Boolean! | Includes at least one project where the repository size exceeds the limit | | `description` | String | Description of the namespace | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `fullName` | String! | Full name of the namespace | @@ -1639,10 +1780,13 @@ Contains statistics about a milestone. | `lfsEnabled` | Boolean | Indicates if Large File Storage (LFS) is enabled for namespace | | `name` | String! | Name of the namespace | | `path` | String! | Path of the namespace | +| `repositorySizeExcessProjectCount` | Int! | Number of projects in the root namespace where the repository size exceeds the limit | | `requestAccessEnabled` | Boolean | Indicates if users can request access to namespace | | `rootStorageStatistics` | RootStorageStatistics | Aggregated storage statistics of the namespace. Only available for root namespaces | | `storageSizeLimit` | Float | Total storage limit of the root namespace in bytes | | `temporaryStorageIncreaseEndsOn` | Time | Date until the temporary storage increase is active | +| `totalRepositorySize` | Float | Total repository size of all projects in the root namespace in bytes | +| `totalRepositorySizeExcess` | Float | Total excess repository size of all projects in the root namespace in bytes | | `visibility` | String | Visibility of the namespace | ### NamespaceIncreaseStorageTemporarilyPayload @@ -1702,7 +1846,7 @@ Represents a package. ### PackageFileRegistry -Represents the sync and verification state of a package file. +Represents the Geo sync and verification state of a package file. | Field | Type | Description | | ----- | ---- | ----------- | @@ -1790,6 +1934,7 @@ Autogenerated return type of PipelineRetry. | Field | Type | Description | | ----- | ---- | ----------- | +| `actualRepositorySizeLimit` | Float | Size limit for the repository in bytes | | `alertManagementAlert` | AlertManagementAlert | A single Alert Management alert of the project | | `alertManagementAlertStatusCounts` | AlertManagementAlertStatusCountsType | Counts of alerts by status for the project | | `allowMergeOnSkippedPipeline` | Boolean | If `only_allow_merge_if_pipeline_succeeds` is true, indicates if merge requests of the project can also be merged with skipped jobs | @@ -1836,8 +1981,9 @@ Autogenerated return type of PipelineRetry. | `release` | Release | A single release of the project | | `removeSourceBranchAfterMerge` | Boolean | Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project | | `repository` | Repository | Git repository of the project | +| `repositorySizeExcess` | Float | Size of repository that exceeds the limit in bytes | | `requestAccessEnabled` | Boolean | Indicates if users can request member access to the project | -| `requirement` | Requirement | Find a single requirement. Available only when feature flag `requirements_management` is enabled. | +| `requirement` | Requirement | Find a single requirement | | `requirementStatesCount` | RequirementStatesCount | Number of requirements for the project by their state | | `sastCiConfiguration` | SastCiConfiguration | SAST CI configuration for the project | | `securityDashboardPath` | String | Path to project's security dashboard | @@ -2049,12 +2195,16 @@ Represents a requirement. | ----- | ---- | ----------- | | `author` | User! | Author of the requirement | | `createdAt` | Time! | Timestamp of when the requirement was created | +| `description` | String | Description of the requirement | +| `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | | `id` | ID! | ID of the requirement | | `iid` | ID! | Internal ID of the requirement | +| `lastTestReportManuallyCreated` | Boolean | Indicates if latest test report was created by user | | `lastTestReportState` | TestReportState | Latest requirement test report state | | `project` | Project! | Project to which the requirement belongs | | `state` | RequirementState! | State of the requirement | | `title` | String | Title of the requirement | +| `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` | | `updatedAt` | Time! | Timestamp of when the requirement was last updated | | `userPermissions` | RequirementPermissions! | Permissions for the current user on the resource | @@ -2079,6 +2229,16 @@ Counts of requirements by their state. | `archived` | Int | Number of archived requirements | | `opened` | Int | Number of opened requirements | +### RevertVulnerabilityToDetectedPayload + +Autogenerated return type of RevertVulnerabilityToDetected. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `vulnerability` | Vulnerability | The vulnerability after revert | + ### RootStorageStatistics | Field | Type | Description | @@ -2086,6 +2246,7 @@ Counts of requirements by their state. | `buildArtifactsSize` | Float! | The CI artifacts size in bytes | | `lfsObjectsSize` | Float! | The LFS objects size in bytes | | `packagesSize` | Float! | The packages size in bytes | +| `pipelineArtifactsSize` | Float! | The CI pipeline artifacts size in bytes | | `repositorySize` | Float! | The Git repository size in bytes | | `snippetsSize` | Float! | The snippets size in bytes | | `storageSize` | Float! | The total storage in bytes | @@ -2101,6 +2262,20 @@ Autogenerated return type of RunDASTScan. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `pipelineUrl` | String | URL of the pipeline that was created. | +### RunnerArchitecture + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `downloadLocation` | String! | Download location for the runner for the platform architecture | +| `name` | String! | Name of the runner platform architecture | + +### RunnerPlatform + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `humanReadableName` | String! | Human readable name of the runner platform | +| `name` | String! | Name slug of the runner platform | + ### SastCiConfigurationAnalyzersEntity Represents an analyzer entity in SAST CI configuration. @@ -2150,6 +2325,7 @@ Represents summary of a security report. | Field | Type | Description | | ----- | ---- | ----------- | +| `apiFuzzing` | SecurityReportSummarySection | Aggregated counts for the api_fuzzing scan | | `containerScanning` | SecurityReportSummarySection | Aggregated counts for the container_scanning scan | | `coverageFuzzing` | SecurityReportSummarySection | Aggregated counts for the coverage_fuzzing scan | | `dast` | SecurityReportSummarySection | Aggregated counts for the dast scan | @@ -2302,7 +2478,6 @@ Represents a snippet entry. | ----- | ---- | ----------- | | `author` | User | The owner of the snippet | | `blob` **{warning-solid}** | SnippetBlob! | **Deprecated:** Use `blobs`. Deprecated in 13.3 | -| `blobs` | SnippetBlob! => Array | Snippet blobs | | `createdAt` | Time! | Timestamp this snippet was created | | `description` | String | Description of the snippet | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | @@ -2362,6 +2537,16 @@ Represents how the blob content should be displayed. | `reportSnippet` | Boolean! | Indicates the user can perform `report_snippet` on this resource | | `updateSnippet` | Boolean! | Indicates the user can perform `update_snippet` on this resource | +### StatusAction + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `buttonTitle` | String | Title for the button, for example: Retry this job | +| `icon` | String | Icon used in the action button | +| `method` | String | Method for the action, for example: :post | +| `path` | String | Path for the action | +| `title` | String | Title for the action, for example: Retry | + ### Submodule | Field | Type | Description | @@ -2384,20 +2569,31 @@ Completion status of tasks. | `completedCount` | Int! | Number of completed tasks | | `count` | Int! | Number of total tasks | -### TerraformStateRegistry +### TerraformState + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `createdAt` | Time! | Timestamp the Terraform state was created | +| `id` | ID! | ID of the Terraform state | +| `lockedAt` | Time | Timestamp the Terraform state was locked | +| `lockedByUser` | User | The user currently holding a lock on the Terraform state | +| `name` | String! | Name of the Terraform state | +| `updatedAt` | Time! | Timestamp the Terraform state was updated | + +### TerraformStateVersionRegistry -Represents the sync and verification state of a terraform state. +Represents the Geo sync and verification state of a terraform state version. | Field | Type | Description | | ----- | ---- | ----------- | -| `createdAt` | Time | Timestamp when the TerraformStateRegistry was created | -| `id` | ID! | ID of the TerraformStateRegistry | -| `lastSyncFailure` | String | Error message during sync of the TerraformStateRegistry | -| `lastSyncedAt` | Time | Timestamp of the most recent successful sync of the TerraformStateRegistry | -| `retryAt` | Time | Timestamp after which the TerraformStateRegistry should be resynced | -| `retryCount` | Int | Number of consecutive failed sync attempts of the TerraformStateRegistry | -| `state` | RegistryState | Sync state of the TerraformStateRegistry | -| `terraformStateId` | ID! | ID of the TerraformState | +| `createdAt` | Time | Timestamp when the TerraformStateVersionRegistry was created | +| `id` | ID! | ID of the TerraformStateVersionRegistry | +| `lastSyncFailure` | String | Error message during sync of the TerraformStateVersionRegistry | +| `lastSyncedAt` | Time | Timestamp of the most recent successful sync of the TerraformStateVersionRegistry | +| `retryAt` | Time | Timestamp after which the TerraformStateVersionRegistry should be resynced | +| `retryCount` | Int | Number of consecutive failed sync attempts of the TerraformStateVersionRegistry | +| `state` | RegistryState | Sync state of the TerraformStateVersionRegistry | +| `terraformStateVersionId` | ID! | ID of the terraform state version | ### TestReport @@ -2523,6 +2719,16 @@ Autogenerated return type of UpdateAlertStatus. | `issue` | Issue | The issue created after mutation | | `todo` | Todo | The todo after mutation | +### UpdateBoardEpicUserPreferencesPayload + +Autogenerated return type of UpdateBoardEpicUserPreferences. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `epicUserPreferences` | BoardEpicUserPreferences | User preferences for the epic in the board after mutation | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | + ### UpdateBoardListPayload Autogenerated return type of UpdateBoardList. @@ -2611,7 +2817,7 @@ Autogenerated return type of UpdateRequirement. | ----- | ---- | ----------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | -| `requirement` | Requirement | The requirement after mutation | +| `requirement` | Requirement | Requirement after mutation | ### UpdateSnippetPayload @@ -2622,6 +2828,7 @@ Autogenerated return type of UpdateSnippet. | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `snippet` | Snippet | The snippet after mutation | +| `spam` | Boolean | Indicates whether the operation returns a record detected as spam | ### User @@ -2690,16 +2897,36 @@ Represents a vulnerability. | `location` | VulnerabilityLocation | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability | | `primaryIdentifier` | VulnerabilityIdentifier | Primary identifier of the vulnerability. | | `project` | Project | The project on which the vulnerability was found | -| `reportType` | VulnerabilityReportType | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING) | +| `reportType` | VulnerabilityReportType | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING) | | `resolvedOnDefaultBranch` | Boolean! | Indicates whether the vulnerability is fixed on the default branch or not | | `scanner` | VulnerabilityScanner | Scanner metadata for the vulnerability. | | `severity` | VulnerabilitySeverity | Severity of the vulnerability (INFO, UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL) | -| `state` | VulnerabilityState | State of the vulnerability (DETECTED, DISMISSED, RESOLVED, CONFIRMED) | +| `state` | VulnerabilityState | State of the vulnerability (DETECTED, CONFIRMED, RESOLVED, DISMISSED) | | `title` | String | Title of the vulnerability | | `userNotesCount` | Int! | Number of user notes attached to the vulnerability | | `userPermissions` | VulnerabilityPermissions! | Permissions for the current user on the resource | | `vulnerabilityPath` | String | URL to the vulnerability's details page | +### VulnerabilityConfirmPayload + +Autogenerated return type of VulnerabilityConfirm. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `vulnerability` | Vulnerability | The vulnerability after state change | + +### VulnerabilityDismissPayload + +Autogenerated return type of VulnerabilityDismiss. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `vulnerability` | Vulnerability | The vulnerability after dismissal | + ### VulnerabilityIdentifier Represents a vulnerability identifier. @@ -2812,6 +3039,16 @@ Autogenerated return type of VulnerabilityResolve. | `errors` | String! => Array | Errors encountered during execution of the mutation. | | `vulnerability` | Vulnerability | The vulnerability after state change | +### VulnerabilityRevertToDetectedPayload + +Autogenerated return type of VulnerabilityRevertToDetected. + +| Field | Type | Description | +| ----- | ---- | ----------- | +| `clientMutationId` | String | A unique identifier for the client performing the mutation. | +| `errors` | String! => Array | Errors encountered during execution of the mutation. | +| `vulnerability` | Vulnerability | The vulnerability after revert | + ### VulnerabilityScanner Represents a vulnerability scanner. @@ -2890,6 +3127,8 @@ Values for sorting alerts. | Value | Description | | ----- | ----------- | +| `CREATED_ASC` | Created at ascending order | +| `CREATED_DESC` | Created at descending order | | `CREATED_TIME_ASC` | Created time by ascending order | | `CREATED_TIME_DESC` | Created time by descending order | | `ENDED_AT_ASC` | End time by ascending order | @@ -2902,12 +3141,14 @@ Values for sorting alerts. | `STARTED_AT_DESC` | Start time by descending order | | `STATUS_ASC` | Status by order: Ignored > Resolved > Acknowledged > Triggered | | `STATUS_DESC` | Status by order: Triggered > Acknowledged > Resolved > Ignored | +| `UPDATED_ASC` | Updated at ascending order | +| `UPDATED_DESC` | Updated at descending order | | `UPDATED_TIME_ASC` | Created time by ascending order | | `UPDATED_TIME_DESC` | Created time by descending order | -| `created_asc` | Created at ascending order | -| `created_desc` | Created at descending order | -| `updated_asc` | Updated at ascending order | -| `updated_desc` | Updated at descending order | +| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5 | +| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5 | +| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5 | +| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5 | ### AlertManagementSeverity @@ -2996,6 +3237,7 @@ Mode of a commit action. | Value | Description | | ----- | ----------- | +| `ACTIVE` | Active DAST scan. This scan will make active attacks against the target site. | | `PASSIVE` | Passive DAST scan. This scan will not make active attacks against the target site. | ### DastSiteProfileValidationStatusEnum @@ -3007,6 +3249,16 @@ Mode of a commit action. | `PASSED_VALIDATION` | Site validation process finished successfully | | `PENDING_VALIDATION` | Site validation process has not started | +### DesignCollectionCopyState + +Copy state of a DesignCollection. + +| Value | Description | +| ----- | ----------- | +| `ERROR` | The DesignCollection encountered an error during a copy | +| `IN_PROGRESS` | The DesignCollection is being copied | +| `READY` | The DesignCollection has no copy in progress | + ### DesignVersionEvent Mutation event of a design within a version. @@ -3115,6 +3367,8 @@ Values for sorting issues. | Value | Description | | ----- | ----------- | +| `CREATED_ASC` | Created at ascending order | +| `CREATED_DESC` | Created at descending order | | `DUE_DATE_ASC` | Due date by ascending order | | `DUE_DATE_DESC` | Due date by descending order | | `LABEL_PRIORITY_ASC` | Label priority by ascending order | @@ -3123,13 +3377,19 @@ Values for sorting issues. | `MILESTONE_DUE_DESC` | Milestone due date by descending order | | `PRIORITY_ASC` | Priority by ascending order | | `PRIORITY_DESC` | Priority by descending order | +| `PUBLISHED_ASC` | Published issues shown last | +| `PUBLISHED_DESC` | Published issues shown first | | `RELATIVE_POSITION_ASC` | Relative position by ascending order | +| `SEVERITY_ASC` | Severity from less critical to more critical | +| `SEVERITY_DESC` | Severity from more critical to less critical | +| `UPDATED_ASC` | Updated at ascending order | +| `UPDATED_DESC` | Updated at descending order | | `WEIGHT_ASC` | Weight by ascending order | | `WEIGHT_DESC` | Weight by descending order | -| `created_asc` | Created at ascending order | -| `created_desc` | Created at descending order | -| `updated_asc` | Updated at ascending order | -| `updated_desc` | Updated at descending order | +| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5 | +| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5 | +| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5 | +| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5 | ### IssueState @@ -3142,6 +3402,15 @@ State of a GitLab issue. | `locked` | | | `opened` | | +### IssueStateEvent + +Values for issue state events. + +| Value | Description | +| ----- | ----------- | +| `CLOSE` | Closes the issue | +| `REOPEN` | Reopens the issue | + ### IssueType Issue type. @@ -3184,6 +3453,10 @@ Possible identifier types for a measurement. | `ISSUES` | Issue count | | `MERGE_REQUESTS` | Merge request count | | `PIPELINES` | Pipeline count | +| `PIPELINES_CANCELED` | Pipeline count with canceled status | +| `PIPELINES_FAILED` | Pipeline count with failed status | +| `PIPELINES_SKIPPED` | Pipeline count with skipped status | +| `PIPELINES_SUCCEEDED` | Pipeline count with success status | | `PROJECTS` | Project count | | `USERS` | User count | @@ -3193,6 +3466,8 @@ Values for sorting merge requests. | Value | Description | | ----- | ----------- | +| `CREATED_ASC` | Created at ascending order | +| `CREATED_DESC` | Created at descending order | | `LABEL_PRIORITY_ASC` | Label priority by ascending order | | `LABEL_PRIORITY_DESC` | Label priority by descending order | | `MERGED_AT_ASC` | Merge time by ascending order | @@ -3201,10 +3476,12 @@ Values for sorting merge requests. | `MILESTONE_DUE_DESC` | Milestone due date by descending order | | `PRIORITY_ASC` | Priority by ascending order | | `PRIORITY_DESC` | Priority by descending order | -| `created_asc` | Created at ascending order | -| `created_desc` | Created at descending order | -| `updated_asc` | Updated at ascending order | -| `updated_desc` | Updated at descending order | +| `UPDATED_ASC` | Updated at ascending order | +| `UPDATED_DESC` | Updated at descending order | +| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5 | +| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5 | +| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5 | +| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5 | ### MergeRequestState @@ -3256,13 +3533,15 @@ Values for sorting projects. | Value | Description | | ----- | ----------- | -| `COMPOSER` | Packages from the composer package manager | -| `CONAN` | Packages from the conan package manager | -| `GENERIC` | Packages from the generic package manager | -| `MAVEN` | Packages from the maven package manager | -| `NPM` | Packages from the npm package manager | -| `NUGET` | Packages from the nuget package manager | -| `PYPI` | Packages from the pypi package manager | +| `COMPOSER` | Packages from the Composer package manager | +| `CONAN` | Packages from the Conan package manager | +| `DEBIAN` | Packages from the Debian package manager | +| `GENERIC` | Packages from the Generic package manager | +| `GOLANG` | Packages from the Golang package manager | +| `MAVEN` | Packages from the Maven package manager | +| `NPM` | Packages from the NPM package manager | +| `NUGET` | Packages from the Nuget package manager | +| `PYPI` | Packages from the PyPI package manager | ### PipelineConfigSourceEnum @@ -3352,6 +3631,7 @@ The type of the security scanner. | Value | Description | | ----- | ----------- | +| `API_FUZZING` | | | `CONTAINER_SCANNING` | | | `COVERAGE_FUZZING` | | | `DAST` | | @@ -3428,10 +3708,14 @@ Common sort values. | Value | Description | | ----- | ----------- | -| `created_asc` | Created at ascending order | -| `created_desc` | Created at descending order | -| `updated_asc` | Updated at ascending order | -| `updated_desc` | Updated at descending order | +| `CREATED_ASC` | Created at ascending order | +| `CREATED_DESC` | Created at descending order | +| `UPDATED_ASC` | Updated at ascending order | +| `UPDATED_DESC` | Updated at descending order | +| `created_asc` **{warning-solid}** | **Deprecated:** Use CREATED_ASC. Deprecated in 13.5 | +| `created_desc` **{warning-solid}** | **Deprecated:** Use CREATED_DESC. Deprecated in 13.5 | +| `updated_asc` **{warning-solid}** | **Deprecated:** Use UPDATED_ASC. Deprecated in 13.5 | +| `updated_desc` **{warning-solid}** | **Deprecated:** Use UPDATED_DESC. Deprecated in 13.5 | ### TestReportState @@ -3532,6 +3816,7 @@ The type of the security scan that found the vulnerability. | Value | Description | | ----- | ----------- | +| `API_FUZZING` | | | `CONTAINER_SCANNING` | | | `COVERAGE_FUZZING` | | | `DAST` | | @@ -3558,8 +3843,16 @@ Vulnerability sort values. | Value | Description | | ----- | ----------- | +| `detected_asc` | Detection timestamp in ascending order | +| `detected_desc` | Detection timestamp in descending order | +| `report_type_asc` | Report Type in ascending order | +| `report_type_desc` | Report Type in descending order | | `severity_asc` | Severity in ascending order | | `severity_desc` | Severity in descending order | +| `state_asc` | State in ascending order | +| `state_desc` | State in descending order | +| `title_asc` | Title in ascending order | +| `title_desc` | Title in descending order | ### VulnerabilityState diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index 17413ea2a3b..27b76d1f0c0 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -8,8 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30213) in GitLab 12.1. -NOTE: **Note:** -User will need at least maintainer access for the group to use these endpoints. +Users need at least [Maintainer](../user/permissions.md) access for the group to use these endpoints. ## List group clusters diff --git a/doc/api/group_iterations.md b/doc/api/group_iterations.md new file mode 100644 index 00000000000..62431244d78 --- /dev/null +++ b/doc/api/group_iterations.md @@ -0,0 +1,55 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Group iterations API **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. + +This page describes the group iterations API. +There's a separate [project iterations API](./iterations.md) page. + +## List group iterations + +Returns a list of group iterations. + +```plaintext +GET /groups/:id/iterations +GET /groups/:id/iterations?state=opened +GET /groups/:id/iterations?state=closed +GET /groups/:id/iterations?title=1.0 +GET /groups/:id/iterations?search=version +``` + +| Attribute | Type | Required | Description | +| ------------------- | ------- | -------- | ----------- | +| `state` | string | no | Return only `opened`, `upcoming`, `started`, `closed`, or `all` iterations. Defaults to `all`. | +| `search` | string | no | Return only iterations with a title matching the provided string. | +| `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/iterations" +``` + +Example response: + +```json +[ + { + "id": 53, + "iid": 13, + "group_id": 5, + "title": "Iteration II", + "description": "Ipsum Lorem ipsum", + "state": 2, + "created_at": "2020-01-27T05:07:12.573Z", + "updated_at": "2020-01-27T05:07:12.573Z", + "due_date": "2020-02-01", + "start_date": "2020-02-14" + } +] +``` diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 47350442b3e..3220707e9e3 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12819) in GitLab 9.5. This page describes the group milestones API. -There's a separate [project milestones API](./group_milestones.md) page. +There's a separate [project milestones API](./milestones.md) page. ## List group milestones diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index 414c795e092..c61a557fcc6 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -5,9 +5,9 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Wikis API +# Group wikis API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212199) in GitLab 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212199) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. Available only in APIv4. diff --git a/doc/api/groups.md b/doc/api/groups.md index ae3300e24fb..53c92cf85ec 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -167,6 +167,89 @@ GET /groups/:id/subgroups ] ``` +## List a group's descendant groups + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217115) in GitLab 13.5 + +Get a list of visible descendant groups of this group. +When accessed without authentication, only public groups are returned. + +By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination). + +Parameters: + +| Attribute | Type | Required | Description | +| ------------------------ | ----------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the immediate parent group | +| `skip_groups` | array of integers | no | Skip the group IDs passed | +| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin). Attributes `owned` and `min_access_level` have precedence | +| `search` | string | no | Return the list of authorized groups matching the search criteria | +| `order_by` | string | no | Order groups by `name`, `path`, or `id`. Default is `name` | +| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | +| `statistics` | boolean | no | Include group statistics (admins only) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `owned` | boolean | no | Limit to groups explicitly owned by the current user | +| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md#valid-access-levels) | + +```plaintext +GET /groups/:id/descendant_groups +``` + +```json +[ + { + "id": 2, + "name": "Bar Group", + "path": "foo/bar", + "description": "A subgroup of Foo Group", + "visibility": "public", + "share_with_group_lock": false, + "require_two_factor_authentication": false, + "two_factor_grace_period": 48, + "project_creation_level": "developer", + "auto_devops_enabled": null, + "subgroup_creation_level": "owner", + "emails_disabled": null, + "mentions_disabled": null, + "lfs_enabled": true, + "default_branch_protection": 2, + "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg", + "web_url": "http://gitlab.example.com/groups/foo/bar", + "request_access_enabled": false, + "full_name": "Bar Group", + "full_path": "foo/bar", + "file_template_project_id": 1, + "parent_id": 123, + "created_at": "2020-01-15T12:36:29.590Z" + }, + { + "id": 3, + "name": "Baz Group", + "path": "foo/bar/baz", + "description": "A subgroup of Bar Group", + "visibility": "public", + "share_with_group_lock": false, + "require_two_factor_authentication": false, + "two_factor_grace_period": 48, + "project_creation_level": "developer", + "auto_devops_enabled": null, + "subgroup_creation_level": "owner", + "emails_disabled": null, + "mentions_disabled": null, + "lfs_enabled": true, + "default_branch_protection": 2, + "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/baz.jpg", + "web_url": "http://gitlab.example.com/groups/foo/bar/baz", + "request_access_enabled": false, + "full_name": "Baz Group", + "full_path": "foo/bar/baz", + "file_template_project_id": 1, + "parent_id": 123, + "created_at": "2020-01-15T12:36:29.590Z" + } +] +``` + ## List a group's projects Get a list of projects in this group. When accessed without authentication, only public projects are returned. @@ -357,6 +440,7 @@ Example response: "import_status":"failed", "open_issues_count":10, "ci_default_git_depth":50, + "ci_forward_deployment_enabled":true, "public_jobs":true, "build_timeout":3600, "auto_cancel_pending_pipelines":"enabled", @@ -676,6 +760,7 @@ Parameters: | `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). Default to the global level default branch protection setting. | | `shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | | `extra_shared_runners_minutes_limit` | integer | no | **(STARTER ONLY)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | +| `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | ### Options for `default_branch_protection` @@ -687,6 +772,16 @@ The `default_branch_protection` attribute determines whether developers and main | `1` | Partial protection. Developers and maintainers can:
- Push new commits | | `2` | Full protection. Only maintainers can:
- Push new commits | +### Options for `shared_runners_setting` + +The `shared_runners_setting` attribute determines whether shared runners are enabled for a group's subgroups and projects. + +| Value | Description | +|-------|-------------------------------------------------------------------------------------------------------------| +| `enabled` | Enables shared runners for all projects and subgroups in this group. | +| `disabled_with_override` | Disables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting. | +| `disabled_and_unoverridable` | Disables shared runners for all projects and subgroups in this group, and prevents subgroups from overriding this setting. | + ## New Subgroup This is similar to creating a [New group](#new-group). You'll need the `parent_id` from the [List groups](#list-groups) call. You can then enter the desired: @@ -696,7 +791,7 @@ This is similar to creating a [New group](#new-group). You'll need the `parent_i ```shell curl --request POST --header "PRIVATE-TOKEN: " --header "Content-Type: application/json" \ - --data '{"path": "", "name": "", "parent_id": } \ + --data '{"path": "", "name": "", "parent_id": }' \ "https://gitlab.example.com/api/v4/groups/" ``` diff --git a/doc/api/import.md b/doc/api/import.md index 54e7eb12ed1..e377853ade0 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -50,8 +50,8 @@ POST /import/bitbucket_server | `personal_access_token` | string | yes | Bitbucket Server personal access token/password | | `bitbucket_server_project` | string | yes | Bitbucket Project Key | | `bitbucket_server_repo` | string | yes | Bitbucket Repository Name | -| `new_name` | string | no | New repo name | -| `target_namespace` | string | no | Namespace to import repo into | +| `new_name` | string | no | New repository name | +| `target_namespace` | string | no | Namespace to import repository into | ```shell curl --request POST \ diff --git a/doc/api/instance_level_ci_variables.md b/doc/api/instance_level_ci_variables.md index d8f306a822c..e8550d41c44 100644 --- a/doc/api/instance_level_ci_variables.md +++ b/doc/api/instance_level_ci_variables.md @@ -70,7 +70,7 @@ curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/a Create a new instance-level variable. -[Since GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/216097), the maximum number of allowed instance-level variables can be changed. +[In GitLab 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/216097), the maximum number of allowed instance-level variables can be changed. ```plaintext POST /admin/ci/variables @@ -79,7 +79,7 @@ POST /admin/ci/variables | Attribute | Type | required | Description | |-----------------|---------|----------|-----------------------| | `key` | string | yes | The `key` of a variable. Max 255 characters, only `A-Z`, `a-z`, `0-9`, and `_` are allowed. | -| `value` | string | yes | The `value` of a variable. 10,000 characters allowed. [Since GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/220028) | +| `value` | string | yes | The `value` of a variable. 10,000 characters allowed ([GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/220028)). | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file`. | | `protected` | boolean | no | Whether the variable is protected. | | `masked` | boolean | no | Whether the variable is masked. | @@ -109,7 +109,7 @@ PUT /admin/ci/variables/:key | Attribute | Type | required | Description | |-----------------|---------|----------|-------------------------| | `key` | string | yes | The `key` of a variable. | -| `value` | string | yes | The `value` of a variable. [Since GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), around 10,000 characters allowed. Previously 700 characters. | +| `value` | string | yes | The `value` of a variable. 10,000 characters allowed ([GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/220028)). | | `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file`. | | `protected` | boolean | no | Whether the variable is protected. | | `masked` | boolean | no | Whether the variable is masked. | diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index b6502bf099c..757910d0946 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -1,8 +1,11 @@ -# Issue links API **(STARTER)** +# Issue links API **(CORE)** + +> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. ## List issue relations -Get a list of related issues of a given issue, sorted by the relationship creation datetime (ascending). +Get a list of a given issue's [related issues](../user/project/issues/related_issues.md), +sorted by the relationship creation datetime (ascending). Issues will be filtered according to the user authorizations. ```plaintext @@ -55,19 +58,20 @@ Parameters: ## Create an issue link -Creates a two-way relation between two issues. User must be allowed to update both issues in order to succeed. +Creates a two-way relation between two issues. The user must be allowed to +update both issues to succeed. ```plaintext POST /projects/:id/issues/:issue_iid/links ``` -| Attribute | Type | Required | Description | -|-------------|---------|----------|--------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `issue_iid` | integer | yes | The internal ID of a project's issue | +| Attribute | Type | Required | Description | +|---------------------|----------------|----------|--------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The internal ID of a project's issue | | `target_project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) of a target project | -| `target_issue_iid` | integer/string | yes | The internal ID of a target project's issue | -| `link_type` | string | no | The type of the relation ("relates_to", "blocks", "is_blocked_by"), defaults to "relates_to"). | +| `target_issue_iid` | integer/string | yes | The internal ID of a target project's issue | +| `link_type` | string | no | The type of the relation ("relates_to", "blocks", "is_blocked_by"), defaults to "relates_to"). | ```shell curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/4/issues/1/links?target_project_id=5&target_issue_iid=1" diff --git a/doc/api/issues.md b/doc/api/issues.md index d8249869cab..b50ea7b42be 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -16,7 +16,7 @@ are paginated. Read more on [pagination](README.md#pagination). -CAUTION: **Deprecation:** +DANGER: **Deprecated:** The `reference` attribute in responses is deprecated in favor of `references`. Introduced in [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354). @@ -33,19 +33,19 @@ use parameter `scope=all`. ```plaintext GET /issues -GET /issues?state=opened -GET /issues?state=closed +GET /issues?assignee_id=5 +GET /issues?author_id=5 +GET /issues?confidential=true +GET /issues?iids[]=42&iids[]=43 GET /issues?labels=foo GET /issues?labels=foo,bar GET /issues?labels=foo,bar&state=opened GET /issues?milestone=1.0.0 GET /issues?milestone=1.0.0&state=opened -GET /issues?iids[]=42&iids[]=43 -GET /issues?author_id=5 -GET /issues?assignee_id=5 GET /issues?my_reaction_emoji=star GET /issues?search=foo&in=title -GET /issues?confidential=true +GET /issues?state=closed +GET /issues?state=opened ``` | Attribute | Type | Required | Description | @@ -194,7 +194,7 @@ the `health_status` parameter: ] ``` -NOTE: **Note:** +DANGER: **Deprecated:** The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. @@ -212,19 +212,19 @@ The preferred way to do this, is by using [personal access tokens](../user/profi ```plaintext GET /groups/:id/issues -GET /groups/:id/issues?state=opened -GET /groups/:id/issues?state=closed +GET /groups/:id/issues?assignee_id=5 +GET /groups/:id/issues?author_id=5 +GET /groups/:id/issues?confidential=true +GET /groups/:id/issues?iids[]=42&iids[]=43 GET /groups/:id/issues?labels=foo GET /groups/:id/issues?labels=foo,bar GET /groups/:id/issues?labels=foo,bar&state=opened GET /groups/:id/issues?milestone=1.0.0 GET /groups/:id/issues?milestone=1.0.0&state=opened -GET /groups/:id/issues?iids[]=42&iids[]=43 -GET /groups/:id/issues?search=issue+title+or+description -GET /groups/:id/issues?author_id=5 -GET /groups/:id/issues?assignee_id=5 GET /groups/:id/issues?my_reaction_emoji=star -GET /groups/:id/issues?confidential=true +GET /groups/:id/issues?search=issue+title+or+description +GET /groups/:id/issues?state=closed +GET /groups/:id/issues?state=opened ``` | Attribute | Type | Required | Description | @@ -372,7 +372,7 @@ the `health_status` parameter: ] ``` -NOTE: **Note:** +DANGER: **Deprecated:** The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. NOTE: **Note:** @@ -389,19 +389,19 @@ The preferred way to do this, is by using [personal access tokens](../user/profi ```plaintext GET /projects/:id/issues -GET /projects/:id/issues?state=opened -GET /projects/:id/issues?state=closed +GET /projects/:id/issues?assignee_id=5 +GET /projects/:id/issues?author_id=5 +GET /projects/:id/issues?confidential=true +GET /projects/:id/issues?iids[]=42&iids[]=43 GET /projects/:id/issues?labels=foo GET /projects/:id/issues?labels=foo,bar GET /projects/:id/issues?labels=foo,bar&state=opened GET /projects/:id/issues?milestone=1.0.0 GET /projects/:id/issues?milestone=1.0.0&state=opened -GET /projects/:id/issues?iids[]=42&iids[]=43 -GET /projects/:id/issues?search=issue+title+or+description -GET /projects/:id/issues?author_id=5 -GET /projects/:id/issues?assignee_id=5 GET /projects/:id/issues?my_reaction_emoji=star -GET /projects/:id/issues?confidential=true +GET /projects/:id/issues?search=issue+title+or+description +GET /projects/:id/issues?state=closed +GET /projects/:id/issues?state=opened ``` | Attribute | Type | Required | Description | @@ -555,7 +555,7 @@ the `health_status` parameter: ] ``` -NOTE: **Note:** +DANGER: **Deprecated:** The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. NOTE: **Note:** @@ -574,7 +574,7 @@ GET /issues/:id | Attribute | Type | Required | Description | |-------------|---------|----------|--------------------------------------| -| `id` | integer | yes | The ID of the issue | +| `id` | integer | yes | The ID of the issue | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/issues/41" @@ -663,10 +663,10 @@ Example response: "weight": null, "has_tasks": false, "_links": { - "self": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1", - "notes": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1/notes", - "award_emoji": "http://gitlab.dummy:3000/api/v4/projects/1/issues/1/award_emoji", - "project": "http://gitlab.dummy:3000/api/v4/projects/1" + "self": "http://gitlab.example:3000/api/v4/projects/1/issues/1", + "notes": "http://gitlab.example:3000/api/v4/projects/1/issues/1/notes", + "award_emoji": "http://gitlab.example:3000/api/v4/projects/1/issues/1/award_emoji", + "project": "http://gitlab.example:3000/api/v4/projects/1" }, "references": { "short": "#1", @@ -712,19 +712,19 @@ the `epic` property: } ``` -NOTE: **Note:** +DANGER: **Deprecated:** The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. +DANGER: **Deprecated:** +The `epic_iid` attribute is deprecated, and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + NOTE: **Note:** The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. -NOTE: **Note:** -The `epic_iid` attribute is deprecated, and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). -Please use `iid` of the `epic` attribute instead. - ## Single project issue Get a single project issue. @@ -874,17 +874,17 @@ property: ] ``` -NOTE: **Note:** +DANGER: **Deprecated:** The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. +DANGER: **Deprecated:** +The `epic_iid` attribute is deprecated and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +Please use `iid` of the `epic` attribute instead. + NOTE: **Note:** The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. -NOTE: **Note:** -The `epic_iid` attribute is deprecated and [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). -Please use `iid` of the `epic` attribute instead. - ## New issue Creates a new project issue. @@ -895,21 +895,21 @@ POST /projects/:id/issues | Attribute | Type | Required | Description | |-------------------------------------------|----------------|----------|--------------| +| `assignee_ids` | integer array | no | The ID of the user(s) to assign the issue to. | +| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | +| `created_at` | string | no | When the issue was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights. | +| `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | +| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This fills out the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +| `due_date` | string | no | The due date. Date time string in the format YEAR-MONTH-DAY, for example `2016-03-11` | +| `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | +| `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iid` | integer/string | no | The internal ID of the project's issue (requires administrator or project owner rights) | -| `title` | string | yes | The title of an issue | -| `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | -| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | -| `assignee_ids` | integer array | no | The ID of the user(s) to assign the issue to. | -| `milestone_id` | integer | no | The global ID of a milestone to assign issue | | `labels` | string | no | Comma-separated label names for an issue | -| `created_at` | string | no | Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | -| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, for example `2016-03-11` | | `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This fills out the issue with a default description and mark all discussions as resolved. When passing a description or title, these values take precedence over the default values.| -| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This fills out the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +| `milestone_id` | integer | no | The global ID of a milestone to assign issue | +| `title` | string | yes | The title of an issue | | `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | -| `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | -| `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | ```shell curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug" @@ -1002,7 +1002,7 @@ the `health_status` parameter: ] ``` -NOTE: **Note:** +DANGER: **Deprecated:** The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. NOTE: **Note:** @@ -1019,29 +1019,43 @@ See [Issues rate limits](../user/admin_area/settings/rate_limit_on_issues_creati Updates an existing project issue. This call is also used to mark an issue as closed. +At least one of the following parameters is required for the request to be successful: + +- `:assignee_id` +- `:assignee_ids` +- `:confidential` +- `:created_at` +- `:description` +- `:discussion_locked` +- `:due_date` +- `:labels` +- `:milestone_id` +- `:state_event` +- `:title` + ```plaintext PUT /projects/:id/issues/:issue_iid ``` | Attribute | Type | Required | Description | |----------------|---------|----------|------------------------------------------------------------------------------------------------------------| +| `add_labels` | string | no | Comma-separated label names to add to an issue. | +| `assignee_ids` | integer array | no | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | +| `confidential` | boolean | no | Updates an issue to be confidential | +| `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | +| `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | +| `due_date` | string | no | The due date. Date time string in the format YEAR-MONTH-DAY, for example `2016-03-11` | +| `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | +| `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | -| `title` | string | no | The title of an issue | -| `description` | string | no | The description of an issue. Limited to 1,048,576 characters. | -| `confidential` | boolean | no | Updates an issue to be confidential | -| `assignee_ids` | integer array | no | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | -| `milestone_id` | integer | no | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| | `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | -| `add_labels` | string | no | Comma-separated label names to add to an issue. | +| `milestone_id` | integer | no | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| | `remove_labels`| string | no | Comma-separated label names to remove from an issue. | | `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | -| `updated_at` | string | no | Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project owner rights). Empty string or null values are not accepted.| -| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, for example `2016-03-11` | +| `title` | string | no | The title of an issue | +| `updated_at` | string | no | When the issue was updated. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` (requires administrator or project owner rights). Empty string or null values are not accepted.| | `weight` **(STARTER)** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | -| `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | -| `epic_id` **(PREMIUM)** | integer | no | ID of the epic to add the issue to. Valid values are greater than or equal to 0. | -| `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [will be removed in version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | ```shell curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close" @@ -1141,16 +1155,13 @@ the `health_status` parameter: ] ``` -NOTE: **Note:** -At least one of following parameters is required to be passed for the request to be successful: `:assignee_id`, `:assignee_ids`, `:confidential`, `:created_at`, `:description`, `:discussion_locked`, `:due_date`, `:labels`, `:milestone_id`, `:state_event`, or `:title`. - -NOTE: **Note:** -`assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. - NOTE: **Note:** The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. +DANGER: **Deprecated:** +`assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## Delete an issue Only for admins and project owners. Deletes the issue in question. @@ -1309,7 +1320,7 @@ the `health_status` parameter: ] ``` -NOTE: **Note:** +DANGER: **Deprecated:** The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. NOTE: **Note:** @@ -1418,7 +1429,7 @@ the `weight` parameter: } ``` -NOTE: **Note:** +DANGER: **Deprecated:** The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. NOTE: **Note:** @@ -1496,10 +1507,10 @@ Example response: } ``` -## Create a to-do +## Create a to do -Manually creates a to-do for the current user on an issue. If -there already exists a to-do for the user on that issue, status code `304` is +Manually creates a to do for the current user on an issue. If +there already exists a to do for the user on that issue, status code `304` is returned. ```plaintext @@ -1608,7 +1619,7 @@ Example response: } ``` -NOTE: **Note:** +DANGER: **Deprecated:** The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. NOTE: **Note:** @@ -1625,9 +1636,9 @@ POST /projects/:id/issues/:issue_iid/time_estimate | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| +| `duration` | string | yes | The duration in human format. e.g: 3h30m | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | -| `duration` | string | yes | The duration in human format. e.g: 3h30m | ```shell curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m" @@ -1682,9 +1693,9 @@ POST /projects/:id/issues/:issue_iid/add_spent_time | Attribute | Type | Required | Description | |-------------|---------|----------|------------------------------------------| +| `duration` | string | yes | The duration in human format. e.g: 3h30m | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | -| `duration` | string | yes | The duration in human format. e.g: 3h30m | ```shell curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h" diff --git a/doc/api/iterations.md b/doc/api/iterations.md new file mode 100644 index 00000000000..53a6bb00f23 --- /dev/null +++ b/doc/api/iterations.md @@ -0,0 +1,57 @@ +--- +stage: Plan +group: Project Management +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Project iterations API **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. + +This page describes the project iterations API. +There's a separate [group iterations API](./group_iterations.md) page. + +As of GitLab 13.5, we don't have project-level iterations, but you can use this endpoint to fetch the iterations of the project's ancestor groups. + +## List project iterations + +Returns a list of project iterations. + +```plaintext +GET /projects/:id/iterations +GET /projects/:id/iterations?state=opened +GET /projects/:id/iterations?state=closed +GET /projects/:id/iterations?title=1.0 +GET /projects/:id/iterations?search=version +``` + +| Attribute | Type | Required | Description | +| ------------------- | ------- | -------- | ----------- | +| `state` | string | no | Return only `opened`, `upcoming`, `started`, `closed`, or `all` iterations. Defaults to `all`. | +| `search` | string | no | Return only iterations with a title matching the provided string. | +| `include_ancestors` | boolean | no | Include iterations from parent group and its ancestors. Defaults to `true`. | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/iterations" +``` + +Example response: + +```json +[ + { + "id": 53, + "iid": 13, + "group_id": 5, + "title": "Iteration II", + "description": "Ipsum Lorem ipsum", + "state": 2, + "created_at": "2020-01-27T05:07:12.573Z", + "updated_at": "2020-01-27T05:07:12.573Z", + "due_date": "2020-02-01", + "start_date": "2020-02-14" + } +] +``` diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 458877d6548..f5510f6ee91 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -63,6 +63,11 @@ the given reference name and job, provided the job finished successfully. This is the same as [getting the job's artifacts](#get-job-artifacts), but by defining the job's name instead of its ID. +NOTE: **Note:** +If a pipeline is [parent of other child pipelines](../ci/parent_child_pipelines.md), artifacts +are searched in hierarchical order from parent to child. For example, if both parent and +child pipelines have a job with the same name, the artifact from the parent pipeline will be returned. + ```plaintext GET /projects/:id/jobs/artifacts/:ref_name/download?job=name ``` @@ -157,6 +162,11 @@ Download a single artifact file for a specific job of the latest successful pipeline for the given reference name from within the job's artifacts archive. The file is extracted from the archive and streamed to the client. +In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201784) and later, artifacts +for [parent and child pipelines](../ci/parent_child_pipelines.md) are searched in hierarchical +order from parent to child. For example, if both parent and child pipelines have a +job with the same name, the artifact from the parent pipeline is returned. + ```plaintext GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name ``` diff --git a/doc/api/license.md b/doc/api/license.md index 71e95fc3202..dcdf019059b 100644 --- a/doc/api/license.md +++ b/doc/api/license.md @@ -1,7 +1,7 @@ # License **(CORE ONLY)** -In order to interact with license endpoints, you need to authenticate yourself -as an admin. +To interact with license endpoints, you need to authenticate yourself as an +admin. ## Retrieve information about the current license diff --git a/doc/api/lint.md b/doc/api/lint.md index f4d8a0bc011..c82e0845f99 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -4,11 +4,14 @@ group: Continuous Integration info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Validate the `.gitlab-ci.yml` (API) +# CI Lint API + +## Validate the CI YAML configuration > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5953) in GitLab 8.12. -Checks if your `.gitlab-ci.yml` file is valid. +Checks if CI/CD YAML configuration is valid. This endpoint validates basic CI/CD +configuration syntax. It doesn't have any namespace specific context. ```plaintext POST /ci/lint @@ -16,13 +19,15 @@ POST /ci/lint | Attribute | Type | Required | Description | | ---------- | ------- | -------- | -------- | -| `content` | string | yes | the `.gitlab-ci.yaml` content| +| `content` | string | yes | The CI/CD configuration content. | +| `include_merged_yaml` | boolean | no | If the [expanded CI/CD configuration](#yaml-expansion) should be included in the response. | ```shell curl --header "Content-Type: application/json" "https://gitlab.example.com/api/v4/ci/lint" --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}' ``` -Be sure to copy paste the exact contents of `.gitlab-ci.yml` as YAML is very picky about indentation and spaces. +Be sure to paste the exact contents of your GitLab CI/CD YAML configuration because YAML +is very sensitive about indentation and spacing. Example responses: @@ -53,3 +58,180 @@ Example responses: "error": "content is missing" } ``` + +### YAML expansion + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29568) in GitLab 13.5. + +The CI lint returns an expanded version of the configuration. The expansion does not +work for CI configuration added with [`include: local`](../ci/yaml/README.md#includelocal), +or with [`extends:`](../ci/yaml/README.md#extends). + +Example contents of a `.gitlab-ci.yml` passed to the CI Lint API with +`include_merged_yaml` set as true: + +```yaml +include: + remote: 'https://example.com/remote.yaml' + +test: + stage: test + script: + - echo 1 +``` + +Example contents of `https://example.com/remote.yaml`: + +```yaml +another_test: + stage: test + script: + - echo 2 +``` + +Example response: + +```json +{ + "status": "valid", + "errors": [], + "merged_config": "---\n:another_test:\n :stage: test\n :script: echo 2\n:test:\n :stage: test\n :script: echo 1\n" +} +``` + +## Validate a project's CI configuration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231352) in GitLab 13.5. + +Checks if a project's latest (`HEAD` of the project's default branch) +`.gitlab-ci.yml` configuration is valid. This endpoint uses all namespace +specific data available, including variables, local includes, and so on. + +```plaintext +GET /projects/:id/ci/lint +``` + +| Attribute | Type | Required | Description | +| ---------- | ------- | -------- | -------- | +| `dry_run` | boolean | no | Run pipeline creation simulation, or only do static check. | + +Example request: + +```shell +curl "https://gitlab.example.com/api/v4/projects/:id/ci/lint" +``` + +Example responses: + +- Valid configuration: + +```json +{ + "valid": true, + "merged_yaml": "---\n:test_job:\n :script: echo 1\n", + "errors": [], + "warnings": [] +} +``` + +- Invalid configuration: + +```json +{ + "valid": false, + "merged_yaml": "---\n:test_job:\n :script: echo 1\n", + "errors": [ + "jobs config should contain at least one visible job" + ], + "warnings": [] +} +``` + +## Use jq to create and process YAML & JSON payloads + +To `POST` a YAML configuration to the CI Lint endpoint, it must be properly escaped and JSON encoded. +You can use `jq` and `curl` to escape and upload YAML to the GitLab API. + +### Escape YAML for JSON encoding + +To escape quotes and encode your YAML in a format suitable for embedding within +a JSON payload, you can use `jq`. For example, create a file named `example-gitlab-ci.yml`: + +```yaml +.api_test: + rules: + - if: '$CI_PIPELINE_SOURCE=="merge_request_event"' + changes: + - src/api/* +deploy: + extends: + - .api_test + rules: + - when: manual + allow_failure: true + script: + - echo "hello world" +``` + +Next, use `jq` to escape and encode the YAML file into JSON: + +```shell +jq --raw-input --slurp < example-gitlab-ci.yml +``` + +To escape and encode an input YAML file (`example-gitlab-ci.yml`), and `POST` it to the +GitLab API using `curl` and `jq` in a one-line command: + +```shell +jq --null-input --arg yaml "$( +``` + +Example input: + +```json +{"status":"valid","errors":[],"merged_yaml":"---\n:.api_test:\n :rules:\n - :if: $CI_PIPELINE_SOURCE==\"merge_request_event\"\n :changes:\n - src/api/*\n:deploy:\n :rules:\n - :when: manual\n :allow_failure: true\n :extends:\n - \".api_test\"\n :script:\n - echo \"hello world\"\n"} +``` + +Becomes: + +```yaml +:.api_test: + :rules: + - :if: $CI_PIPELINE_SOURCE=="merge_request_event" + :changes: + - src/api/* +:deploy: + :rules: + - :when: manual + :allow_failure: true + :extends: + - ".api_test" + :script: + - echo "hello world" +``` + +With a one-line command, you can: + +1. Escape the YAML +1. Encode it in JSON +1. POST it to the API with curl +1. Format the response + +```shell +jq --null-input --arg yaml "$( [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217384) in GitLab 13.5. + +Gets a list of group members that count as billable. The list includes members in the subgroup or subproject. + +NOTE: +Unlike other API endpoints, billable members is updated once per day at 12:00 UTC. + +This function takes [pagination](README.md#pagination) parameters `page` and `per_page` to restrict the list of users. + +```plaintext +GET /groups/:id/billable_members +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/:id/billable_members" +``` + +Example response: + +```json +[ + { + "id": 1, + "username": "raymond_smith", + "name": "Raymond Smith", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root", + }, + { + "id": 2, + "username": "john_doe", + "name": "John Doe", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root", + "email": "john@example.com" + }, + { + "id": 3, + "username": "foo_bar", + "name": "Foo bar", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", + "web_url": "http://192.168.1.8:3000/root" + } +] +``` + ## Add a member to a group or project Adds a member to a group or project. @@ -235,7 +291,7 @@ POST /projects/:id/members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `user_id` | integer | yes | The user ID of the new member | +| `user_id` | integer/string | yes | The user ID of the new member or multiple IDs separated by commas | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 643d03b6fb8..89e4224c735 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -60,7 +60,7 @@ POST /projects/:id/approvals | `disable_overriding_approvers_per_merge_request` | boolean | no | Allow/Disallow overriding approvers per MR | | `merge_requests_author_approval` | boolean | no | Allow/Disallow authors from self approving merge requests; `true` means authors can self approve | | `merge_requests_disable_committers_approval` | boolean | no | Allow/Disallow committers from self approving merge requests | -| `require_password_to_approve` | boolean | no | Require approver to enter a password in order to authenticate before adding the approval | +| `require_password_to_approve` | boolean | no | Require approver to enter a password to authenticate before adding the approval | ```json { diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index faefc445210..194f48c6e84 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -72,6 +72,9 @@ Parameters: | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | | `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | | `not` | Hash | no | Return merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji` | +| `environment` | string | no | Returns merge requests deployed to the given environment +| `deployed_before` | datetime | no | Return merge requests deployed before the given date/time +| `deployed_after` | datetime | no | Return merge requests deployed after the given date/time NOTE: **Note:** [Starting in GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890), @@ -1004,6 +1007,7 @@ order for it to take effect: value of zero disables approvals for that project. 1. The provided value of `approvals_before_merge` must be greater than the target project's `approvals_before_merge`. +1. This API returns 201 (created) for a successful response. ```json { @@ -1310,7 +1314,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: " "https://git Merge changes submitted with MR using this API. -If merge request is unable to be accepted (ie: Draft, Closed, Pipeline Pending Completion, or Failed while requiring Success) - you'll get a `405` and the error message 'Method Not Allowed' +If merge request is unable to be accepted (such as Draft, Closed, Pipeline Pending Completion, or Failed while requiring Success) - you'll get a `405` and the error message 'Method Not Allowed' If it has some conflicts and can not be merged - you'll get a `406` and the error message 'Branch cannot be merged' @@ -2085,10 +2089,10 @@ the `approvals_before_merge` parameter: } ``` -## Create a to-do +## Create a to do -Manually creates a to-do for the current user on a merge request. -If there already exists a to-do for the user on that merge request, +Manually creates a to do for the current user on a merge request. +If there already exists a to do for the user on that merge request, status code `304` is returned. ```plaintext diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index 10dfd3d1c3b..c23ed657583 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts, howto --- @@ -18,14 +18,11 @@ POST /environments/:id/metrics_dashboard/annotations/ POST /clusters/:id/metrics_dashboard/annotations/ ``` -NOTE: **Note:** -The value of `dashboard_path` will be treated as a CGI-escaped path, and automatically un-escaped. - Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| -| `dashboard_path` | string | yes | ID of the dashboard which needs to be annotated. | +| `dashboard_path` | string | yes | ID of the dashboard which needs to be annotated. Treated as a CGI-escaped path, and automatically un-escaped. | | `starting_at` | string | yes | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking start point of annotation. | | `ending_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking end point of annotation. When not supplied annotation will be displayed as single event at start point. | | `description` | string | yes | Description of the annotation. | diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index df9cdd3b0e4..8c2894293ba 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: concepts, howto --- diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index ba59d467bc8..0792c6d4a3b 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -87,6 +87,26 @@ the `plan` parameter associated with a namespace: ] ``` +Users on GitLab.com will also see `max_seats_used` and `seats_in_use` parameters. +`max_seats_used` is the highest number of users the group had. `seats_in_use` is +the number of license seats currently being used. Both values are updated +once a day. + +`max_seats_used` and `seats_in_use` will be non-zero only for namespaces on paid plans. + +```json +[ + { + "id": 1, + "name": "user1", + "billable_members_count": 2, + "max_seats_used": 3, + "seats_in_use": 2, + ... + } +] +``` + NOTE: **Note:** Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **(BRONZE ONLY)**. @@ -123,6 +143,8 @@ Example response: "web_url": "https://gitlab.example.com/groups/twitter", "members_count_with_descendants": 2, "billable_members_count": 2, + "max_seats_used": 0, + "seats_in_use": 0, "plan": "default", "trial_ends_on": null, "trial": false @@ -162,6 +184,8 @@ Example response: "web_url": "https://gitlab.example.com/groups/group1", "members_count_with_descendants": 2, "billable_members_count": 2, + "max_seats_used": 0, + "seats_in_use": 0, "plan": "default", "trial_ends_on": null, "trial": false @@ -188,6 +212,8 @@ Example response: "web_url": "https://gitlab.example.com/groups/group1", "members_count_with_descendants": 2, "billable_members_count": 2, + "max_seats_used": 0, + "seats_in_use": 0, "plan": "default", "trial_ends_on": null, "trial": false diff --git a/doc/api/openapi/openapi.yaml b/doc/api/openapi/openapi.yaml index 8aa4de62501..8c46804d86f 100644 --- a/doc/api/openapi/openapi.yaml +++ b/doc/api/openapi/openapi.yaml @@ -9,9 +9,9 @@ info: When viewing this on gitlab.com, you can test API calls directly from the browser against the `gitlab.com` instance, if you are logged in. The feature uses the current [GitLab session cookie](https://docs.gitlab.com/ee/api/README.html#session-cookie), - so each request is made using your account. + so each request is made using your account. - Read more at . + Read more at . version: "v4" title: "GitLab API" termsOfService: "https://about.gitlab.com/terms/" diff --git a/doc/api/packages.md b/doc/api/packages.md index cf65b518844..d4e69b9bc66 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -26,7 +26,7 @@ GET /projects/:id/packages | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, or `type`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | -| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, or `nuget`. (_Introduced in GitLab 12.9_) +| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, or `golang`. (_Introduced in GitLab 12.9_) | `package_name` | string | no | Filter the project packages with a fuzzy search by name. (_Introduced in GitLab 12.9_) ```shell @@ -50,6 +50,19 @@ Example response: "version": "1.0.3", "package_type": "npm", "created_at": "2019-11-27T03:37:38.711Z" + }, + { + "id": 3, + "name": "Hello/0.1@mycompany/stable", + "conan_package_name": "Hello", + "version": "0.1", + "package_type": "conan", + "_links": { + "web_path": "/foo/bar/-/packages/3", + "delete_api_path": "https://gitlab.example.com/api/v4/projects/1/packages/3" + }, + "created_at": "2029-12-16T20:33:34.316Z", + "tags": [] } ] ``` @@ -73,7 +86,7 @@ GET /groups/:id/packages | `exclude_subgroups` | boolean | false | If the parameter is included as true, packages from projects from subgroups are not listed. Default is `false`. | | `order_by`| string | no | The field to use as order. One of `created_at` (default), `name`, `version`, `type`, or `project_path`. | | `sort` | string | no | The direction of the order, either `asc` (default) for ascending order or `desc` for descending order. | -| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, or `nuget`. (_Introduced in GitLab 12.9_) | +| `package_type` | string | no | Filter the returned packages by type. One of `conan`, `maven`, `npm`, `pypi`, `composer`, `nuget`, or `golang`. (_Introduced in GitLab 12.9_) | | `package_name` | string | no | Filter the project packages with a fuzzy search by name. (_[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30980) in GitLab 13.0_) ```shell diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 517e26f3d85..43310570fe8 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -24,7 +24,7 @@ curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/a ``` ```json -[ +[ { "id": 4, "name": "Test Token", @@ -45,7 +45,7 @@ curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/a ``` ```json -[ +[ { "id": 4, "name": "Test Token", diff --git a/doc/api/project_badges.md b/doc/api/project_badges.md index 936bd40d1ee..b8ea55ab72f 100644 --- a/doc/api/project_badges.md +++ b/doc/api/project_badges.md @@ -16,7 +16,7 @@ Badges support placeholders that will be replaced in real time in both the link - **%{project_path}**: will be replaced by the project path. - **%{project_id}**: will be replaced by the project ID. - **%{default_branch}**: will be replaced by the project default branch. -- **%{commit_sha}**: will be replaced by the last project's commit sha. +- **%{commit_sha}**: will be replaced by the last project's commit SHA. ## List all badges of a project diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 04694157561..ce175184179 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -8,8 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23922) in GitLab 11.7. -NOTE: **Note:** -User will need at least maintainer access to use these endpoints. +Users need at least [Maintainer](../user/permissions.md) access to use these endpoints. ## List project clusters diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index 2010fccc624..b490b6235b1 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -194,7 +194,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `project_id` | integer | yes | ID of the project | -| `destination_storage_name` | string | yes | Name of the destination storage shard | +| `destination_storage_name` | string | no | Name of the destination storage shard. If not provided the storage will be selected automatically. | Example request: diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index eccc8b4212d..cc8bb20b003 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -83,12 +83,17 @@ POST /projects/:id/snippets Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `title` (required) - The title of a snippet -- `file_name` (required) - The name of a snippet file -- `description` (optional) - The description of a snippet -- `content` (required) - The content of a snippet -- `visibility` (required) - The snippet's visibility +| Attribute | Type | Required | Description | +|:------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `title` | string | yes | Title of a snippet | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | +| `description` | string | no | Description of a snippet | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | +| `files` | array of hashes | no | An array of snippet files | +| `files:file_path` | string | yes | File path of the snippet file | +| `files:content` | string | yes | Content of the snippet file | Example request: @@ -105,9 +110,13 @@ curl --request POST "https://gitlab.com/api/v4/projects/:id/snippets" \ { "title" : "Example Snippet Title", "description" : "More verbose snippet description", - "file_name" : "example.txt", - "content" : "source code \n with multiple lines\n", - "visibility" : "private" + "visibility" : "private", + "files": [ + { + "file_path": "example.txt", + "content" : "source code \n with multiple lines\n", + } + ] } ``` @@ -121,13 +130,22 @@ PUT /projects/:id/snippets/:snippet_id Parameters: -- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `snippet_id` (required) - The ID of a project's snippet -- `title` (optional) - The title of a snippet -- `file_name` (optional) - The name of a snippet file -- `description` (optional) - The description of a snippet -- `content` (optional) - The content of a snippet -- `visibility` (optional) - The snippet's visibility +| Attribute | Type | Required | Description | +|:----------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `snippet_id` | integer | yes | The ID of a project's snippet | +| `title` | string | no | Title of a snippet | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | +| `description` | string | no | Description of a snippet | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | +| `files` | array of hashes | no | An array of snippet files | +| `files:action` | string | yes | Type of action to perform on the file, one of: 'create', 'update', 'delete', 'move' | +| `files:file_path` | string | no | File path of the snippet file | +| `files:previous_path` | string | no | Previous path of the snippet file | +| `files:content` | string | no | Content of the snippet file | + +Updates to snippets with multiple files *must* use the `files` attribute. Example request: @@ -144,9 +162,14 @@ curl --request PUT "https://gitlab.com/api/v4/projects/:id/snippets/:snippet_id" { "title" : "Updated Snippet Title", "description" : "More verbose snippet description", - "file_name" : "new_filename.txt", - "content" : "updated source code \n with multiple lines\n", - "visibility" : "private" + "visibility" : "private", + "files": [ + { + "action": "update", + "file_path": "example.txt", + "content" : "updated source code \n with multiple lines\n" + } + ] } ``` diff --git a/doc/api/projects.md b/doc/api/projects.md index ad26457ad99..f6ed905cda1 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -156,6 +156,7 @@ When the user is authenticated and `simple` is not set this returns something li "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", "ci_default_git_depth": 50, + "ci_forward_deployment_enabled": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -248,6 +249,7 @@ When the user is authenticated and `simple` is not set this returns something li "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", "ci_default_git_depth": 0, + "ci_forward_deployment_enabled": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -410,6 +412,7 @@ This endpoint supports [keyset pagination](README.md#keyset-based-pagination) fo "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", "ci_default_git_depth": 50, + "ci_forward_deployment_enabled": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -502,6 +505,7 @@ This endpoint supports [keyset pagination](README.md#keyset-based-pagination) fo "star_count": 0, "runners_token": "b8547b1dc37721d05889db52fa2f02", "ci_default_git_depth": 0, + "ci_forward_deployment_enabled": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -856,6 +860,7 @@ GET /projects/:id "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", "ci_default_git_depth": 50, + "ci_forward_deployment_enabled": true, "public_jobs": true, "shared_with_groups": [ { @@ -1218,6 +1223,7 @@ PUT /projects/:id | `build_coverage_regex` | string | no | Test coverage parsing | | `ci_config_path` | string | no | The path to CI configuration file | | `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#git-shallow-clone) | +| `ci_forward_deployment_enabled` | boolean | no | When a new deployment job starts, [skip older deployment jobs](../ci/pipelines/settings.md#skip-outdated-deployment-jobs) that are still pending | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project | | `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) | | `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | @@ -1701,6 +1707,7 @@ Example response: "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", "ci_default_git_depth": 50, + "ci_forward_deployment_enabled": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -1811,6 +1818,7 @@ Example response: "star_count": 0, "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b", "ci_default_git_depth": 50, + "ci_forward_deployment_enabled": true, "public_jobs": true, "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, @@ -2241,6 +2249,113 @@ PUT /projects/:id/transfer | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `namespace` | integer/string | yes | The ID or path of the namespace to transfer to project to | +Example request: + +```shell +curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/transfer?namespace=14" +``` + +Example response: + +```json + { + "id": 7, + "description": "", + "name": "hello-world", + "name_with_namespace": "cute-cats / hello-world", + "path": "hello-world", + "path_with_namespace": "cute-cats/hello-world", + "created_at": "2020-10-15T16:25:22.415Z", + "default_branch": "master", + "tag_list": [], + "ssh_url_to_repo": "git@gitlab.example.com:cute-cats/hello-world.git", + "http_url_to_repo": "https://gitlab.example.com/cute-cats/hello-world.git", + "web_url": "https://gitlab.example.com/cute-cats/hello-world", + "readme_url": "https://gitlab.example.com/cute-cats/hello-world/-/blob/master/README.md", + "avatar_url": null, + "forks_count": 0, + "star_count": 0, + "last_activity_at": "2020-10-15T16:25:22.415Z", + "namespace": { + "id": 18, + "name": "cute-cats", + "path": "cute-cats", + "kind": "group", + "full_path": "cute-cats", + "parent_id": null, + "avatar_url": null, + "web_url": "https://gitlab.example.com/groups/cute-cats" + }, + "_links": { + "self": "https://gitlab.example.com/api/v4/projects/7", + "issues": "https://gitlab.example.com/api/v4/projects/7/issues", + "merge_requests": "https://gitlab.example.com/api/v4/projects/7/merge_requests", + "repo_branches": "https://gitlab.example.com/api/v4/projects/7/repository/branches", + "labels": "https://gitlab.example.com/api/v4/projects/7/labels", + "events": "https://gitlab.example.com/api/v4/projects/7/events", + "members": "https://gitlab.example.com/api/v4/projects/7/members" + }, + "packages_enabled": true, + "empty_repo": false, + "archived": false, + "visibility": "private", + "resolve_outdated_diff_discussions": false, + "container_registry_enabled": true, + "container_expiration_policy": { + "cadence": "7d", + "enabled": false, + "keep_n": null, + "older_than": null, + "name_regex": null, + "name_regex_keep": null, + "next_run_at": "2020-10-22T16:25:22.746Z" + }, + "issues_enabled": true, + "merge_requests_enabled": true, + "wiki_enabled": true, + "jobs_enabled": true, + "snippets_enabled": true, + "service_desk_enabled": false, + "service_desk_address": null, + "can_create_merge_request_in": true, + "issues_access_level": "enabled", + "repository_access_level": "enabled", + "merge_requests_access_level": "enabled", + "forking_access_level": "enabled", + "wiki_access_level": "enabled", + "builds_access_level": "enabled", + "snippets_access_level": "enabled", + "pages_access_level": "enabled", + "emails_disabled": null, + "shared_runners_enabled": true, + "lfs_enabled": true, + "creator_id": 2, + "import_status": "none", + "open_issues_count": 0, + "ci_default_git_depth": 50, + "public_jobs": true, + "build_timeout": 3600, + "auto_cancel_pending_pipelines": "enabled", + "build_coverage_regex": null, + "ci_config_path": null, + "shared_with_groups": [], + "only_allow_merge_if_pipeline_succeeds": false, + "allow_merge_on_skipped_pipeline": null, + "request_access_enabled": true, + "only_allow_merge_if_all_discussions_are_resolved": false, + "remove_source_branch_after_merge": true, + "printing_merge_request_link_enabled": true, + "merge_method": "merge", + "suggestion_commit_message": null, + "auto_devops_enabled": true, + "auto_devops_deploy_strategy": "continuous", + "autoclose_referenced_issues": true, + "approvals_before_merge": 0, + "mirror": false, + "compliance_frameworks": [] +} +``` + ## Branches Read more in the [Branches](branches.md) documentation. diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index 05d586738d0..79b848bdf15 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -295,6 +295,67 @@ Example response: } ``` +### Example with allow to push and allow to merge access **(STARTER)** + +Example request: + +```shell +curl --request POST \ + --header "PRIVATE-TOKEN: " \ + --header "Content-Type: application/json" \ + --data '{ + "id": 5, + "name": "master", + "allowed_to_push": [{"access_level": 30}], + "allowed_to_merge": [{ + "access_level": 30 + },{ + "access_level": 40 + } + ]}' + "https://gitlab.example.com/api/v4/projects/5/protected_branches" +``` + +Example response: + +```json +{ + "id": 5, + "name": "master", + "push_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Maintainers", + "user_id": null, + "group_id": null + } + ], + "merge_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Maintainers", + "user_id": null, + "group_id": null + }, + { + "access_level": 40, + "access_level_description": "Maintainers", + "user_id": null, + "group_id": null + } + ], + "unprotect_access_levels": [ + { + "access_level": 40, + "access_level_description": "Maintainers", + "user_id": null, + "group_id": null + } + ], + "code_owner_approval_required": false +} +``` + ## Unprotect repository branches Unprotects the given protected branch or wildcard protected branch. diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 357f7e7a125..4dac9f61469 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -22,6 +22,8 @@ GET /projects/:id/releases | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | +| `order_by` | string | no | The field to use as order. Either `released_at` (default) or `created_at`. | +| `sort` | string | no | The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order. | Example request: @@ -361,11 +363,11 @@ POST /projects/:id/releases | `tag_name` | string | yes | The tag where the release will be created from. | | `description` | string | no | The description of the release. You can use [Markdown](../../user/markdown.md). | | `ref` | string | yes, if `tag_name` doesn't exist | If a tag specified in `tag_name` doesn't exist, the release will be created from `ref` and tagged with `tag_name`. It can be a commit SHA, another tag name, or a branch name. | -| `milestones` | array of string | no | The title of each milestone the release is associated with. | +| `milestones` | array of string | no | The title of each milestone the release is associated with. [GitLab Premium](https://about.gitlab.com/pricing/) customers can specify group milestones. | | `assets:links` | array of hash | no | An array of assets links. | | `assets:links:name`| string | required by: `assets:links` | The name of the link. | | `assets:links:url` | string | required by: `assets:links` | The URL of the link. | -| `assets:links:filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases.md). +| `assets:links:filepath` | string | no | Optional path for a [Direct Asset link](../../user/project/releases/index.md). | `assets:links:link_type` | string | no | The type of the link: `other`, `runbook`, `image`, `package`. Defaults to `other`. | `released_at` | datetime | no | The date when the release will be/was ready. Defaults to the current time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -484,6 +486,15 @@ Example response: } ``` +### Group milestones **(PREMIUM ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235391) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. + +Group milestones associated with the project may be specified in the `milestones` +array for [Create a release](#create-a-release) and [Update a release](#update-a-release) +API calls. Only milestones associated with the project's group may be specified, and +adding milestones for ancestor groups will raise an error. + ## Collect release evidence **(PREMIUM ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. @@ -525,7 +536,7 @@ PUT /projects/:id/releases/:tag_name | `tag_name` | string | yes | The tag where the release will be created from. | | `name` | string | no | The release name. | | `description` | string | no | The description of the release. You can use [Markdown](../../user/markdown.md). | -| `milestones` | array of string | no | The title of each milestone to associate with the release (`[]` to remove all milestones from the release). | +| `milestones` | array of string | no | The title of each milestone to associate with the release. [GitLab Premium](https://about.gitlab.com/pricing/) customers can specify group milestones. To remove all milestones from the release, specify `[]`. | | `released_at` | datetime | no | The date when the release will be/was ready. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | Example request: diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 305216f853a..7e94ff7b7f2 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -24,7 +24,8 @@ Parameters: - `path` (optional) - The path inside repository. Used to get content of subdirectories - `ref` (optional) - The name of a repository branch or tag or if not given the default branch - `recursive` (optional) - Boolean value used to get a recursive tree (false by default) -- `per_page` (optional) - Number of results to show per page. If not specified, defaults to `20` +- `per_page` (optional) - Number of results to show per page. If not specified, defaults to `20`. + Read more on [pagination](README.md#pagination). ```json [ diff --git a/doc/api/resource_iteration_events.md b/doc/api/resource_iteration_events.md index f774cdfe9c7..47f4d70fdf1 100644 --- a/doc/api/resource_iteration_events.md +++ b/doc/api/resource_iteration_events.md @@ -6,14 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Resource iteration events API **(STARTER)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40850) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4 -> - 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-iterations-events-tracking). - -NOTE: **Note:** -This feature might not be available to you. Check the **version history** note above for details. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229463) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229463) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. Resource iteration events keep track of what happens to GitLab [issues](../user/project/issues/). @@ -154,22 +148,3 @@ Example response: "action": "remove" } ``` - -### Enable or disable iterations events tracking **(STARTER)** - -Iterations events tracking 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(:track_iteration_change_events) -``` - -To disable it: - -```ruby -Feature.disable(:track_iteration_change_events) -``` diff --git a/doc/api/runners.md b/doc/api/runners.md index 436abe0a706..16ecdebcd4f 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -271,20 +271,20 @@ Example response: } ``` -## Remove a runner +### Pause a runner -Remove a runner. +Pause a specific runner. ```plaintext -DELETE /runners/:id +PUT --form "active=false" /runners/:runner_id ``` -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a runner | +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `runner_id` | integer | yes | The ID of a runner | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/runners/6" +curl --request PUT --header "PRIVATE-TOKEN: " --form "active=false" "https://gitlab.example.com/api/v4/runners/6" ``` ## List runner's jobs @@ -466,7 +466,7 @@ Example response: Disable a specific runner from the project. It works only if the project isn't the only project associated with the specified runner. If so, an error is -returned. Use the [Remove a runner](#remove-a-runner) call instead. +returned. Use the call to [delete a runner](#delete-a-runner) instead. ```plaintext DELETE /projects/:id/runners/:runner_id @@ -553,7 +553,7 @@ POST /runners |--------------|---------|----------|---------------------| | `token` | string | yes | [Registration token](#registration-and-authentication-tokens). | | `description`| string | no | Runner's description| -| `info` | hash | no | Runner's metadata | +| `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin area of the UI. | | `active` | boolean | no | Whether the runner is active | | `locked` | boolean | no | Whether the runner should be locked for current project | | `run_untagged` | boolean | no | Whether the runner should handle untagged jobs | @@ -580,9 +580,32 @@ Example response: } ``` -## Delete a registered runner +## Delete a runner + +There are two ways to delete a runner: + +- By specifying the runner ID. +- By specifying the runner's authentication token. -Deletes a registered runner. +### Delete a runner by ID + +To delete the runner by ID, use your access token with the runner's ID: + +```plaintext +DELETE /runners/:id +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a runner. The ID is visible in the UI under **Settings > CI/CD**. Expand **Runners**, and below the **Remove Runner** button is an ID preceded by the pound sign, for example, `#6`. | + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/runners/6" +``` + +### Delete a runner by authentication token + +To delete the runner by using its authentication token: ```plaintext DELETE /runners @@ -590,7 +613,7 @@ DELETE /runners | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `token` | string | yes | Runner's [authentication token](#registration-and-authentication-tokens). | +| `token` | string | yes | The runner's [authentication token](#registration-and-authentication-tokens). | ```shell curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=" diff --git a/doc/api/search.md b/doc/api/search.md index cb90b9a064c..bdf5bdd4924 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -24,10 +24,11 @@ GET /search | `scope` | string | yes | The scope to search in | | `search` | string | yes | The search query | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | +| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. This parameter is behind a [feature flag (`search_filter_by_confidential`)](../administration/feature_flags.md). | Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, users. -If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)** +If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs, notes, and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)** The response depends on the requested scope. @@ -362,6 +363,40 @@ Example response: NOTE: **Note:** `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +### Scope: notes **(STARTER)** + +This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/6/search?scope=notes&search=maxime" +``` + +Example response: + +```json +[ + { + "id": 191, + "body": "Harum maxime consequuntur et et deleniti assumenda facilis.", + "attachment": null, + "author": { + "id": 23, + "name": "User 1", + "username": "user1", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808?s=80&d=identicon", + "web_url": "http://localhost:3000/user1" + }, + "created_at": "2017-09-05T08:01:32.068Z", + "updated_at": "2017-09-05T08:01:32.068Z", + "system": false, + "noteable_id": 22, + "noteable_type": "Issue", + "noteable_iid": 2 + } +] +``` + ### Scope: users ```shell @@ -399,10 +434,11 @@ GET /groups/:id/search | `scope` | string | yes | The scope to search in | | `search` | string | yes | The search query | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | +| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. This parameter is behind a [feature flag (`search_filter_by_confidential`)](../administration/feature_flags.md). | Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users. -If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)** +If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs, notes, and commits. Find more about [the feature](../integration/elasticsearch.md). **(STARTER)** The response depends on the requested scope. @@ -706,6 +742,40 @@ Example response: NOTE **Note:** `filename` is deprecated in favor of `path`. Both return the full path of the file inside the repository, but in the future `filename` will be only the file name and not the full path. For details, see [issue 34521](https://gitlab.com/gitlab-org/gitlab/-/issues/34521). +### Scope: notes **(STARTER)** + +This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/6/search?scope=notes&search=maxime" +``` + +Example response: + +```json +[ + { + "id": 191, + "body": "Harum maxime consequuntur et et deleniti assumenda facilis.", + "attachment": null, + "author": { + "id": 23, + "name": "User 1", + "username": "user1", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/111d68d06e2d317b5a59c2c6c5bad808?s=80&d=identicon", + "web_url": "http://localhost:3000/user1" + }, + "created_at": "2017-09-05T08:01:32.068Z", + "updated_at": "2017-09-05T08:01:32.068Z", + "system": false, + "noteable_id": 22, + "noteable_type": "Issue", + "noteable_iid": 2 + } +] +``` + ### Scope: users ```shell @@ -744,6 +814,7 @@ GET /projects/:id/search | `search` | string | yes | The search query | | `ref` | string | no | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: commits, blobs, and wiki_blobs. | | `state` | string | no | Filter by state. Issues and merge requests are supported; it is ignored for other scopes. | +| `confidential` | boolean | no | Filter by confidentiality. Issues scope is supported; it is ignored for other scopes. This parameter is behind a [feature flag (`search_filter_by_confidential`)](../administration/feature_flags.md). | Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users. diff --git a/doc/api/services.md b/doc/api/services.md index 405047a433d..7c01e43a4d8 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -659,7 +659,7 @@ Parameters: | `webhook` | string | true | The Hangouts Chat webhook. For example, `https://chat.googleapis.com/v1/spaces...`. | | `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | | `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | -| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" | | `push_events` | boolean | false | Enable notifications for push events | | `issues_events` | boolean | false | Enable notifications for issue events | | `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | @@ -714,7 +714,7 @@ Parameters: | `merge_requests_events` | boolean | false | Enable notifications for merge request events | | `tag_push_events` | boolean | false | Enable notifications for tag push events | | `note_events` | boolean | false | Enable notifications for note events | -| `confidental_note_events` | boolean | false | Enable notifications for confidential note events | +| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | | `pipeline_events` | boolean | false | Enable notifications for pipeline events | ### Delete HipChat service diff --git a/doc/api/settings.md b/doc/api/settings.md index c8a466d1fcd..236cd10a30e 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -2,8 +2,8 @@ These API calls allow you to read and modify GitLab instance [application settings](#list-of-settings-that-can-be-accessed-via-api-calls) -as appear in `/admin/application_settings/general`. You have to be an -administrator in order to perform this action. +as they appear in `/admin/application_settings/general`. You must be an +administrator to perform this action. ## Get current application settings @@ -185,13 +185,14 @@ Example responses: **(PREMIUM ONLY)** ## List of settings that can be accessed via API calls -In general, all settings are optional. Certain settings though, if enabled, will -require other settings to be set in order to function properly. These requirements -are listed in the descriptions of the relevant settings. +In general, all settings are optional. Certain settings though, if enabled, +require other settings to be set to function properly. These requirements are +listed in the descriptions of the relevant settings. -| Attribute | Type | Required | Description | -| --------- | ---- | :------: | ----------- | -| `admin_notification_email` | string | no | Abuse reports will be sent to this address if it is set. Abuse reports are always available in the Admin Area. | +| Attribute | Type | Required | Description | +|------------------------------------------|------------------|:------------------------------------:|-------------| +| `admin_notification_email` | string | no | Deprecated: Use `abuse_notification_email` instead. If set, [abuse reports](../user/admin_area/abuse_reports.md) are sent to this address. Abuse reports are always available in the Admin Area. | +| `abuse_notification_email` | string | no | If set, [abuse reports](../user/admin_area/abuse_reports.md) are sent to this address. Abuse reports are always available in the Admin Area. | | `after_sign_out_path` | string | no | Where to redirect users after logout. | | `after_sign_up_text` | string | no | Text shown to the user after signing up | | `akismet_api_key` | string | required by: `akismet_enabled` | API key for Akismet spam protection. | @@ -208,6 +209,7 @@ are listed in the descriptions of the relevant settings. | `authorized_keys_enabled` | boolean | no | By default, we write to the `authorized_keys` file to support Git over SSH without additional configuration. GitLab can be optimized to authenticate SSH keys via the database file. Only disable this if you have configured your OpenSSH server to use the AuthorizedKeysCommand. | | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It will automatically build, test, and deploy applications based on a predefined CI/CD configuration. | +| `automatic_purchased_storage_allocation` | boolean | no | Enabling this permits automatic allocation of purchased storage within a namespace. | | `check_namespace_plan` | boolean | no | **(PREMIUM)** Enabling this will make only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | | `commit_email_hostname` | string | no | Custom hostname (for private commit emails). | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | @@ -255,10 +257,10 @@ are listed in the descriptions of the relevant settings. | `external_auth_client_cert` | string | no | (**If enabled, requires:** `external_auth_client_key`) The certificate to use to authenticate with the external authorization service | | `external_auth_client_key_pass` | string | no | Passphrase to use for the private key when authenticating with the external service this is encrypted when stored | | `external_auth_client_key` | string | required by: `external_auth_client_cert` | Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored | -| `external_authorization_service_default_label` | string | required by: `external_authorization_service_enabled` | The default classification label to use when requesting authorization and no classification label has been specified on the project | +| `external_authorization_service_default_label` | string | required by:
`external_authorization_service_enabled` | The default classification label to use when requesting authorization and no classification label has been specified on the project. | | `external_authorization_service_enabled` | boolean | no | (**If enabled, requires:** `external_authorization_service_default_label`, `external_authorization_service_timeout` and `external_authorization_service_url`) Enable using an external authorization service for accessing projects | -| `external_authorization_service_timeout` | float | required by: `external_authorization_service_enabled` | The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001) | -| `external_authorization_service_url` | string | required by: `external_authorization_service_enabled` | URL to which authorization requests will be directed | +| `external_authorization_service_timeout` | float | required by:
`external_authorization_service_enabled` | The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001). | +| `external_authorization_service_url` | string | required by:
`external_authorization_service_enabled` | URL to which authorization requests are directed. | | `file_template_project_id` | integer | no | **(PREMIUM)** The ID of a project to load custom file templates from | | `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | | `geo_node_allowed_ips` | string | yes | **(PREMIUM)** Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | @@ -298,7 +300,7 @@ are listed in the descriptions of the relevant settings. | `mirror_max_capacity` | integer | no | **(PREMIUM)** Maximum number of mirrors that can be synchronizing at the same time. | | `mirror_max_delay` | integer | no | **(PREMIUM)** Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | | `npm_package_requests_forwarding` | boolean | no | **(PREMIUM)** Use npmjs.org as a default remote repository when the package is not found in the GitLab NPM Registry | -| `outbound_local_requests_whitelist` | array of strings | no | Define a list of trusted domains or ip addresses to which local requests are allowed when local requests for hooks and services are disabled. +| `outbound_local_requests_whitelist` | array of strings | no | Define a list of trusted domains or IP addresses to which local requests are allowed when local requests for hooks and services are disabled. | `pages_domain_verification_enabled` | boolean | no | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. | | `password_authentication_enabled_for_git` | boolean | no | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. | | `password_authentication_enabled_for_web` | boolean | no | Enable authentication for the web interface via a GitLab account password. Default is `true`. | @@ -321,7 +323,7 @@ are listed in the descriptions of the relevant settings. | `receive_max_input_size` | integer | no | Maximum push size (MB). | | `repository_checks_enabled` | boolean | no | GitLab will periodically run `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | | `repository_size_limit` | integer | no | **(PREMIUM)** Size limit per repository (MB) | -| `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to weights. New projects are created in one of these stores, chosen by a weighted random selection. | +| `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to [weights](../administration/repository_storage_paths.md#choose-where-new-repositories-will-be-stored). New projects are created in one of these stores, chosen by a weighted random selection. | | `repository_storages` | array of strings | no | (GitLab 13.0 and earlier) List of names of enabled storage paths, taken from `gitlab.yml`. New projects are created in one of these stores, chosen at random. | | `require_two_factor_authentication` | boolean | no | (**If enabled, requires:** `two_factor_grace_period`) Require all users to set up Two-factor authentication. | | `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for groups, projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is `null` which means there is no restriction. | @@ -351,17 +353,17 @@ are listed in the descriptions of the relevant settings. | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. | | `terms` | text | required by: `enforce_terms` | (**Required by:** `enforce_terms`) Markdown content for the ToS. | | `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | -| `throttle_authenticated_api_period_in_seconds` | integer | required by: `throttle_authenticated_api_enabled` | Rate limit period in seconds. | -| `throttle_authenticated_api_requests_per_period` | integer | required by: `throttle_authenticated_api_enabled` | Max requests per period per user. | +| `throttle_authenticated_api_period_in_seconds` | integer | required by:
`throttle_authenticated_api_enabled` | Rate limit period in seconds. | +| `throttle_authenticated_api_requests_per_period` | integer | required by:
`throttle_authenticated_api_enabled` | Max requests per period per user. | | `throttle_authenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_web_period_in_seconds` and `throttle_authenticated_web_requests_per_period`) Enable authenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | -| `throttle_authenticated_web_period_in_seconds` | integer | required by: `throttle_authenticated_web_enabled` | Rate limit period in seconds. | -| `throttle_authenticated_web_requests_per_period` | integer | required by: `throttle_authenticated_web_enabled` | Max requests per period per user. | +| `throttle_authenticated_web_period_in_seconds` | integer | required by:
`throttle_authenticated_web_enabled` | Rate limit period in seconds. | +| `throttle_authenticated_web_requests_per_period` | integer | required by:
`throttle_authenticated_web_enabled` | Max requests per period per user. | | `throttle_unauthenticated_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | -| `throttle_unauthenticated_period_in_seconds` | integer | required by: `throttle_unauthenticated_enabled` | Rate limit period in seconds. | -| `throttle_unauthenticated_requests_per_period` | integer | required by: `throttle_unauthenticated_enabled` | Max requests per period per IP. | +| `throttle_unauthenticated_period_in_seconds` | integer | required by:
`throttle_unauthenticated_enabled` | Rate limit period in seconds. | +| `throttle_unauthenticated_requests_per_period` | integer | required by:
`throttle_unauthenticated_enabled` | Max requests per period per IP. | | `time_tracking_limit_to_hours` | boolean | no | Limit display of time tracking units to hours. Default is `false`. | | `two_factor_grace_period` | integer | required by: `require_two_factor_authentication` | Amount of time (in hours) that users are allowed to skip forced configuration of two-factor authentication. | -| `unique_ips_limit_enabled` | boolean | no | (**If enabled, requires:** `unique_ips_limit_per_user` and `unique_ips_limit_time_window`) Limit sign in from multiple ips. | +| `unique_ips_limit_enabled` | boolean | no | (**If enabled, requires:** `unique_ips_limit_per_user` and `unique_ips_limit_time_window`) Limit sign in from multiple IPs. | | `unique_ips_limit_per_user` | integer | required by: `unique_ips_limit_enabled` | Maximum number of IPs per user. | | `unique_ips_limit_time_window` | integer | required by: `unique_ips_limit_enabled` | How many seconds an IP will be counted towards the limit. | | `usage_ping_enabled` | boolean | no | Every week GitLab will report license usage back to GitLab, Inc. | diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 6863763ff24..431d745ac84 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -198,22 +198,40 @@ POST /snippets Parameters: -| Attribute | Type | Required | Description | -|:--------------|:-------|:---------|:---------------------------------------------------| -| `title` | string | yes | Title of a snippet. | -| `file_name` | string | yes | Name of a snippet file. | -| `content` | string | yes | Content of a snippet. | -| `description` | string | no | Description of a snippet. | -| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). | +| Attribute | Type | Required | Description | +|:------------------|:----------------|:---------|:--------------------------------------------------------| +| `title` | string | yes | Title of a snippet | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | +| `description` | string | no | Description of a snippet | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | +| `files` | array of hashes | no | An array of snippet files | +| `files:file_path` | string | yes | File path of the snippet file | +| `files:content` | string | yes | Content of the snippet file | Example request: ```shell -curl --request POST \ - --data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \ +curl --request POST "https://gitlab.example.com/api/v4/snippets" \ --header 'Content-Type: application/json' \ --header "PRIVATE-TOKEN: " \ - "https://gitlab.example.com/api/v4/snippets" + -d @snippet.json +``` + +`snippet.json` used in the above example request: + +```json +{ + "title": "This is a snippet", + "description": "Hello World snippet", + "visibility": "internal", + "files": [ + { + "content": "Hello world", + "file_path": "test.txt" + } + ] +} ``` Example response: @@ -222,7 +240,6 @@ Example response: { "id": 1, "title": "This is a snippet", - "file_name": "test.txt", "description": "Hello World snippet", "visibility": "internal", "author": { @@ -238,7 +255,16 @@ Example response: "created_at": "2012-06-28T10:52:04Z", "project_id": null, "web_url": "http://example.com/snippets/1", - "raw_url": "http://example.com/snippets/1/raw" + "raw_url": "http://example.com/snippets/1/raw", + "ssh_url_to_repo": "ssh://git@gitlab.example.com:snippets/1.git", + "http_url_to_repo": "https://gitlab.example.com/snippets/1.git", + "file_name": "test.txt", + "files": [ + { + "path": "text.txt", + "raw_url": "https://gitlab.example.com/-/snippets/1/raw/master/renamed.md" + } + ] } ``` @@ -255,23 +281,44 @@ PUT /snippets/:id Parameters: -| Attribute | Type | Required | Description | -|:--------------|:--------|:---------|:---------------------------------------------------| -| `id` | integer | yes | ID of snippet to update. | -| `title` | string | no | Title of a snippet. | -| `file_name` | string | no | Name of a snippet file. | -| `description` | string | no | Description of a snippet. | -| `content` | string | no | Content of a snippet. | -| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). | +| Attribute | Type | Required | Description | +|:----------------------|:----------------|:---------|:------------------------------------------------------------------------------------| +| `id` | integer | yes | ID of snippet to update | +| `title` | string | no | Title of a snippet | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | +| `description` | string | no | Description of a snippet | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | +| `files` | array of hashes | no | An array of snippet files | +| `files:action` | string | yes | Type of action to perform on the file, one of: 'create', 'update', 'delete', 'move' | +| `files:file_path` | string | no | File path of the snippet file | +| `files:previous_path` | string | no | Previous path of the snippet file | +| `files:content` | string | no | Content of the snippet file | + +Updates to snippets with multiple files *must* use the `files` attribute. Example request: ```shell -curl --request PUT \ - --data '{"title": "foo", "content": "bar"}' \ +curl --request PUT "https://gitlab.example.com/api/v4/snippets/1" \ --header 'Content-Type: application/json' \ --header "PRIVATE-TOKEN: " \ - "https://gitlab.example.com/api/v4/snippets/1" + -d @snippet.json +``` + +`snippet.json` used in the above example request: + +```json +{ + "title": "foo", + "files": [ + { + "action": "move", + "previous_path": "test.txt", + "file_path": "renamed.md" + } + ] +} ``` Example response: @@ -280,7 +327,6 @@ Example response: { "id": 1, "title": "test", - "file_name": "add.rb", "description": "description of snippet", "visibility": "internal", "author": { @@ -296,7 +342,16 @@ Example response: "created_at": "2012-06-28T10:52:04Z", "project_id": null, "web_url": "http://example.com/snippets/1", - "raw_url": "http://example.com/snippets/1/raw" + "raw_url": "http://example.com/snippets/1/raw", + "ssh_url_to_repo": "ssh://git@gitlab.example.com:snippets/1.git", + "http_url_to_repo": "https://gitlab.example.com/snippets/1.git", + "file_name": "renamed.md", + "files": [ + { + "path": "renamed.md", + "raw_url": "https://gitlab.example.com/-/snippets/1/raw/master/renamed.md" + } + ] } ``` diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index dfe22fc453e..45bc0f55095 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -135,7 +135,7 @@ Example response: ```json { "name": "Ruby", - "content": "# This file is a template, and might need editing before it works on your project.\n# Official language image. Look for the different tagged releases at:\n# https://hub.docker.com/r/library/ruby/tags/\nimage: \"ruby:2.5\"\n\n# Pick zero or more services to be used on all builds.\n# Only needed when using a docker container to run your tests in.\n# Check out: http://docs.gitlab.com/ce/ci/docker/using_docker_images.html#what-is-a-service\nservices:\n - mysql:latest\n - redis:latest\n - postgres:latest\n\nvariables:\n POSTGRES_DB: database_name\n\n# Cache gems in between builds\ncache:\n paths:\n - vendor/ruby\n\n# This is a basic example for a gem or script which doesn't use\n# services such as redis or postgres\nbefore_script:\n - ruby -v # Print out ruby version for debugging\n # Uncomment next line if your rails app needs a JS runtime:\n # - apt-get update -q && apt-get install nodejs -yqq\n - bundle install -j $(nproc) --path vendor # Install dependencies into ./vendor/ruby\n\n# Optional - Delete if not using `rubocop`\nrubocop:\n script:\n - rubocop\n\nrspec:\n script:\n - rspec spec\n\nrails:\n variables:\n DATABASE_URL: \"postgresql://postgres:postgres@postgres:5432/$POSTGRES_DB\"\n script:\n - rails db:migrate\n - rails db:seed\n - rails test\n\n# This deploy job uses a simple deploy flow to Heroku, other providers, e.g. AWS Elastic Beanstalk\n# are supported too: https://github.com/travis-ci/dpl\ndeploy:\n type: deploy\n environment: production\n script:\n - gem install dpl\n - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_PRODUCTION_KEY\n" + "content": "# This file is a template, and might need editing before it works on your project.\n# Official language image. Look for the different tagged releases at:\n# https://hub.docker.com/r/library/ruby/tags/\nimage: \"ruby:2.5\"\n\n# Pick zero or more services to be used on all builds.\n# Only needed when using a docker container to run your tests in.\n# Check out: http://docs.gitlab.com/ee/ci/docker/using_docker_images.html#what-is-a-service\nservices:\n - mysql:latest\n - redis:latest\n - postgres:latest\n\nvariables:\n POSTGRES_DB: database_name\n\n# Cache gems in between builds\ncache:\n paths:\n - vendor/ruby\n\n# This is a basic example for a gem or script which doesn't use\n# services such as redis or postgres\nbefore_script:\n - ruby -v # Print out ruby version for debugging\n # Uncomment next line if your rails app needs a JS runtime:\n # - apt-get update -q && apt-get install nodejs -yqq\n - bundle install -j $(nproc) --path vendor # Install dependencies into ./vendor/ruby\n\n# Optional - Delete if not using `rubocop`\nrubocop:\n script:\n - rubocop\n\nrspec:\n script:\n - rspec spec\n\nrails:\n variables:\n DATABASE_URL: \"postgresql://postgres:postgres@postgres:5432/$POSTGRES_DB\"\n script:\n - rails db:migrate\n - rails db:seed\n - rails test\n\n# This deploy job uses a simple deploy flow to Heroku, other providers, e.g. AWS Elastic Beanstalk\n# are supported too: https://github.com/travis-ci/dpl\ndeploy:\n type: deploy\n environment: production\n script:\n - gem install dpl\n - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_PRODUCTION_KEY\n" } ``` diff --git a/doc/api/todos.md b/doc/api/todos.md index ebe10ecbd49..ab36021d694 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -4,13 +4,13 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# To-dos API +# To dos API > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3188) in GitLab 8.10. -## Get a list of to-dos +## Get a list of to dos -Returns a list of to-dos. When no filter is applied, it returns all pending to-dos +Returns a list of to dos. When no filter is applied, it returns all pending to dos for the current user. Different filters allow the user to precise the request. ```plaintext @@ -25,8 +25,8 @@ Parameters: | `author_id` | integer | no | The ID of an author | | `project_id` | integer | no | The ID of a project | | `group_id` | integer | no | The ID of a group | -| `state` | string | no | The state of the to-do. Can be either `pending` or `done` | -| `type` | string | no | The type of a to-do. Can be either `Issue`, `MergeRequest`, `DesignManagement::Design` or `AlertManagement::Alert` | +| `state` | string | no | The state of the to do. Can be either `pending` or `done` | +| `type` | string | no | The type of a to do. Can be either `Issue`, `MergeRequest`, `DesignManagement::Design` or `AlertManagement::Alert` | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/todos" @@ -187,10 +187,10 @@ Example Response: ] ``` -## Mark a to-do as done +## Mark a to do as done -Marks a single pending to-do given by its ID for the current user as done. The -to-do marked as done is returned in the response. +Marks a single pending to do given by its ID for the current user as done. The +to do marked as done is returned in the response. ```plaintext POST /todos/:id/mark_as_done @@ -200,7 +200,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a to-do | +| `id` | integer | yes | The ID of a to do | ```shell curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/todos/130/mark_as_done" @@ -285,9 +285,9 @@ Example Response: } ``` -## Mark all to-dos as done +## Mark all to dos as done -Marks all pending to-dos for the current user as done. It returns the HTTP status code `204` with an empty response. +Marks all pending to dos for the current user as done. It returns the HTTP status code `204` with an empty response. ```plaintext POST /todos/mark_as_done diff --git a/doc/api/users.md b/doc/api/users.md index 634e0bd0842..beaea689fb7 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -950,7 +950,7 @@ Returns `204 No Content` on success, or `404 Not found` if the key cannot be fou ## List all GPG keys for given user -Get a list of a specified user's GPG keys. Available only for admins. +Get a list of a specified user's GPG keys. This endpoint can be accessed without authentication. ```plaintext GET /users/:id/gpg_keys @@ -980,7 +980,8 @@ Example response: ## Get a specific GPG key for a given user -Get a specific GPG key for a given user. Available only for admins. +Get a specific GPG key for a given user. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43693) +in GitLab 13.5, this endpoint can be accessed without admin authentication. ```plaintext GET /users/:id/gpg_keys/:key_id @@ -1209,7 +1210,9 @@ Returns: - `201 OK` on success. - `404 User Not Found` if user cannot be found. -- `403 Forbidden` when trying to block an already blocked user by LDAP synchronization. +- `403 Forbidden` when trying to block: + - A user that is blocked through LDAP. + - An internal user. ## Unblock user @@ -1246,7 +1249,8 @@ Returns: - `404 User Not Found` if user cannot be found. - `403 Forbidden` when trying to deactivate a user: - Blocked by admin or by LDAP synchronization. - - That has any activity in past 180 days. These users cannot be deactivated. + - That has any activity in past 90 days. These users cannot be deactivated. + - That is internal. ## Activate user diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 4139438bea0..c351c14e24c 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -1,6 +1,6 @@ # API V3 to API V4 -Since GitLab 9.0, API V4 is the preferred version to be used. +In GitLab 9.0 and later, API V4 is the preferred version to be used. API V3 was unsupported from GitLab 9.5, released on August 22, 2017. API v3 was removed in [GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819). diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index 73c765e2ccc..f89f2bda2eb 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -220,3 +220,53 @@ Example response: "closed_at": null } ``` + +## Revert vulnerability to detected state + +Reverts a given vulnerability to detected state. Returns status code `304` if the vulnerability is already in detected state. + +If an authenticated user does not have permission to +[revert vulnerability to detected state](../user/permissions.md#project-members-permissions), +this request will result in a `403` status code. + +```plaintext +POST /vulnerabilities/:id/revert +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer or string | yes | The ID of a vulnerability to revert to detected state | + +```shell +curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/vulnerabilities/5/dismiss" +``` + +Example response: + +```json +{ + "id": 2, + "title": "Predictable pseudorandom number generator", + "description": null, + "state": "detected", + "severity": "medium", + "confidence": "medium", + "report_type": "sast", + "project": { + "id": 32, + "name": "security-reports", + "full_path": "/gitlab-examples/security/security-reports", + "full_name": "gitlab-examples / security / security-reports" + }, + "author_id": 1, + "updated_by_id": null, + "last_edited_by_id": null, + "closed_by_id": null, + "start_date": null, + "due_date": null, + "created_at": "2019-10-13T15:08:40.219Z", + "updated_at": "2019-10-13T15:09:40.382Z", + "last_edited_at": null, + "closed_at": null +} +``` diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index d19d41b647e..0ee8a18a46a 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -198,18 +198,18 @@ The response will be `404 Not Found` if the vulnerability export is not finished Example response: ```csv -Group Name,Project Name,Scanner Type,Scanner Name,Status,Vulnerability,Details,Additional Info,Severity,CVE -Gitlab.org,Defend,container_scanning,Clair,confirmed,CVE-2017-16997 in glibc,,CVE-2017-16997 in glibc,critical,CVE-2017-16997 +Group Name,Project Name,Scanner Type,Scanner Name,Status,Vulnerability,Details,Additional Info,Severity,CVE,CWE,Other Identifiers +Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2017-16997 in glibc,,CVE-2017-16997 in glibc,critical,CVE-2017-16997 Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2017-18269 in glibc,,CVE-2017-18269 in glibc,critical,CVE-2017-18269 Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2018-1000001 in glibc,,CVE-2018-1000001 in glibc,high,CVE-2018-1000001 Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2016-10228 in glibc,,CVE-2016-10228 in glibc,medium,CVE-2016-10228 -Gitlab.org,Defend,container_scanning,Clair,confirmed,CVE-2010-4052 in glibc,,CVE-2010-4052 in glibc,low,CVE-2010-4052 +Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2010-4052 in glibc,,CVE-2010-4052 in glibc,low,CVE-2010-4052 Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2018-18520 in elfutils,,CVE-2018-18520 in elfutils,low,CVE-2018-18520 -Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2018-16869 in nettle,,CVE-2018-16869 in nettle,unknown,CVE-2018-16869 -Gitlab.org,Defend,dependency_scanning,Gemnasium,detected,Regular Expression Denial of Service in debug,,Regular Expression Denial of Service in debug,unknown,yarn.lock:debug:gemnasium:37283ed4-0380-40d7-ada7-2d994afcc62a -Gitlab.org,Defend,dependency_scanning,Gemnasium,detected,Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js,,Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js,unknown,yarn.lock:saml2-js:gemnasium:9952e574-7b5b-46fa-a270-aeb694198a98 -Gitlab.org,Defend,sast,Find Security Bugs,detected,Predictable pseudorandom number generator,,Predictable pseudorandom number generator,medium,818bf5dacb291e15d9e6dc3c5ac32178:PREDICTABLE_RANDOM:src/main/java/com/gitlab/security_products/tests/App.java:47 -Gitlab.org,Defend,sast,Find Security Bugs,detected,Cipher with no integrity,,Cipher with no integrity,medium,e6449b89335daf53c0db4c0219bc1634:CIPHER_INTEGRITY:src/main/java/com/gitlab/security_products/tests/App.java:29 -Gitlab.org,Defend,sast,Find Security Bugs,detected,Predictable pseudorandom number generator,,Predictable pseudorandom number generator,medium,e8ff1d01f74cd372f78da8f5247d3e73:PREDICTABLE_RANDOM:src/main/java/com/gitlab/security_products/tests/App.java:41 -Gitlab.org,Defend,sast,Find Security Bugs,confirmed,ECB mode is insecure 2,,ECB mode is insecure,medium,ea0f905fc76f2739d5f10a1fd1e37a10:ECB_MODE:src/main/java/com/gitlab/security_products/tests/App.java:29 -Gitlab.org,Defend,``` +Gitlab.org,Defend,container_scanning,Clair,detected,CVE-2018-16869 in nettle,,CVE-2018-16869 in nettle,unknown,CVE-2018-16869,CWE-1 +Gitlab.org,Defend,dependency_scanning,Gemnasium,detected,Regular Expression Denial of Service in debug,,Regular Expression Denial of Service in debug,unknown,CVE-2021-1234,CWE-2,"""yarn.lock:debug:gemnasium:37283ed4-0380-40d7-ada7-2d994afcc62a""" +Gitlab.org,Defend,dependency_scanning,Gemnasium,detected,Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js,,Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js,unknown,,,"""yarn.lock:saml2-js:gemnasium:9952e574-7b5b-46fa-a270-aeb694198a98""" +Gitlab.org,Defend,sast,Find Security Bugs,detected,Predictable pseudorandom number generator,,Predictable pseudorandom number generator,medium,,,"""818bf5dacb291e15d9e6dc3c5ac32178:PREDICTABLE_RANDOM:src/main/java/com/gitlab/security_products/tests/App.java:47""" +Gitlab.org,Defend,sast,Find Security Bugs,detected,Cipher with no integrity,,Cipher with no integrity,medium,,,"""e6449b89335daf53c0db4c0219bc1634:CIPHER_INTEGRITY:src/main/java/com/gitlab/security_products/tests/App.java:29""" +Gitlab.org,Defend,sast,Find Security Bugs,detected,Predictable pseudorandom number generator,,Predictable pseudorandom number generator,medium,,,"""e8ff1d01f74cd372f78da8f5247d3e73:PREDICTABLE_RANDOM:src/main/java/com/gitlab/security_products/tests/App.java:41""" +Gitlab.org,Defend,sast,Find Security Bugs,detected,ECB mode is insecure,,ECB mode is insecure,medium,,,"""ea0f905fc76f2739d5f10a1fd1e37a10:ECB_MODE:src/main/java/com/gitlab/security_products/tests/App.java:29""" +``` diff --git a/doc/api/wikis.md b/doc/api/wikis.md index 7d16a5a38ee..a8c002d4fac 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Wikis API +# Project wikis API > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13372) in GitLab 10.0. diff --git a/doc/architecture/blueprints/cloud_native_build_logs/index.md b/doc/architecture/blueprints/cloud_native_build_logs/index.md new file mode 100644 index 00000000000..25abfe36e88 --- /dev/null +++ b/doc/architecture/blueprints/cloud_native_build_logs/index.md @@ -0,0 +1,141 @@ +--- +comments: false +description: 'Next iteration of build logs architecture at GitLab' +--- + +# Cloud Native Build Logs + +Cloud native and the adoption of Kubernetes has been recognised by GitLab to be +one of the top two biggest tailwinds that are helping us grow faster as a +company behind the project. + +This effort is described in a more details [in the infrastructure team +handbook](https://about.gitlab.com/handbook/engineering/infrastructure/production/kubernetes/gitlab-com/). + +## Traditional build logs + +Traditional job logs depend a lot on availability of a local shared storage. + +Every time a GitLab Runner sends a new partial build output, we write this +output to a file on a disk. This is simple, but this mechanism depends on +shared local storage - the same file needs to be available on every GitLab web +node machine, because GitLab Runner might connect to a different one every time +it performs an API request. Sidekiq also needs access to the file because when +a job is complete, a trace file contents will be sent to the object store. + +## New architecture + +New architecture writes data to Redis instead of writing build logs into a +file. + +In order to make this performant and resilient enough, we implemented a chunked +I/O mechanism - we store data in Redis in chunks, and migrate them to an object +store once we reach a desired chunk size. + +Simplified sequence diagram is available below. + +```mermaid +sequenceDiagram + autonumber + participant U as User + participant R as Runner + participant G as GitLab (rails) + participant I as Redis + participant D as Database + participant O as Object store + + loop incremental trace update sent by a runner + Note right of R: Runner appends a build trace + R->>+G: PATCH trace [build.id, offset, data] + G->>+D: find or create chunk [chunk.index] + D-->>-G: chunk [id, index] + G->>I: append chunk data [chunk.index, data] + G-->>-R: 200 OK + end + + Note right of R: User retrieves a trace + U->>+G: GET build trace + loop every trace chunk + G->>+D: find chunk [index] + D-->>-G: chunk [id] + G->>+I: read chunk data [chunk.index] + I-->>-G: chunk data [data, size] + end + G-->>-U: build trace + + Note right of R: Trace chunk is full + R->>+G: PATCH trace [build.id, offset, data] + G->>+D: find or create chunk [chunk.index] + D-->>-G: chunk [id, index] + G->>I: append chunk data [chunk.index, data] + G->>G: chunk full [index] + G-->>-R: 200 OK + G->>+I: read chunk data [chunk.index] + I-->>-G: chunk data [data, size] + G->>O: send chunk data [data, size] + G->>+D: update data store type [chunk.id] + G->>+I: delete chunk data [chunk.index] +``` + +## NFS coupling + +In 2017, we experienced serious problems of scaling our NFS infrastructure. We +even tried to replace NFS with +[CephFS](https://docs.ceph.com/docs/master/cephfs/) - unsuccessfully. + +Since that time it has become apparent that the cost of operations and +maintenance of a NFS cluster is significant and that if we ever decide to +migrate to Kubernetes [we need to decouple GitLab from a shared local storage +and +NFS](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/426#note_375646396). + +1. NFS might be a single point of failure +1. NFS can only be reliably scaled vertically +1. Moving to Kubernetes means increasing the number of mount points by an order + of magnitude +1. NFS depends on extremely reliable network which can be difficult to provide + in Kubernetes environment +1. Storing customer data on NFS involves additional security risks + +Moving GitLab to Kubernetes without NFS decoupling would result in an explosion +of complexity, maintenance cost and enormous, negative impact on availability. + +## Iterations + +1. ✓ Implement the new architecture in way that it does not depend on shared local storage +1. ✓ Evaluate performance and edge-cases, iterate to improve the new architecture +1. ✓ Design cloud native build logs correctness verification mechanisms +1. ✓ Build observability mechanisms around performance and correctness +1. Rollout the feature into production environment incrementally + +The work needed to make the new architecture production ready and enabled on +GitLab.com is being tracked in [Cloud Native Build Logs on +GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/4275) epic. + +Enabling this feature on GitLab.com is a subtask of [making the new +architecture generally +available](https://gitlab.com/groups/gitlab-org/-/epics/3791) for everyone. + +## Who + +Proposal: + + + +| Role | Who +|------------------------------|-------------------------| +| Author | Grzegorz Bizon | +| Architecture Evolution Coach | Gerardo Lopez-Fernandez | +| Engineering Leader | Darby Frey | +| Domain Expert | Kamil Trzciński | +| Domain Expert | Sean McGivern | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Product | Jason Yavorska | +| Leadership | Darby Frey | +| Engineering | Grzegorz Bizon | + + diff --git a/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md new file mode 100644 index 00000000000..37e69d46ae1 --- /dev/null +++ b/doc/architecture/blueprints/cloud_native_gitlab_pages/index.md @@ -0,0 +1,135 @@ +--- +comments: false +description: 'Making GitLab Pages a Cloud Native application - architecture blueprint.' +--- + +# GitLab Pages New Architecture + +GitLab Pages is an important component of the GitLab product. It is mostly +being used to serve static content, and has a limited set of well defined +responsibilities. That being said, unfortunately it has become a blocker for +GitLab.com Kubernetes migration. + +Cloud Native and the adoption of Kubernetes has been recognised by GitLab to be +one of the top two biggest tailwinds that are helping us grow faster as a +company behind the project. + +This effort is described in more detail [in the infrastructure team handbook +page](https://about.gitlab.com/handbook/engineering/infrastructure/production/kubernetes/gitlab-com/). + +GitLab Pages is tightly coupled with NFS and in order to unblock Kubernetes +migration a significant change to GitLab Pages' architecture is required. This +is an ongoing work that we have started more than a year ago. This blueprint +might be useful to understand why it is important, and what is the roadmap. + +## How GitLab Pages Works + +GitLab Pages is a daemon designed to serve static content, written in +[Go](https://golang.org/). + +Initially, GitLab Pages has been designed to store static content on a local +shared block storage (NFS) in a hierarchical group > project directory +structure. Each directory, representing a project, was supposed to contain a +configuration file and static content that GitLab Pages daemon was supposed to +read and serve. + +```mermaid +graph LR + A(GitLab Rails) -- Writes new pages deployment --> B[(NFS)] + C(GitLab Pages) -. Reads static content .-> B +``` + +This initial design has become outdated because of a few reasons - NFS coupling +being one of them - and we decided to replace it with more "decoupled +service"-like architecture. The new architecture, that we are working on, is +described in this blueprint. + +## NFS coupling + +In 2017, we experienced serious problems of scaling our NFS infrastructure. We +even tried to replace NFS with +[CephFS](https://docs.ceph.com/docs/master/cephfs/) - unsuccessfully. + +Since that time it has become apparent that the cost of operations and +maintenance of a NFS cluster is significant and that if we ever decide to +migrate to Kubernetes [we need to decouple GitLab from a shared local storage +and +NFS](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/426#note_375646396). + +1. NFS might be a single point of failure +1. NFS can only be reliably scaled vertically +1. Moving to Kubernetes means increasing the number of mount points by an order + of magnitude +1. NFS depends on extremely reliable network which can be difficult to provide + in Kubernetes environment +1. Storing customer data on NFS involves additional security risks + +Moving GitLab to Kubernetes without NFS decoupling would result in an explosion +of complexity, maintenance cost and enormous, negative impact on availability. + +## New GitLab Pages Architecture + +- GitLab Pages is going to source domains' configuration from GitLab's internal + API, instead of reading `config.json` files from a local shared storage. +- GitLab Pages is going to serve static content from Object Storage. + +```mermaid +graph TD + A(User) -- Pushes pages deployment --> B{GitLab} + C((GitLab Pages)) -. Reads configuration from API .-> B + C -. Reads static content .-> D[(Object Storage)] + C -- Serves static content --> E(Visitors) +``` + +This new architecture has been briefly described in [the blog +post](https://about.gitlab.com/blog/2020/08/03/how-gitlab-pages-uses-the-gitlab-api-to-serve-content/) +too. + +## Iterations + +1. ✓ Redesign GitLab Pages configuration source to use GitLab's API +1. ✓ Evaluate performance and build reliable caching mechanisms +1. ✓ Incrementally rollout the new source on GitLab.com +1. ✓ Make GitLab Pages API domains config source enabled by default +1. Enable experimentation with different servings through feature flags +1. Triangulate object store serving design through meaningful experiments +1. Design pages migration mechanisms that can work incrementally +1. Gradually migrate towards object storage serving on GitLab.com + +[GitLab Pages Architecture](https://gitlab.com/groups/gitlab-org/-/epics/1316) +epic with detailed roadmap is also available. + +## Who + +Proposal: + + + +| Role | Who +|------------------------------|-------------------------| +| Author | Grzegorz Bizon | +| Architecture Evolution Coach | Kamil Trzciński | +| Engineering Leader | Daniel Croft | +| Domain Expert | Grzegorz Bizon | +| Domain Expert | Vladimir Shushlin | +| Domain Expert | Jaime Martinez | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Product | Jackie Porter | +| Leadership | Daniel Croft | +| Engineering | Kamil Trzciński | + +Domain Experts: + +| Role | Who +|------------------------------|------------------------| +| Domain Expert | Kamil Trzciński | +| Domain Expert | Grzegorz Bizon | +| Domain Expert | Vladimir Shushlin | +| Domain Expert | Jaime Martinez | +| Domain Expert | Krasimir Angelov | + + diff --git a/doc/architecture/blueprints/feature_flags_development/index.md b/doc/architecture/blueprints/feature_flags_development/index.md new file mode 100644 index 00000000000..0aeb2b51b39 --- /dev/null +++ b/doc/architecture/blueprints/feature_flags_development/index.md @@ -0,0 +1,140 @@ +--- +comments: false +description: 'Internal usage of Feature Flags for GitLab development' +--- + +# Usage of Feature Flags for GitLab development + +Usage of feature flags become crucial for the development of GitLab. The +feature flags are a convenient way to ship changes early, and safely rollout +them to wide audience ensuring that feature is stable and performant. + +Since the presence of feature is controlled with a dedicated condition, a +developer can decide for a best time for testing the feature, ensuring that +feature is not enable prematurely. + +## Challenges + +The extensive usage of feature flags poses a few challenges + +- Each feature flag that we add to codebase is a ~"technical debt" as it adds a + matrix of configurations. +- Testing each combination of feature flags is close to impossible, so we + instead try to optimise our testing of feature flags to the most common + scenarios. +- There's a growing challenge of maintaining a growing number of feature flags. + We sometimes forget how our feature flags are configured or why we haven't + yet removed the feature flag. +- The usage of feature flags can also be confusing to people outside of + development that might not fully understand dependence of ~feature or ~bug + fix on feature flag and how this feature flag is configured. Or if the feature + should be announced as part of release post. +- Maintaining feature flags poses additional challenge of having to manage + different configurations across different environments/target. We have + different configuration of feature flags for testing, for development, for + staging, for production and what is being shipped to our customers as part of + on-premise offering. + +## Goals + +The biggest challenge today with our feature flags usage is their implicit +nature. Feature flags are part of the codebase, making them hard to understand +outside of development function. + +We should aim to make our feature flag based development to be accessible to +any interested party. + +- developer / engineer + - can easily add a new feature flag, and configure it's state + - can quickly find who to reach if touches another feature flag + - can quickly find stale feature flags +- engineering manager + - can understand what feature flags her/his group manages +- engineering manager and director + - can understand how much ~"technical debt" is inflicted due to amount of feature flags that we have to manage + - can understand how many feature flags are added and removed in each release +- product manager and documentation writer + - can understand what features are gated by what feature flags + - can understand if feature and thus feature flag is generally available on GitLab.com + - can understand if feature and thus feature flag is enabled by default for on-premise installations +- delivery engineer + - can understand what feature flags are introduced and changed between subsequent deployments +- support and reliability engineer + - can understand how feature flags changed between releases: what feature flags become enabled, what removed + - can quickly find relevant information about feature flag to know individuals which might help with an ongoing support request or incident + +## Proposal + +To help with above goals we should aim to make our feature flags usage explicit +and understood by all involved parties. + +Introduce a YAML-described `feature-flags/` that would +allow us to have: + +1. A central place where all feature flags are documented, +1. A description of why the given feature flag was introduced, +1. A what relevant issue and merge request it was introduced by, +1. Build automated documentation with all feature flags in the codebase, +1. Track how many feature flags are per given group +1. Track how many feature flags are added and removed between releases +1. Make this information easily accessible for all +1. Allow our customers to easily discover how to enable features and quickly + find out information what did change between different releases + +### The `YAML` + +```yaml +--- +name: ci_disallow_to_create_merge_request_pipelines_in_target_project +introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40724 +rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/235119 +group: group::progressive delivery +type: development +default_enabled: false +``` + +## Reasons + +These are reason why these changes are needed: + +- we have around 500 different feature flags today +- we have hard time tracking their usage +- we have ambiguous usage of feature flag with different `default_enabled:` and + different `actors` used +- we lack a clear indication who owns what feature flag and where to find + relevant informations +- we do not emphasise the desire to create feature flag rollout issue to + indicate that feature flag is in fact a ~"technical debt" +- we don't know exactly what feature flags we have in our codebase +- we don't know exactly how our feature flags are configured for different + environments: what is being used for `test`, what we ship for `on-premise`, + what is our settings for `staging`, `qa` and `production` + +## Iterations + +This work is being done as part of dedicated epic: [Improve internal usage of +Feature Flags](https://gitlab.com/groups/gitlab-org/-/epics/3551). This epic +describes a meta reasons for making these changes. + +## Who + +Proposal: + + + +| Role | Who +|------------------------------|-------------------------| +| Author | Kamil Trzciński | +| Architecture Evolution Coach | Gerardo Lopez-Fernandez | +| Engineering Leader | Kamil Trzciński | +| Domain Expert | Shinya Maeda | + +DRIs: + +| Role | Who +|------------------------------|------------------------| +| Product | Kenny Johnston | +| Leadership | Craig Gomes | +| Engineering | Kamil Trzciński | + + diff --git a/doc/architecture/index.md b/doc/architecture/index.md new file mode 100644 index 00000000000..0a2ade6b7b0 --- /dev/null +++ b/doc/architecture/index.md @@ -0,0 +1,9 @@ +--- +comments: false +description: 'Architecture Practice at GitLab' +--- + +# Architecture at GitLab + +- [Architecture at GitLab](https://about.gitlab.com/handbook/engineering/architecture/) +- [Architecture Workflow](https://about.gitlab.com/handbook/engineering/architecture/workflow/) diff --git a/doc/articles/artifactory_and_gitlab/index.md b/doc/articles/artifactory_and_gitlab/index.md deleted file mode 100644 index ed9fd135e7c..00000000000 --- a/doc/articles/artifactory_and_gitlab/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../ci/examples/artifactory_and_gitlab/index.md' ---- - -This document was moved to [another location](../../ci/examples/artifactory_and_gitlab/index.md) diff --git a/doc/articles/how_to_configure_ldap_gitlab_ce/index.md b/doc/articles/how_to_configure_ldap_gitlab_ce/index.md deleted file mode 100644 index 2fbeb6f2506..00000000000 --- a/doc/articles/how_to_configure_ldap_gitlab_ce/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../administration/auth/ldap/index.md' ---- - -This document was moved to [another location](../../administration/auth/ldap/index.md). diff --git a/doc/articles/how_to_configure_ldap_gitlab_ee/index.md b/doc/articles/how_to_configure_ldap_gitlab_ee/index.md deleted file mode 100644 index 2fbeb6f2506..00000000000 --- a/doc/articles/how_to_configure_ldap_gitlab_ee/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../administration/auth/ldap/index.md' ---- - -This document was moved to [another location](../../administration/auth/ldap/index.md). diff --git a/doc/articles/how_to_install_git/index.md b/doc/articles/how_to_install_git/index.md deleted file mode 100644 index 62598101895..00000000000 --- a/doc/articles/how_to_install_git/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../topics/git/how_to_install_git/index.md' ---- - -This document was moved to [another location](../../topics/git/how_to_install_git/index.md). diff --git a/doc/articles/index.md b/doc/articles/index.md deleted file mode 100644 index 4b965b0256f..00000000000 --- a/doc/articles/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../topics/index.md' ---- - -This document was moved to [another location](../topics/index.md) diff --git a/doc/articles/laravel_with_gitlab_and_envoy/index.md b/doc/articles/laravel_with_gitlab_and_envoy/index.md deleted file mode 100644 index fa4f6243410..00000000000 --- a/doc/articles/laravel_with_gitlab_and_envoy/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../ci/examples/laravel_with_gitlab_and_envoy/index.md' ---- - -This document was moved to [another location](../../ci/examples/laravel_with_gitlab_and_envoy/index.md). diff --git a/doc/articles/numerous_undo_possibilities_in_git/index.md b/doc/articles/numerous_undo_possibilities_in_git/index.md deleted file mode 100644 index 83aac82db4e..00000000000 --- a/doc/articles/numerous_undo_possibilities_in_git/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../../topics/git/numerous_undo_possibilities_in_git/index.md' ---- - -This document was moved to [another location](../../topics/git/numerous_undo_possibilities_in_git/index.md). diff --git a/doc/articles/openshift_and_gitlab/index.md b/doc/articles/openshift_and_gitlab/index.md deleted file mode 100644 index 822d012aa3d..00000000000 --- a/doc/articles/openshift_and_gitlab/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_to: '../../install/openshift_and_gitlab/index.html' ---- diff --git a/doc/articles/runner_autoscale_aws/index.md b/doc/articles/runner_autoscale_aws/index.md deleted file mode 100644 index fb769731256..00000000000 --- a/doc/articles/runner_autoscale_aws/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: 'https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/index.html' ---- - -This document was moved to [another location](https://docs.gitlab.com/runner/configuration/runner_autoscale_aws/index.html). diff --git a/doc/ci/README.md b/doc/ci/README.md index 9d3f7f2a8f2..dca6d8baa79 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -16,7 +16,7 @@ through the [continuous methodologies](introduction/index.md#introduction-to-cic - Continuous Delivery (CD) - Continuous Deployment (CD) -NOTE: **Note:** +TIP: **Tip:** Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more. Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) webcast to learn about continuous methods and how GitLab’s built-in CI can help you simplify and scale software development. @@ -24,7 +24,7 @@ webcast to learn about continuous methods and how GitLab’s built-in CI can hel ## Overview Continuous Integration works by pushing small code chunks to your -application's code base hosted in a Git repository, and, to every +application's codebase hosted in a Git repository, and to every push, run a pipeline of scripts to build, test, and validate the code changes before merging them into the main branch. @@ -73,13 +73,14 @@ to your needs: ![Use a `.gitlab-ci.yml` template](img/add_file_template_11_10.png) +While building your `.gitlab-ci.yml`, you can use the [CI/CD configuration visualization](yaml/visualization.md) to facilate your writing experience. + For a broader overview, see the [CI/CD getting started](quick_start/README.md) guide. Once you're familiar with how GitLab CI/CD works, see the [`.gitlab-ci.yml` full reference](yaml/README.md) for all the attributes you can set and use. -NOTE: **Note:** GitLab CI/CD and [shared runners](runners/README.md#shared-runners) are enabled on GitLab.com and available for all users, limited only by the [pipeline quota](../user/gitlab_com/index.md#shared-runners). ## Concepts @@ -94,7 +95,7 @@ GitLab CI/CD uses a number of concepts to describe and run your build and deploy | [Job artifacts](pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. | | [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. | | [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own runners to execute your scripts. | -| [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and effienctly. | +| [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and efficiently. | ## Configuration diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 50f7d5252d8..df41f7da2d9 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -24,7 +24,6 @@ how it is defined in `.gitlab-ci.yml`. ## Cache vs artifacts -NOTE: **Note:** Be careful if you use cache and artifacts to store the same path in your jobs as **caches are restored before artifacts** and the content could be overwritten. @@ -73,7 +72,6 @@ Artifacts: - Are always uploaded to GitLab (known as coordinator). - Can have an expiration value for controlling disk usage (30 days by default). -NOTE: **Note:** Both artifacts and caches define their paths relative to the project directory, and can't link to files outside it. @@ -204,9 +202,7 @@ runs of jobs for things like dependencies and commonly used libraries (Node.js packages, PHP packages, rubygems, Python libraries, etc.), so they don't have to be re-fetched from the public internet. -NOTE: **Note:** -For more examples, check out our [GitLab CI/CD -templates](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates). +For more examples, check out our [GitLab CI/CD templates](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates). ### Caching Node.js dependencies diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index 74c48f087b2..f8e2a2b7eb0 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -9,7 +9,7 @@ type: howto GitLab CI/CD can be used with Bitbucket Cloud by: -1. Creating a [CI/CD project](../../user/project/ci_cd_for_external_repo.md). +1. Creating a [CI/CD project](index.md). 1. Connecting your Git repository via URL. To use GitLab CI/CD with a Bitbucket Cloud repository: diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index 661d935fc1d..7ee9f98bd39 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -21,7 +21,6 @@ cannot be used to authenticate with GitHub as an external CI/CD repository. ## Connect with Personal Access Token -NOTE: **Note:** Personal access tokens can only be used to connect GitHub.com repositories to GitLab, and the GitHub user must have the [owner role](https://docs.github.com/en/github/getting-started-with-github/access-permissions-on-github). @@ -53,7 +52,6 @@ GitLab will: ## Connect manually -NOTE: **Note:** To use **GitHub Enterprise** with **GitLab.com**, use this method. To manually enable GitLab CI/CD for your repository: diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 78988e8a057..c6590599849 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -74,7 +74,6 @@ If changes are pushed to the branch referenced by the Pull Request and the Pull Request is still open, a pipeline for the external pull request is created. -NOTE: **Note:** GitLab CI/CD will create 2 pipelines in this case. One for the branch push and one for the external pull request. diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index 6fa0e6d9475..af7df0e1153 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -8,7 +8,10 @@ type: howto # Cloud deployment Interacting with a major cloud provider may have become a much needed task that's -part of your delivery process. GitLab is making this process less painful by providing Docker images +part of your delivery process. With GitLab you can +[deploy your application anywhere](https://about.gitlab.com/stages-devops-lifecycle/deploy-targets/). + +For some specific deployment targets, GitLab makes this process less painful by providing Docker images that come with the needed libraries and tools pre-installed. By referencing them in your CI/CD pipeline, you'll be able to interact with your chosen cloud provider more easily. @@ -200,3 +203,81 @@ deploy: script: - aws ecs register-task-definition ... ``` + +### Provision and deploy to your AWS Elastic Compute Cloud (EC2) + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201742) in GitLab 13.5. + +You can use the `AWS/CF-Provision-and-Deploy-EC2` CI template to perform the +following actions within the same pipeline: + +1. **Create stack**: Provision your own infrastructure by leveraging the [AWS CloudFormation](https://aws.amazon.com/cloudformation/) API. +1. **Push to S3**: Push your previously-built artifact to an [AWS S3](https://aws.amazon.com/s3/) bucket. +1. **Deploy to EC2**: Deploy this pushed content onto an [AWS EC2](https://aws.amazon.com/ec2/) instance. + +![CF-Provision-and-Deploy-EC2 diagram](../img/cf_ec2_diagram_v13_5.png) + +#### Run the `AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml` template + +To run the `AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml` template, you must +pass three JSON input objects, based on existing templates: + +1. The AWS documentation provides templates for the _Create stack_ and _Deploy to EC2_ steps (links + below). We provide the template for the remaining step, _Push to S3_: + + - [Template for the _Create stack_ step on AWS](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html). + - Template for the _Push to S3_ step. Note that `source` is where a preceding `build` job built + your application, exporting the build through [`artifacts:paths`](../yaml/README.md#artifactspaths): + + ```json + { + "applicationName": "string", + "source": "string", + "s3Location": "s3://your/bucket/project_built_file...]" + } + ``` + + - [Template for the _Deploy to EC2_ step on AWS](https://docs.aws.amazon.com/codedeploy/latest/APIReference/API_CreateDeployment.html). + +1. Once you have completed these three templates based on your requirements, you + have two ways to pass in these JSON objects: + + - They can be three actual files located in your project. You must specify their path relative to + your project root in your `.gitlab-ci.yml` file, using the following variables. For example, if + your files are in a `/aws` folder: + + ```yaml + variables: + CI_AWS_CF_CREATE_STACK_FILE: 'aws/cf_create_stack.json' + CI_AWS_S3_PUSH_FILE: 'aws/s3_push.json' + CI_AWS_EC2_DEPLOYMENT_FILE: 'aws/create_deployment.json' + ``` + + - Alternatively, you can provide these JSON objects as [file-typed environment variables](../variables/README.md#custom-environment-variables-of-type-file). + In your project, go to **Settings > CI / CD > Variables** and add + the three variables listed above as file-typed environment variables. + For each variable, set the value to its corresponding JSON object. + +1. Provide the name of the stack you're creating and/or targeting, as an environment variable: + + ```yaml + variables: + CI_AWS_CF_STACK_NAME: 'YourStackName' + ``` + +1. Add this CI template to your `.gitlab-ci.yml`: + + ```yaml + include: + - template: AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml + ``` + +When running your project pipeline at this point: + +- Your AWS CloudFormation stack is created based on the content of your + `CI_AWS_CF_CREATE_STACK_FILE` file/variable. + If your stack already exists, this step is skipped, but the `provision` job it belongs to still + runs. +- Your built application is pushed to your S3 bucket then and deployed to your EC2 instance, based + on the related JSON object's content. The deployment job finishes whenever the deployment to EC2 + is done or has failed. diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 045fcd39c4d..e3123cde1cd 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -48,7 +48,6 @@ The simplest approach is to install GitLab Runner in `shell` execution mode. GitLab Runner then executes job scripts as the `gitlab-runner` user. 1. Install [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/#installation). - 1. During GitLab Runner installation select `shell` as method of executing job scripts or use command: ```shell @@ -90,7 +89,6 @@ GitLab Runner then executes job scripts as the `gitlab-runner` user. 1. You can now use `docker` command (and **install** `docker-compose` if needed). -NOTE: **Note:** By adding `gitlab-runner` to the `docker` group you are effectively granting `gitlab-runner` full root permissions. For more information please read [On Docker security: `docker` group considered harmful](https://www.andreas-jung.com/contents/on-docker-security-docker-group-considered-harmful). @@ -101,7 +99,6 @@ The second approach is to use the special Docker-in-Docker (dind) (`docker`) and run the job script in context of that image in privileged mode. -NOTE: **Note:** `docker-compose` is not part of Docker-in-Docker (dind). To use `docker-compose` in your CI builds, follow the `docker-compose` [installation instructions](https://docs.docker.com/compose/install/). @@ -149,22 +146,17 @@ released. #### TLS enabled -NOTE: **Note:** -Requires GitLab Runner 11.11 or later, but is not supported if GitLab -Runner is installed using the [Helm -chart](https://docs.gitlab.com/runner/install/kubernetes.html). See the -[related -issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/83) for -details. - The Docker daemon supports connection over TLS and it's done by default for Docker 19.03.12 or higher. This is the **suggested** way to use the Docker-in-Docker service and [GitLab.com shared runners](../../user/gitlab_com/index.md#shared-runners) support this. -1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). +GitLab Runner 11.11 or later is required, but it is not supported if GitLab +Runner is installed using the [Helm chart](https://docs.gitlab.com/runner/install/kubernetes.html). +See the [related issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/83) for details. +1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). 1. Register GitLab Runner from the command line to use `docker` and `privileged` mode: @@ -225,7 +217,7 @@ support this. # The 'docker' hostname is the alias of the service container as described at # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services. # - # Note that if you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier, + # If you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier, # the variable must be set to tcp://localhost:2376 because of how the # Kubernetes executor connects services to the job container # DOCKER_HOST: tcp://localhost:2376 @@ -287,7 +279,7 @@ variables: # The 'docker' hostname is the alias of the service container as described at # https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#accessing-the-services # - # Note that if you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier, + # If you're using GitLab Runner 12.7 or earlier with the Kubernetes executor and Kubernetes 1.6 or earlier, # the variable must be set to tcp://localhost:2375 because of how the # Kubernetes executor connects services to the job container # DOCKER_HOST: tcp://localhost:2375 @@ -324,7 +316,6 @@ are done to the services as well, making these incompatible. In order to do that, follow the steps: 1. Install [GitLab Runner](https://docs.gitlab.com/runner/install/). - 1. Register GitLab Runner from the command line to use `docker` and share `/var/run/docker.sock`: ```shell @@ -506,14 +497,13 @@ environment = ["DOCKER_DRIVER=overlay2"] If you're running multiple runners, you have to modify all configuration files. -NOTE: **Note:** Read more about the [runner configuration](https://docs.gitlab.com/runner/configuration/) and [using the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/). ## Using the GitLab Container Registry Once you've built a Docker image, you can push it up to the built-in -[GitLab Container Registry](../../user/packages/container_registry/index.md#build-and-push-images-using-gitlab-cicd). +[GitLab Container Registry](../../user/packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd). ## Troubleshooting diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 0fcd95c41ed..f7d54aa7d78 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -138,7 +138,6 @@ still succeeds even if that warning was printed. For example: As it was mentioned before, this feature is designed to provide **network accessible** services. A database is the simplest example of such a service. -NOTE: **Note:** The services feature is not designed to, and does not add any software from the defined `services` image(s) to the job's container. @@ -186,7 +185,6 @@ access to it from your build container under two hostnames to choose from: - `tutum-wordpress` - `tutum__wordpress` -NOTE: **Note:** Hostnames with underscores are not RFC valid and may cause problems in 3rd party applications. @@ -364,10 +362,9 @@ For example, the following two definitions are equal: | `name` | yes, when used with any other option | 9.4 | Full name of the image that should be used. It should contain the Registry part if needed. | | `entrypoint` | no | 9.4 |Command or script that should be executed as the container's entrypoint. It's translated to Docker's `--entrypoint` option while creating the container. The syntax is similar to [`Dockerfile`'s `ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, where each shell token is a separate string in the array. | | `command` | no | 9.4 |Command or script that should be used as the container's command. It's translated to arguments passed to Docker after the image's name. The syntax is similar to [`Dockerfile`'s `CMD`](https://docs.docker.com/engine/reference/builder/#cmd) directive, where each shell token is a separate string in the array. | -| `alias` | no | 9.4 |Additional alias that can be used to access the service from the job's container. Read [Accessing the services](#accessing-the-services) for more information. | +| `alias` (1) | no | 9.4 |Additional alias that can be used to access the service from the job's container. Read [Accessing the services](#accessing-the-services) for more information. | -NOTE: **Note:** -Alias support for the Kubernetes executor was [introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2229) in GitLab Runner 12.8, and is only available for Kubernetes version 1.7 or later. +(1) Alias support for the Kubernetes executor was [introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2229) in GitLab Runner 12.8, and is only available for Kubernetes version 1.7 or later. ### Starting multiple services from the same image @@ -532,7 +529,6 @@ To define which should be used, the GitLab Runner process reads the configuratio If the `--user` flag is provided to run the GitLab Runner child processes as unprivileged user, the home directory of the main GitLab Runner process user is used. -NOTE: **Note:** GitLab Runner reads this configuration **only** from `config.toml` and ignores it if it's provided as an environment variable. This is because GitLab Runner uses **only** `config.toml` configuration and does not interpolate **ANY** environment variables at @@ -547,6 +543,7 @@ runtime. at least version **1.8** if you want to use private registries. - Available for [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html) in GitLab Runner 13.1 and later. +- [Credentials Store](#using-credentials-store) and [Credential Helpers](#using-credential-helpers) require binaries to be added to the GitLab Runner's `$PATH`, and require access to do so. Therefore, these features are not available on shared runners or any other runner where the user does not have access to the environment where the runner is installed. ### Using statically-defined credentials @@ -600,7 +597,7 @@ There are two ways to determine the value of `DOCKER_AUTH_CONFIG`: Open a terminal and execute the following command: ```shell - # Note the use of "-n" - it prevents encoding a newline in the password. + # The use of "-n" - prevents encoding a newline in the password. echo -n "my_username:my_password" | base64 # Example output to copy @@ -650,7 +647,6 @@ follow these steps: You can add configuration for as many registries as you want, adding more registries to the `"auths"` hash as described above. -NOTE: **Note:** The full `hostname:port` combination is required everywhere for the runner to match the `DOCKER_AUTH_CONFIG`. For example, if `registry.example.com:5000/namespace/image:tag` is specified in `.gitlab-ci.yml`, @@ -679,17 +675,14 @@ To add `DOCKER_AUTH_CONFIG` to a runner: environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=\"}}}"] ``` -1. Restart the runner service. - -NOTE: **Note:** -The double quotes included in the `DOCKER_AUTH_CONFIG` -data must be escaped with backslashes. This prevents them from being -interpreted as TOML. + - The double quotes included in the `DOCKER_AUTH_CONFIG` + data must be escaped with backslashes. This prevents them from being + interpreted as TOML. + - The `environment` option is a list. Your runner may + have existing entries and you should add this to the list, not replace + it. -NOTE: **Note:** -The `environment` option is a list. So your runner may -have existing entries and you should add this to the list, not replace -it. +1. Restart the runner service. ### Using Credentials Store @@ -717,10 +710,9 @@ To configure credentials store, follow these steps: `${GITLAB_RUNNER_HOME}/.docker/config.json`. GitLab Runner reads this configuration file and uses the needed helper for this specific repository. -NOTE: **Note:** `credsStore` is used to access ALL the registries. -If you want to use both images from private registry and public images from DockerHub, -pulling from DockerHub would fail, because Docker daemon tries to use the same credentials for **ALL** the registries. +If you want to use both images from private registry and public images from Docker Hub, +pulling from Docker Hub would fail, because Docker daemon tries to use the same credentials for **ALL** the registries. ### Using Credential Helpers @@ -732,10 +724,8 @@ image which is private and requires you to log in into a private container regis To configure access for `aws_account_id.dkr.ecr.region.amazonaws.com`, follow these steps: 1. Make sure `docker-credential-ecr-login` is available in GitLab Runner's `$PATH`. - 1. Have any of the following [AWS credentials setup](https://github.com/awslabs/amazon-ecr-credential-helper#aws-credentials). Make sure that GitLab Runner can access the credentials. - 1. Make GitLab Runner use it. There are two ways to accomplish this. Either: - Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) @@ -791,7 +781,6 @@ service containers. For all possible configuration variables check the documentation of each image provided in their corresponding Docker hub page. -NOTE: **Note:** All variables are passed to all services containers. It's not designed to distinguish which variable should go where. @@ -823,7 +812,6 @@ time. ## How to debug a job locally -NOTE: **Note:** The following commands are run without root privileges. You should be able to run Docker with your regular user account. diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index a62f4db4fe4..f9b09bada14 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -17,13 +17,13 @@ kaniko solves two problems with using the build](using_docker_build.md#use-docker-in-docker-workflow-with-docker-executor) method: - Docker-in-Docker requires [privileged mode](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) - in order to function, which is a significant security concern. + to function, which is a significant security concern. - Docker-in-Docker generally incurs a performance penalty and can be quite slow. ## Requirements -In order to utilize kaniko with GitLab, [a runner](https://docs.gitlab.com/runner/) -with one of the following executors is required: +To use kaniko with GitLab, [a runner](https://docs.gitlab.com/runner/) with one +of the following executors is required: - [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html). - [Docker](https://docs.gitlab.com/runner/executors/docker.html). diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 46cf76637a4..8b88ec509e7 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -31,7 +31,6 @@ either: - Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source and Omnibus installations respectively. -NOTE: **Note:** This only applies to pipelines run as part of GitLab CI/CD. This will not enable or disable pipelines that are run from an [external integration](../user/project/integrations/overview.md#integrations-listing). diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 07d0dac6163..baf2156e64a 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -118,11 +118,9 @@ With this configuration, we: - Ensure that our app is able to be built successfully. - Lastly we deploy to the staging server. -NOTE: **Note:** -The `environment` keyword defines where the app is deployed. -The environment `name` and `url` is exposed in various places -within GitLab. Each time a job that has an environment specified -succeeds, a deployment is recorded, along with the Git SHA, and environment name. +Note that the `environment` keyword defines where the app is deployed. The environment `name` and +`url` is exposed in various places within GitLab. Each time a job that has an environment specified +succeeds, a deployment is recorded along with the Git SHA and environment name. CAUTION: **Caution:** Some characters are not allowed in environment names. Use only letters, @@ -288,12 +286,11 @@ You can find the "play" button in the pipelines, environments, deployments, and | Deployments | ![Deployments manual action](../img/environments_manual_action_deployments.png) | | Jobs | ![Builds manual action](../img/environments_manual_action_jobs.png) | -Clicking on the play button in any view will trigger the `deploy_prod` job, and the -deployment will be recorded as a new environment named `production`. +Clicking the play button in any view triggers the `deploy_prod` job. The deployment is recorded as a +new environment named `production`. -NOTE: **Note:** -If your environment's name is `production` (all lowercase), -it will get recorded in [Value Stream Analytics](../../user/project/cycle_analytics.md). +If your environment's name is `production` (all lowercase), it's recorded in +[Value Stream Analytics](../../user/analytics/value_stream_analytics.md). ### Configuring dynamic environments @@ -371,9 +368,8 @@ For the value of: the example above: `https://$CI_COMMIT_REF_NAME.example.com`, which would give a URL of `https://100-do-the-thing.example.com`. -NOTE: **Note:** -You are not required to use the same prefix or only slashes (`/`) in the dynamic environments' -names. However, using this format will enable the [grouping similar environments](#grouping-similar-environments) +You aren't required to use the same prefix or only slashes (`/`) in the dynamic environments' names. +However, using this format enables the [grouping similar environments](#grouping-similar-environments) feature. ### Configuring Kubernetes deployments @@ -384,6 +380,12 @@ If you are deploying to a [Kubernetes cluster](../../user/project/clusters/index associated with your project, you can configure these deployments from your `gitlab-ci.yml` file. +NOTE: **Note:** +Kubernetes configuration isn't supported for Kubernetes clusters that are +[managed by GitLab](../../user/project/clusters/index.md#gitlab-managed-clusters). +To follow progress on support for GitLab-managed clusters, see the +[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054). + The following configuration options are supported: - [`namespace`](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) @@ -411,12 +413,6 @@ trace on the deployment job page: ![Deployment cluster information](../img/environments_deployment_cluster_v12_8.png) -NOTE: **Note:** -Kubernetes configuration is not supported for Kubernetes clusters -that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed-clusters). -To follow progress on support for GitLab-managed clusters, see the -[relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054). - #### Configuring incremental rollouts Learn how to release production changes to only a portion of your Kubernetes pods with @@ -514,9 +510,8 @@ review_app: This example requires that NGINX and GitLab Runner are set up on the server this job will run on. -NOTE: **Note:** -See the [limitations](#limitations) section for some edge cases regarding the naming of -your branches and Review Apps. +See the [limitations](#limitations) section for some edge cases regarding the naming of your +branches and Review Apps. The complete example provides the following workflow to developers: @@ -617,13 +612,12 @@ To retry or rollback a deployment: #### What to expect with a rollback -Pressing the **Rollback** button on a specific commit will trigger a _new_ deployment with its -own unique job ID. - -This means that you will see a new deployment that points to the commit you are rolling back to. +Pressing the **Rollback** button on a specific commit triggers a _new_ deployment with its own +unique job ID. This means that you will see a new deployment that points to the commit you're +rolling back to. -NOTE: **Note:** -The defined deployment process in the job's `script` determines whether the rollback succeeds or not. +Note that the defined deployment process in the job's `script` determines whether the rollback +succeeds. ### Using the environment URL @@ -662,9 +656,8 @@ Stopping an environment: This is often used when multiple developers are working on a project at the same time, each of them pushing to their own branches, causing many dynamic environments to be created. -NOTE: **Note:** -Starting with GitLab 8.14, dynamic environments are stopped automatically -when their associated branch is deleted. +Starting with GitLab 8.14, dynamic environments stop automatically when their associated branch is +deleted. #### Automatically stopping an environment @@ -721,29 +714,25 @@ You can read more in the [`.gitlab-ci.yml` reference](../yaml/README.md#environm > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8. -You can set a expiry time to environments and stop them automatically after a certain period. +You can set an expiry time for environments and stop them automatically after a certain period. -For example, consider the use of this feature with Review Apps environments. -When you set up Review Apps, sometimes they keep running for a long time -because some merge requests are left as open. An example for this situation is when the author of the merge -request is not actively working on it, due to priority changes or a different approach was decided on, and the merge requests was simply forgotten. -Idle environments waste resources, therefore they -should be terminated as soon as possible. +For example, consider the use of this feature with Review App environments. When you set up Review +Apps, sometimes they keep running for a long time because some merge requests are left open and +forgotten. Such idle environments waste resources and should be terminated as soon as possible. -To address this problem, you can specify an optional expiration date for -Review Apps environments. When the expiry time is reached, GitLab will automatically trigger a job -to stop the environment, eliminating the need of manually doing so. In case an environment is updated, the expiration is renewed -ensuring that only active merge requests keep running Review Apps. +To address this problem, you can specify an optional expiration date for Review App environments. +When the expiry time is reached, GitLab automatically triggers a job to stop the environment, +eliminating the need of manually doing so. In case an environment is updated, the expiration is +renewed ensuring that only active merge requests keep running Review Apps. -To enable this feature, you need to specify the [`environment:auto_stop_in`](../yaml/README.md#environmentauto_stop_in) keyword in `.gitlab-ci.yml`. -You can specify a human-friendly date as the value, such as `1 hour and 30 minutes` or `1 day`. -`auto_stop_in` uses the same format of [`artifacts:expire_in` docs](../yaml/README.md#artifactsexpire_in). +To enable this feature, you must specify the [`environment:auto_stop_in`](../yaml/README.md#environmentauto_stop_in) +keyword in `.gitlab-ci.yml`. You can specify a human-friendly date as the value, such as +`1 hour and 30 minutes` or `1 day`. `auto_stop_in` uses the same format of +[`artifacts:expire_in` docs](../yaml/README.md#artifactsexpire_in). -NOTE: **Note:** -Due to the resource limitation, a background worker for stopping environments only -runs once every hour. This means environments will not be stopped at the exact -timestamp as the specified period, but will be stopped when the hourly cron worker -detects expired environments. +Note that due to resource limitation, a background worker for stopping environments only runs once +every hour. This means that environments aren't stopped at the exact timestamp specified, but are +instead stopped when the hourly cron worker detects expired environments. ##### Auto-stop example @@ -866,7 +855,7 @@ exist, you should see something like: ### Environment incident management -You have successfuly setup a Continous Delivery/Deployment workflow in your project. +You have successfully setup a Continuous Delivery/Deployment workflow in your project. Production environments can go down unexpectedly, including for reasons outside of your own control. For example, issues with external dependencies, infrastructure, or human error can cause major issues with an environment. This could include: @@ -903,8 +892,7 @@ you can monitor the behavior of your app running in each environment. For the mo dashboard to appear, you need to Configure Prometheus to collect at least one [supported metric](../../user/project/integrations/prometheus_library/index.md). -NOTE: **Note:** -Since GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard. +In GitLab 9.2 and later, all deployments to an environment are shown directly on the monitoring dashboard. Once configured, GitLab will attempt to retrieve [supported performance metrics](../../user/project/integrations/prometheus_library/index.md) for any environment that has had a successful deployment. If monitoring data was @@ -938,6 +926,11 @@ This is a powerful feature that allows you to debug issues without leaving the c of your web browser. To enable it, just follow the instructions given in the service integration documentation. +NOTE: **Note:** +Container-based deployments often lack basic tools (like an editor), and may +be stopped or restarted at any time. If this happens, you will lose all your +changes. Treat this as a debugging tool, not a comprehensive online IDE. + Once enabled, your environments will gain a "terminal" button: ![Terminal button on environment index](../img/environments_terminal_button_on_index.png) @@ -961,14 +954,9 @@ by your deployment so you can: You can open multiple terminals to the same environment, they each get their own shell session and even a multiplexer like `screen` or `tmux`. -NOTE: **Note:** -Container-based deployments often lack basic tools (like an editor), and may -be stopped or restarted at any time. If this happens, you will lose all your -changes. Treat this as a debugging tool, not a comprehensive online IDE. - ### Check out deployments locally -Since GitLab 8.13, a reference in the Git repository is saved for each deployment, so +In GitLab 8.13 and later, a reference in the Git repository is saved for each deployment, so knowing the state of your current environments is only a `git fetch` away. In your Git configuration, append the `[remote ""]` block with an extra @@ -1024,9 +1012,8 @@ As you can see, you can use specific matching for selecting a particular environ and also use wildcard matching (`*`) for selecting a particular environment group, such as [Review Apps](../review_apps/index.md) (`review/*`). -NOTE: **Note:** -The most _specific_ spec takes precedence over the other wildcard matching. -In this case, `review/feature-1` spec takes precedence over `review/*` and `*` specs. +Note that the most _specific_ spec takes precedence over the other wildcard matching. In this case, +the `review/feature-1` spec takes precedence over `review/*` and `*` specs. ### Environments Dashboard **(PREMIUM)** diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 5dda0cc81f6..87bced29906 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -9,8 +9,6 @@ type: concepts, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6303) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. -## Overview - [Environments](../environments/index.md) can be used for different reasons: - Some of them are just for testing. diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md index 2abb2cc1b0d..e2ee05923cd 100644 --- a/doc/ci/examples/artifactory_and_gitlab/index.md +++ b/doc/ci/examples/artifactory_and_gitlab/index.md @@ -23,10 +23,10 @@ We also assume that an Artifactory instance is available and reachable from the ## Create the simple Maven dependency -First of all, you need an application to work with: in this specific case we will -use a simple one, but it could be any Maven application. This will be the -dependency you want to package and deploy to Artifactory, in order to be -available to other projects. +First, you need an application to work with: in this specific case we'll use a +simple one, but it could be any Maven application. This will be the dependency +you want to package and deploy to Artifactory, to be available to other +projects. ### Prepare the dependency application @@ -58,7 +58,7 @@ The application is ready to use, but you need some additional steps to deploy it 1. Log in to Artifactory with your user's credentials. 1. From the main screen, click on the `libs-release-local` item in the **Set Me Up** panel. 1. Copy to clipboard the configuration snippet under the **Deploy** paragraph. -1. Change the `url` value in order to have it configurable via variables. +1. Change the `url` value to have it configurable by using variables. 1. Copy the snippet in the `pom.xml` file for your project, just after the `dependencies` section. The snippet should look like this: @@ -146,8 +146,9 @@ deploy: - master ``` -The runner will use the latest [Maven Docker image](https://hub.docker.com/_/maven/), which already contains all the tools and the dependencies you need to manage the project, -in order to run the jobs. +The runner uses the latest [Maven Docker image](https://hub.docker.com/_/maven/), +which contains all of the tools and dependencies needed to manage the project +and to run the jobs. Environment variables are set to instruct Maven to use the `homedir` of the repository instead of the user's home when searching for configuration and dependencies. diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index 73896547675..4a0ff2fa6ac 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -41,15 +41,14 @@ The JWT's payload looks like this: "nbf": 1585798372, # Not valid before "exp": 1585713886, # Expire at "sub": "job_1212", # Subject (job id) - "namespace_id": "1", - "namespace_path": "mygroup", - "project_id": "22", - "project_path": "mygroup/myproject", - "user_id": "42", - "user_login": "myuser", - "user_email": "myuser@example.com", - "pipeline_id": "1212", - "job_id": "1212", + "namespace_id": "1", # Use this to scope to group or user level namespace by id + "namespace_path": "mygroup", # Use this to scope to group or user level namespace by path + "project_id": "22", # + "project_path": "mygroup/myproject", # + "user_id": "42", # Id of the user executing the job + "user_email": "myuser@example.com", # Email of the user executing the job + "pipeline_id": "1212", # + "job_id": "1212", # "ref": "auto-deploy-2020-04-01", # Git ref for this job "ref_type": "branch", # Git ref type, branch or tag "ref_protected": "true" # true if this git ref is protected, false otherwise diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index 1f6c81a68aa..aa6e6f73a0d 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -9,7 +9,7 @@ type: tutorial [Review Apps](../../review_apps/index.md) are great: for every merge request (or branch, for that matter), the new code can be copied and deployed to a fresh production-like live -environment, making it incredibly low-effort to assess the impact of the changes. Thus, when we use a dependency manager like +environment, reducing the effort to assess the impact of changes. Thus, when we use a dependency manager like [Dependencies.io](https://www.dependencies.io/), it can submit a merge request with an updated dependency, and it will immediately be clear that the application can still be properly built and deployed. After all, you can _see_ it running! @@ -95,9 +95,10 @@ dependency upgrade did not break anything without even having to look at your we ## Running locally -We'll get to running the above test in CI/CD in a moment. When writing tests, however, it helps if -you do not have to wait for your pipelines to succeed in order to check whether they do what you -expect them to do. In other words, let's get it to run locally. +We'll get to running the above test in CI/CD in a moment. When writing tests, +however, it helps if you don't have to wait for your pipelines to succeed to +determine whether they do what you expect them to do. In other words, let's get +it to run locally. Make sure that your app is running locally. If you use Webpack, you can use [the Webpack Dev Server WebdriverIO plugin](https://www.npmjs.com/package/wdio-webpack-dev-server-service) diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index 8927c5c3480..aaa34afeddf 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -143,7 +143,6 @@ Now, let's clone our repository on the server just to make sure the `deployer` u git clone git@gitlab.example.com:/laravel-sample.git ``` -NOTE: **Note:** Answer **yes** if asked `Are you sure you want to continue connecting (yes/no)?`. It adds GitLab.com to the known hosts. @@ -167,7 +166,6 @@ server { } ``` -NOTE: **Note:** You may replace the app's name in `/var/www/app/current/public` with the folder name of your application. ## Setting up Envoy @@ -397,8 +395,6 @@ To be able to build, test, and deploy our app with GitLab CI/CD, we need to prep To do that, we'll use a Docker image which has the minimum requirements that a Laravel app needs to run. [There are other ways](../php.md#test-php-projects-using-the-docker-executor) to do that as well, but they may lead our builds run slowly, which is not what we want when there are faster options to use. -With Docker images our builds run incredibly faster! - ### Create a Container Image Let's create a [Dockerfile](https://gitlab.com/mehranrasulian/laravel-sample/blob/master/Dockerfile) in the root directory of our app with the following content: @@ -441,9 +437,11 @@ On your GitLab project repository navigate to the **Registry** tab. ![container registry page empty image](img/container_registry_page_empty_image.png) -You may need to [enable Container Registry](../../../user/packages/container_registry/index.md#enable-the-container-registry-for-your-project) to your project to see this tab. You'll find it under your project's **Settings > General > Visibility, project features, permissions**. +You may need to enable the Container Registry for your project to see this tab. You'll find it under your project's **Settings > General > Visibility, project features, permissions**. -To start using Container Registry on our machine, we first need to login to the GitLab registry using our GitLab username and password: +To start using Container Registry on our machine, we first need to sign in to the GitLab registry using our GitLab username and password. +Make sure you have [Docker](https://docs.docker.com/engine/installation/) installed on our machine, +then run the following commands: ```shell docker login registry.gitlab.com @@ -457,14 +455,10 @@ docker build -t registry.gitlab.com//laravel-sample . docker push registry.gitlab.com//laravel-sample ``` -NOTE: **Note:** -To run the above commands, we first need to have [Docker](https://docs.docker.com/engine/installation/) installed on our machine. - Congratulations! You just pushed the first Docker image to the GitLab Registry, and if you refresh the page you should be able to see it: ![container registry page with image](img/container_registry_page_with_image.jpg) -NOTE: **Note:** You can also [use GitLab CI/CD](https://about.gitlab.com/blog/2016/05/23/gitlab-container-registry/#use-with-gitlab-ci) to build and push your Docker images, rather than doing that on your machine. We'll use this image further down in the `.gitlab-ci.yml` configuration file to handle the process of testing and deploying our app. @@ -544,7 +538,6 @@ services: ... ``` -NOTE: **Note:** If you wish to test your app with different PHP versions and [database management systems](../../services/README.md), you can define different `image` and `services` keywords for each test job. #### Variables diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index ab6ff1dc177..699d04f632c 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -141,12 +141,11 @@ Of course, `my_php.ini` must be present in the root directory of your repository ## Test PHP projects using the Shell executor -The shell executor runs your job in a terminal session on your server. -Thus, in order to test your projects you first need to make sure that all -dependencies are installed. +The shell executor runs your job in a terminal session on your server. To test +your projects, you must first ensure that all dependencies are installed. -For example, in a VM running Debian 8 we first update the cache, then we -install `phpunit` and `php5-mysql`: +For example, in a VM running Debian 8, first update the cache, and then install +`phpunit` and `php5-mysql`: ```shell sudo apt-get update -y @@ -219,8 +218,8 @@ test:atoum: ### Using Composer The majority of the PHP projects use Composer for managing their PHP packages. -In order to execute Composer before running your tests, simply add the -following in your `.gitlab-ci.yml`: +To execute Composer before running your tests, add the following to your +`.gitlab-ci.yml`: ```yaml # Composer stores all downloaded packages in the vendor/ directory. @@ -243,14 +242,14 @@ before_script: ## Access private packages or dependencies If your test suite needs to access a private repository, you need to configure -[the SSH keys](../ssh_keys/README.md) in order to be able to clone it. +the [SSH keys](../ssh_keys/README.md) to be able to clone it. ## Use databases or other services -Most of the time you will need a running database in order for your tests to -run. If you are using the Docker executor you can leverage Docker's ability to -link to other containers. With GitLab Runner, this can be achieved by -defining a `service`. +Most of the time, you need a running database for your tests to be able to +run. If you're using the Docker executor, you can leverage Docker's ability to +link to other containers. With GitLab Runner, this can be achieved by defining +a `service`. This functionality is covered in [the CI services](../services/README.md) documentation. diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md index 066c0cf214f..86c979c489c 100644 --- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md @@ -68,7 +68,7 @@ First install [Docker Engine](https://docs.docker.com/installation/). To build this project you also need to have [GitLab Runner](https://docs.gitlab.com/runner/). You can use public runners available on `gitlab.com` or register your own. Start by -creating a template configuration file in order to pass complex configuration: +creating a template configuration file to pass complex configuration: ```shell cat > /tmp/test-config.template.toml << EOF diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index ab6a4d3f507..c62f0dec598 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -117,7 +117,6 @@ Generated hello_gitlab_ci app The database for HelloGitlabCi.Repo has been created ``` -NOTE: **Note:** Phoenix assumes that our PostgreSQL database will have a `postgres` user account with the correct permissions and a password of `postgres`. If it's not your case, check [Ecto's instructions](https://hexdocs.pm/ecto/Ecto.html#module-repositories). @@ -205,7 +204,6 @@ when running our Phoenix in our `localhost`. Without `.gitkeep`, Git will not upload this empty directory and we'll got an error when running our test on GitLab. - NOTE: **Note:** If we add a folder via the GitLab UI, GitLab itself will add the `.gitkeep` to that new dir. Now, let's run a local test and see if everything we did didn't break anything. diff --git a/doc/ci/img/cf_ec2_diagram_v13_5.png b/doc/ci/img/cf_ec2_diagram_v13_5.png new file mode 100644 index 00000000000..1d49790c7b9 Binary files /dev/null and b/doc/ci/img/cf_ec2_diagram_v13_5.png differ diff --git a/doc/ci/img/ci_lint.png b/doc/ci/img/ci_lint.png index e62de011293..fdc3868cdce 100644 Binary files a/doc/ci/img/ci_lint.png and b/doc/ci/img/ci_lint.png differ diff --git a/doc/ci/img/ci_lint_dry_run.png b/doc/ci/img/ci_lint_dry_run.png index 4092b66d534..61d6379f70e 100644 Binary files a/doc/ci/img/ci_lint_dry_run.png and b/doc/ci/img/ci_lint_dry_run.png differ diff --git a/doc/ci/img/gitlab_vault_workflow_v13_4.png b/doc/ci/img/gitlab_vault_workflow_v13_4.png new file mode 100644 index 00000000000..80d07362bf4 Binary files /dev/null and b/doc/ci/img/gitlab_vault_workflow_v13_4.png differ diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index db2749233e8..d1f3e449e5b 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -12,7 +12,7 @@ In this document, we'll present an overview of the concepts of Continuous Integr Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD. -NOTE: **Note:** +TIP: **Tip:** Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more. Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) webcast to learn about continuous methods and how GitLab’s built-in CI can help you simplify and scale software development. @@ -154,7 +154,7 @@ commits to a feature branch in a remote repository in GitLab, the CI/CD pipeline set for your project is triggered. By doing so, GitLab CI/CD: -- Runs automated scripts (sequential or parallel) to: +- Runs automated scripts (sequentially or in parallel) to: - Build and test your app. - Preview the changes per merge request with Review Apps, as you would see in your `localhost`. diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index 3ce62936168..cc0b4ac1f86 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -24,7 +24,6 @@ can run a pipeline for merge requests. ![Merge request page](img/merge_request.png) -NOTE: **Note:** If you use this feature with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md), pipelines for merge requests take precedence over the other regular pipelines. @@ -125,8 +124,9 @@ Therefore: - Since `C` specifies that it should only run for merge requests, it will not run for any pipeline except a merge request pipeline. -This helps you avoid having to add the `only:` rule to all of your jobs -in order to make them always run. You can use this format to set up a Review App, helping to save resources. +This helps you avoid having to add the `only:` rule to all of your jobs to make +them always run. You can use this format to set up a Review App, helping to +save resources. #### Excluding certain branches diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index dd08f9248f6..2330bdb4c7c 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -80,8 +80,8 @@ For more information, read the [documentation on Merge Trains](merge_trains/inde > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12996) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3. -GitLab CI/CD can detect the presence of redundant pipelines, -and will cancel them automatically in order to conserve CI resources. +GitLab CI/CD can detect the presence of redundant pipelines, and cancels them +to conserve CI resources. When a user merges a merge request immediately within an ongoing merge train, the train will be reconstructed, as it will recreate the expected diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md index 1f88e8f832f..45cae49377f 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -37,7 +37,6 @@ run. To add a merge request to a merge train, you need [permissions](../../../../user/permissions.md) to push to the target branch. -NOTE: **Note:** Each merge train can run a maximum of **twenty** pipelines in parallel. If more than twenty merge requests are added to the merge train, the merge requests will be queued until a slot in the merge train is free. There is no limit to the diff --git a/doc/ci/metrics_reports.md b/doc/ci/metrics_reports.md index 4f4471225a0..53e097760e6 100644 --- a/doc/ci/metrics_reports.md +++ b/doc/ci/metrics_reports.md @@ -9,8 +9,6 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9788) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. Requires GitLab Runner 11.10 and above. -## Overview - GitLab provides a lot of great reporting tools for [merge requests](../user/project/merge_requests/index.md) - [Unit test reports](unit_test_reports.md), [code quality](../user/project/merge_requests/code_quality.md), performance tests, etc. While JUnit is a great open framework for tests that "pass" or "fail", it is also important to see other types of metrics from a given change. You can configure your job to use custom Metrics Reports, and GitLab will display a report on the merge request so that it's easier and faster to identify changes without having to check the entire log. diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 8dff99f7244..1130c11f472 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -23,7 +23,7 @@ that were able to quickly complete this migration: 1. Use the [Jenkins Wrapper](#jenkinsfile-wrapper) to temporarily maintain fragile Jenkins jobs. 1. Migrate the build and CI jobs and configure them to show results directly in your merge requests. They can use [Auto DevOps](../../topics/autodevops/index.md) as a starting point, and [customize](../../topics/autodevops/customize.md) or [decompose](../../topics/autodevops/customize.md#using-components-of-auto-devops) the configuration as needed. 1. Add [Review Apps](../review_apps/index.md). - 1. Migrate the deployment jobs using [cloud deployment templates](../cloud_deployment/index.md), adding [environments](../environments/index.md), and [deploy boards](../..//user/project/deploy_boards.md). + 1. Migrate the deployment jobs using [cloud deployment templates](../cloud_deployment/index.md), adding [environments](../environments/index.md), and [deploy boards](../../user/project/deploy_boards.md). 1. Work to unwrap any jobs still running with the use of the Jenkins wrapper. 1. Take stock of any common CI/CD job definitions then create and share [templates](#templates) for them. 1. Check the [pipeline efficiency documentation](../pipelines/pipeline_efficiency.md) @@ -83,7 +83,7 @@ There are some high level differences between the products worth mentioning: - You can control which jobs run in which cases, depending on how they are triggered, with the [`rules` syntax](../yaml/README.md#rules). -- GitLab [pipeline scheduling concepts](../pipelines/schedules.md) are also different than with Jenkins. +- GitLab [pipeline scheduling concepts](../pipelines/schedules.md) are also different from Jenkins. - You can reuse pipeline configurations using the [`include` keyword](../yaml/README.md#include) and [templates](#templates). Your templates can be kept in a central repository (with different permissions), and then any project can use them. This central project could also diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 3f9a00b6cc8..378adcd35e9 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -163,6 +163,8 @@ have permission to run CI/CD pipelines against the protected branch, the pipelin ### Passing variables to a downstream pipeline +#### With the `variables` keyword + Sometimes you might want to pass variables to a downstream pipeline. You can do that using the `variables` keyword, just like you would when defining a regular job. @@ -211,10 +213,49 @@ In this scenario, the `UPSTREAM_BRANCH` variable with a value related to the upstream pipeline will be passed to the `downstream-job` job, and will be available within the context of all downstream builds. -NOTE: **Tip:** Upstream pipelines take precedence over downstream ones. If there are two variables with the same name defined in both upstream and downstream projects, -the ones defined in the upstream project will take precedence. +the ones defined in the upstream project take precedence. + +#### With variable inheritance + +You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](variables/README.md#inherit-environment-variables) and [cross project artifact downloads](yaml/README.md#cross-project-artifact-downloads-with-needs). + +In the upstream pipeline: + +1. Save the variables in a `.env` file. +1. Save the `.env` file as a `dotenv` report. +1. Trigger the downstream pipeline. + +```yaml +build_vars: + stage: build + script: + - echo "BUILD_VERSION=hello" >> build.env + artifacts: + reports: + dotenv: build.env + +deploy: + stage: deploy + trigger: my/downstream_project +``` + +Set the `test` job in the downstream pipeline to inherit the variables from the `build_vars` +job in the upstream project with `needs:`. The `test` job inherits the variables in the +`dotenv` report and it can access `BUILD_VERSION` in the script: + +```yaml +test: + stage: test + script: + - echo $BUILD_VERSION + needs: + - project: my/upstream_project + job: build_vars + ref: master + artifacts: true +``` ### Mirroring status from triggered pipeline @@ -280,3 +321,11 @@ Any pipelines that complete successfully for new tags in the subscribed project will now trigger a pipeline on the current project's default branch. The maximum number of upstream pipeline subscriptions is 2 by default, for both the upstream and downstream projects. This [application limit](../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) can be changed on self-managed instances by a GitLab administrator. + +## Downstream private projects confidentiality concern + +If you trigger a pipeline in a downstream private project, the name of the project +and the status of the pipeline is visible in the upstream project's pipelines page. + +If you have a public project that can trigger downstream pipelines in a private +project, make sure to check that there are no confidentiality problems. diff --git a/doc/ci/parent_child_pipelines.md b/doc/ci/parent_child_pipelines.md index 83fa1d355e6..a0965643970 100644 --- a/doc/ci/parent_child_pipelines.md +++ b/doc/ci/parent_child_pipelines.md @@ -68,11 +68,22 @@ microservice_a: trigger: include: - local: path/to/microservice_a.yml - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml ``` -NOTE: **Note:** -The max number of entries that are accepted for `trigger:include:` is three. +In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/205157) and later, +you can use [`include:file`](yaml/README.md#includefile) to trigger child pipelines +with a configuration file in a different project: + +```yaml +microservice_a: + trigger: + include: + - project: 'my-group/my-pipeline-library' + file: 'path/to/ci-config.yml' +``` + +The maximum number of entries that are accepted for `trigger:include:` is three. Similar to [multi-project pipelines](multi_project_pipelines.md#mirroring-status-from-triggered-pipeline), we can set the parent pipeline to depend on the status of the child pipeline upon completion: @@ -82,7 +93,7 @@ microservice_a: trigger: include: - local: path/to/microservice_a.yml - - template: SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml strategy: depend ``` @@ -153,32 +164,13 @@ This is [resolved in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues ## Nested child pipelines > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29651) in GitLab 13.4. -> - 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-nested-child-pipelines). **(CORE ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/243747) in GitLab 13.5. Parent and child pipelines were introduced with a maximum depth of one level of child pipelines, which was later increased to two. A parent pipeline can trigger many child pipelines, and these child pipelines can trigger their own child pipelines. It's not possible to trigger another level of child pipelines. -### Enable or disable nested child pipelines **(CORE ONLY)** +## Pass variables to a child pipeline -Nested child pipelines with a depth of two are under development but ready for -production use. This feature is deployed behind a feature flag that is **enabled by default**. - -[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:ci_child_of_child_pipeline) -``` - -To disable it: - -```ruby -Feature.disable(:ci_child_of_child_pipeline) -``` +You can [pass variables to a downstream pipeline](multi_project_pipelines.md#passing-variables-to-a-downstream-pipeline). diff --git a/doc/ci/pipelines/img/ci_efficiency_pipeline_dag_critical_path.png b/doc/ci/pipelines/img/ci_efficiency_pipeline_dag_critical_path.png index 1715e8224ab..421fddaf38d 100644 Binary files a/doc/ci/pipelines/img/ci_efficiency_pipeline_dag_critical_path.png and b/doc/ci/pipelines/img/ci_efficiency_pipeline_dag_critical_path.png differ diff --git a/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png b/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png index 0956e76804e..59276bda727 100644 Binary files a/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png and b/doc/ci/pipelines/img/ci_efficiency_pipeline_health_grafana_dashboard.png differ diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 1b9048089bd..f7e3698b6d4 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -10,7 +10,7 @@ type: reference > Introduced in GitLab 8.8. -NOTE: **Tip:** +TIP: **Tip:** Watch the ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) webcast to see a comprehensive demo of a GitLab CI/CD pipeline. @@ -101,8 +101,8 @@ you can filter the pipeline list by: - Trigger author - Branch name -- Status ([since GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) -- Tag ([since GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) +- Status ([GitLab 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) +- Tag ([GitLab 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) ### Run a pipeline manually @@ -114,7 +114,7 @@ operation of the pipeline. To execute a pipeline manually: 1. Navigate to your project's **CI/CD > Pipelines**. -1. Click on the **Run Pipeline** button. +1. Select the **Run Pipeline** button. 1. On the **Run Pipeline** page: 1. Select the branch to run the pipeline for in the **Create for** field. 1. Enter any [environment variables](../variables/README.md) required for the pipeline run. @@ -461,6 +461,28 @@ this line should be hidden when collapsed section_end:1560896353:my_first_section\r\e[0K ``` +#### Pre-collapse sections + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198413) in GitLab 13.5. + +You can make the job log automatically collapse collapsible sections by adding the `collapsed` option to the section start. +Add `[collapsed=true]` after the section name and before the `\r`. The section end marker +remains unchanged: + +- Section start marker with `[collapsed=true]`: `section_start:UNIX_TIMESTAMP:SECTION_NAME[collapsed=true]\r\e[0K` + `TEXT_OF_SECTION_HEADER` +- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + +Add the updated section start text to the CI configuration. For example, +using `echo`: + +```yaml +job1: + script: + - echo -e "section_start:`date +%s`:my_first_section[collapsed=true]\r\e[0KHeader of the 1st collapsible section" + - echo 'this line should be hidden automatically after loading the job log' + - echo -e "section_end:`date +%s`:my_first_section\r\e[0K" +``` + ## Visualize pipelines > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5742) in GitLab 8.11. @@ -473,7 +495,6 @@ and their statuses. Pipeline graphs can be displayed in two different ways, depending on the page you access the graph from. -NOTE: **Note:** GitLab capitalizes the stages' names in the pipeline graphs. ### Regular pipeline graphs diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index 750a76bfaa0..d904452a011 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -37,8 +37,8 @@ pdf: expire_in: 1 week ``` -A job named `pdf` calls the `xelatex` command in order to build a PDF file from -the latex source file `mycv.tex`. We then define the `artifacts` paths which in +A job named `pdf` calls the `xelatex` command to build a PDF file from the +latex source file `mycv.tex`. We then define the `artifacts` paths which in turn are defined with the `paths` keyword. All paths to files and directories are relative to the repository that was cloned during the build. @@ -61,12 +61,10 @@ The `artifacts:reports` keyword is used for collecting test reports, code qualit reports, and security reports from jobs. It also exposes these reports in GitLab's UI (merge requests, pipeline views, and security dashboards). -NOTE: **Note:** The test reports are collected regardless of the job results (success or failure). You can use [`artifacts:expire_in`](../yaml/README.md#artifactsexpire_in) to set up an expiration date for their artifacts. -NOTE: **Note:** If you also want the ability to browse the report output files, include the [`artifacts:paths`](../yaml/README.md#artifactspaths) keyword. @@ -96,7 +94,6 @@ rspec: The collected Unit test reports upload to GitLab as an artifact and display in merge requests. -NOTE: **Note:** If the JUnit tool you use exports to multiple XML files, specify multiple test report paths within a single job to concatenate them into a single file. Use a filename pattern (`junit: rspec-*.xml`), @@ -343,6 +340,11 @@ The latest artifacts are created by jobs in the **most recent** successful pipel for the specific ref. If you run two types of pipelines for the same ref, timing determines the latest artifact. For example, if a merge request creates a branch pipeline at the same time as a scheduled pipeline, the pipeline that completed most recently creates the latest artifact. +In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201784) and later, artifacts +for [parent and child pipelines](../parent_child_pipelines.md) are searched in hierarchical +order from parent to child. For example, if both parent and child pipelines have a +job with the same name, the artifact from the parent pipeline is returned. + Artifacts for other pipelines can be accessed with direct access to them. The structure of the URL to download the whole artifacts archive is the following: @@ -429,7 +431,20 @@ To erase a job: ## Retrieve artifacts of private projects when using GitLab CI -In order to retrieve a job artifact of a different project, you might need to use a private token in order to [authenticate and download](../../api/job_artifacts.md#get-job-artifacts) the artifacts. +To retrieve a job artifact from a different project, you might need to use a +private token to [authenticate and download](../../api/job_artifacts.md#get-job-artifacts) +the artifact. + +## Troubleshooting + +### Error message `No files to upload` + +This is often preceded by other errors or warnings that specify the filename and why it wasn't +generated in the first place. Please check the entire job log for such messages. + +If you find no helpful messages, please retry the failed job after activating +[CI debug logging](../variables/README.md#debug-logging). +This provides useful information to investigate further. - + - The administrator can also configure a maximum number of shared runner [pipeline minutes for each group](../../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota). @@ -123,21 +118,20 @@ To enable shared runners: #### Disable shared runners -You can disable shared runners for individual projects. -You must have Owner permissions for the project. +You can disable shared runners for individual projects or for groups. +You must have Owner permissions for the project or group. To disable shared runners for a project: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. 1. In the **Shared runners** area, click **Disable shared runners**. - + click **Allow projects and subgroups to override the group setting**. ### Group runners diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index 6d561fe00a3..fb1183cd68b 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -17,23 +17,36 @@ Unlike CI variables, which are always presented to a job, secrets must be explic required by a job. Read [GitLab CI/CD pipeline configuration reference](../yaml/README.md#secrets) for more information about the syntax. -GitLab has selected [Vault by Hashicorp](https://www.vaultproject.io) as the +GitLab has selected [Vault by HashiCorp](https://www.vaultproject.io) as the first supported provider, and [KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) as the first supported secrets engine. GitLab authenticates using Vault's -[JWT Auth method](https://www.vaultproject.io/docs/auth/jwt#jwt-authentication), using +[JSON Web Token (JWT) authentication method](https://www.vaultproject.io/docs/auth/jwt#jwt-authentication), using the [JSON Web Token](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) (`CI_JOB_JWT`) introduced in GitLab 12.10. You must [configure your Vault server](#configure-your-vault-server) before you can use [use Vault secrets in a CI job](#use-vault-secrets-in-a-ci-job). +The flow for using GitLab with HashiCorp Vault +is summarized by this diagram: + +![Flow between GitLab and HashiCorp](../img/gitlab_vault_workflow_v13_4.png "How GitLab CI_JOB_JWT works with HashiCorp Vault") + +1. Configure your vault and secrets. +1. Generate your JWT and provide it to your CI job. +1. Runner contacts HashiCorp Vault and authenticates using the JWT. +1. HashiCorp Vault verifies the JWT. +1. HashiCorp Vault checks the bounded claims and attaches policies. +1. HashiCorp Vault returns the token. +1. Runner reads secrets from the HashiCorp Vault. + NOTE: **Note:** -Read the [Authenticating and Reading Secrets With Hashicorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) -tutorial for a version of this feature that is available to all +Read the [Authenticating and Reading Secrets With HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) +tutorial for a version of this feature. It's available to all subscription levels, supports writing secrets to and deleting secrets from Vault, -and multiple secrets engines. +and supports multiple secrets engines. ## Configure your Vault server @@ -90,7 +103,7 @@ the secrets stored in Vault by defining them with the `vault` keyword: ```yaml secrets: DATABASE_PASSWORD: - vault: production/db/password@ops # translates to secret `ops/data/production/db`, field `password` + vault: production/db/password@ops # translates to secret `ops/data/production/db`, field `password` ``` In this example: @@ -149,7 +162,7 @@ generated by this GitLab instance may be allowed to authenticate using this role For a full list of `CI_JOB_JWT` claims, read the [How it works](../examples/authenticating-with-hashicorp-vault/index.md#how-it-works) section of the -[Authenticating and Reading Secrets With Hashicorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) tutorial. +[Authenticating and Reading Secrets With HashiCorp Vault](../examples/authenticating-with-hashicorp-vault/index.md) tutorial. You can also specify some attributes for the resulting Vault tokens, such as time-to-live, IP address range, and number of uses. The full list of options is available in diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index aadbce5a50a..96552ab1245 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -13,7 +13,7 @@ do this with the Docker and Shell executors of GitLab Runner. ## Use PostgreSQL with the Docker executor -If you are using [GitLab Runner](../runners/README.md) with the Docker executor +If you're using [GitLab Runner](../runners/README.md) with the Docker executor, you basically have everything set up already. First, in your `.gitlab-ci.yml` add: @@ -29,12 +29,11 @@ variables: POSTGRES_HOST_AUTH_METHOD: trust ``` -NOTE: **Note:** -The `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD` -variables can't be set in the GitLab UI. To set them, assign them to a variable -[in the UI](../variables/README.md#create-a-custom-variable-in-the-ui), and then assign that -variable to the `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD` -variables in your `.gitlab-ci.yml`. +To set values for the `POSTGRES_DB`, `POSTGRES_USER`, +`POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD`, +[assign them to a variable in the user interface](../variables/README.md#create-a-custom-variable-in-the-ui), +then assign that variable to the corresponding variable in your +`.gitlab-ci.yml` file. And then configure your application to use the database, for example: @@ -45,14 +44,14 @@ Password: '' Database: nice_marmot ``` -If you are wondering why we used `postgres` for the `Host`, read more at +If you're wondering why we used `postgres` for the `Host`, read more at [How services are linked to the job](../docker/using_docker_images.md#how-services-are-linked-to-the-job). You can also use any other Docker image available on [Docker Hub](https://hub.docker.com/_/postgres). -For example, to use PostgreSQL 9.3 the service becomes `postgres:9.3`. +For example, to use PostgreSQL 9.3, the service becomes `postgres:9.3`. -The `postgres` image can accept some environment variables. For more details -check the documentation on [Docker Hub](https://hub.docker.com/_/postgres). +The `postgres` image can accept some environment variables. For more details, +see the documentation on [Docker Hub](https://hub.docker.com/_/postgres). ## Use PostgreSQL with the Shell executor @@ -65,7 +64,7 @@ First install the PostgreSQL server: sudo apt-get install -y postgresql postgresql-client libpq-dev ``` -The next step is to create a user, so login to PostgreSQL: +The next step is to create a user, so sign in to PostgreSQL: ```shell sudo -u postgres psql -d template1 @@ -74,24 +73,26 @@ sudo -u postgres psql -d template1 Then create a user (in our case `runner`) which will be used by your application. Change `$password` in the command below to a real strong password. -*__Note:__ Do not type `template1=#`, this is part of the PostgreSQL prompt.* +NOTE: **Note:** +Be sure to not enter `template1=#` in the following commands, as that's part of +the PostgreSQL prompt. ```shell template1=# CREATE USER runner WITH PASSWORD '$password' CREATEDB; ``` -*__Note:__ Notice that we created the user with the privilege to be able to -create databases (`CREATEDB`). In the following steps we will create a database -explicitly for that user but having that privilege can be useful if in your -testing framework you have tools that drop and create databases.* +The created user has the privilege to create databases (`CREATEDB`). The +following steps describe how to create a database explicitly for that user, but +having that privilege can be useful if in your testing framework you have tools +that drop and create databases. -Create the database and grant all privileges on it for the user `runner`: +Create the database and grant all privileges to it for the user `runner`: ```shell template1=# CREATE DATABASE nice_marmot OWNER runner; ``` -If all went well you can now quit the database session: +If all went well, you can now quit the database session: ```shell template1=# \q @@ -104,8 +105,8 @@ check that everything is in place. psql -U runner -h localhost -d nice_marmot -W ``` -*__Note:__ We are explicitly telling `psql` to connect to localhost in order -to use the md5 authentication. If you omit this step you will be denied access.* +This command explicitly directs `psql` to connect to localhost to use the md5 +authentication. If you omit this step, you'll be denied access. Finally, configure your application to use the database, for example: @@ -122,5 +123,5 @@ We have set up an [Example PostgreSQL Project](https://gitlab.com/gitlab-example convenience that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). -Want to hack on it? Simply fork it, commit and push your changes. Within a few +Want to hack on it? Fork it, commit, and push your changes. Within a few moments the changes will be picked by a public runner and the job will begin. diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index d8280316f19..12478000a0a 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -36,7 +36,6 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/) `~/.ssh/authorized_keys`) or add it as a [deploy key](../../ssh/README.md#deploy-keys) if you are accessing a private GitLab repository. -NOTE: **Note:** The private key will not be displayed in the job log, unless you enable [debug logging](../variables/README.md#debug-logging). You might also want to check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines). @@ -94,7 +93,6 @@ to access it. This is where an SSH key pair comes in handy. # - git config --global user.name "User name" ``` - NOTE: **Note:** The [`before_script`](../yaml/README.md#before_script-and-after_script) can be set globally or per-job. @@ -134,7 +132,8 @@ on, and use that key for all projects that are run on this machine. If you are accessing a private GitLab repository you need to add it as a [deploy key](../../ssh/README.md#deploy-keys). -Once done, try to log in to the remote server in order to accept the fingerprint: +After generating the key, try to sign in to the remote server to accept the +fingerprint: ```shell ssh example.com @@ -163,7 +162,6 @@ ssh-keyscan 1.2.3.4 Create a new [variable](../variables/README.md#gitlab-cicd-environment-variables) with `SSH_KNOWN_HOSTS` as "Key", and as a "Value" add the output of `ssh-keyscan`. -NOTE: **Note:** If you need to connect to multiple servers, all the server host keys need to be collected in the **Value** of the variable, one key per line. diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 2b006b8779b..bcd19f0de6f 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -95,9 +95,9 @@ Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts ## Adding a new trigger -You can add a new trigger by going to your project's -**Settings ➔ CI/CD** under **Triggers**. The **Add trigger** button will -create a new token which you can then use to trigger a rerun of this +Go to your +**Settings ➔ CI/CD** under **Triggers** to add a new trigger. The **Add trigger** button creates +a new token which you can then use to trigger a rerun of this particular project's pipeline. Every new trigger you create, gets assigned a different token which you can @@ -121,7 +121,7 @@ POST /projects/:id/trigger/pipeline ``` The required parameters are the [trigger's `token`](#authentication-tokens) -and the Git `ref` on which the trigger will be performed. Valid refs are +and the Git `ref` on which the trigger is performed. Valid refs are branches or tags. The `:id` of a project can be found by [querying the API](../../api/projects.md) or by visiting the **CI/CD** settings page which provides self-explanatory examples. @@ -146,7 +146,7 @@ curl --request POST \ https://gitlab.example.com/api/v4/projects/9/trigger/pipeline ``` -In this case, the project with ID `9` will get rebuilt on `master` branch. +In this case, the project with ID `9` gets rebuilt on `master` branch. Alternatively, you can pass the `token` and `ref` arguments in the query string: @@ -169,9 +169,9 @@ build_docs: - tags ``` -This means that whenever a new tag is pushed on project A, the job will run and the -`build_docs` job will be executed, triggering a rebuild of project B. The -`stage: deploy` ensures that this job will run only after all jobs with +This means that whenever a new tag is pushed on project A, the job runs and the +`build_docs` job is executed, triggering a rebuild of project B. The +`stage: deploy` ensures that this job runs only after all jobs with `stage: test` complete successfully. ## Triggering a pipeline from a webhook @@ -183,14 +183,14 @@ webhook URL for Push and Tag events (change the project ID, ref and token): https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN ``` -`ref` should be passed as part of the URL in order to take precedence over -`ref` from the webhook body that designates the branch ref that fired the -trigger in the source repository. `ref` should be URL-encoded if it contains slashes. +You should pass `ref` as part of the URL, to take precedence over `ref` from +the webhook body that designates the branch ref that fired the trigger in the +source repository. Be sure to URL-encode `ref` if it contains slashes. ## Making use of trigger variables You can pass any number of arbitrary variables in the trigger API call and they -will be available in GitLab CI/CD so that they can be used in your `.gitlab-ci.yml` +are available in GitLab CI/CD so that they can be used in your `.gitlab-ci.yml` file. The parameter is of the form: ```plaintext @@ -237,7 +237,7 @@ upload_package: ``` You can then trigger a rebuild while you pass the `UPLOAD_TO_S3` variable -and the script of the `upload_package` job will run: +and the script of the `upload_package` job is run: ```shell curl --request POST \ @@ -252,10 +252,6 @@ of all types of variables. ## Using cron to trigger nightly pipelines -NOTE: **Note:** -The following behavior can also be achieved through GitLab's UI with -[pipeline schedules](../pipelines/schedules.md). - Whether you craft a script or just run cURL directly, you can trigger jobs in conjunction with cron. The example below triggers a job on the `master` branch of project with ID `9` every night at `00:30`: @@ -264,9 +260,12 @@ branch of project with ID `9` every night at `00:30`: 30 0 * * * curl --request POST --form token=TOKEN --form ref=master https://gitlab.example.com/api/v4/projects/9/trigger/pipeline ``` +This behavior can also be achieved through GitLab's UI with +[pipeline schedules](../pipelines/schedules.md). + ## Legacy triggers -Old triggers, created before GitLab 9.0 will be marked as legacy. +Old triggers, created before GitLab 9.0 are marked as legacy. Triggers with the legacy label do not have an associated user and only have access to the current project. They are considered deprecated and will be diff --git a/doc/ci/unit_test_reports.md b/doc/ci/unit_test_reports.md index 5a59a175a89..b9c1809bf0d 100644 --- a/doc/ci/unit_test_reports.md +++ b/doc/ci/unit_test_reports.md @@ -10,8 +10,6 @@ type: reference > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/45318) in GitLab 11.2. Requires GitLab Runner 11.2 and above. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39737) from JUnit test reports to Unit test reports in GitLab 13.4. -## Overview - It is very common that a [CI/CD pipeline](pipelines/index.md) contains a test job that will verify your code. If the tests fail, the pipeline fails and users get notified. The person that @@ -20,12 +18,12 @@ tests failed so that they can fix them. You can configure your job to use Unit test reports, and GitLab will display a report on the merge request so that it's easier and faster to identify the -failure without having to check the entire log. Unit test reports currently +failure without having to check the entire log. Unit test reports currently only support test reports in the JUnit report format. -If you don't use Merge Requests but still want to see the unit test report -output without searching through job logs, the full -[Unit test reports](#viewing-unit-test-reports-on-gitlab) are available +If you don't use Merge Requests but still want to see the unit test report +output without searching through job logs, the full +[Unit test reports](#viewing-unit-test-reports-on-gitlab) are available in the pipeline detail view. Consider the following workflow: @@ -84,7 +82,6 @@ To make the Unit test report output files browsable, include them with the To upload the report even if the job fails (for example if the tests do not pass), use the [`artifacts:when:always`](yaml/README.md#artifactswhen) keyword. -NOTE: **Note:** You cannot have multiple tests with the same name and class in your JUnit report format XML file. ### Ruby example @@ -146,8 +143,8 @@ java: junit: build/test-results/test/**/TEST-*.xml ``` -NOTE: **Note:** -Support for `**` was added in [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620). +In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) +and later, you can use `**`. #### Maven diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 1a982fa4e19..9c8fb994bf7 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -12,10 +12,11 @@ affect the way running processes behave on an operating system. Environment variables are part of the environment in which a process runs. -For example, a running process can query the value of the -`TEMP` environment variable to discover a suitable location -to store temporary files, or to define a `URL` for a database -that can be reused in different scripts. +For example, a running process could: + +- Use the value of a `TEMP` environment variable to know the correct location + to store temporary files. +- Use a `DATABASE_URL` variable for the URL to a database that can be reused in different scripts. Variables are useful for customizing your jobs in GitLab CI/CD. When you use variables, you don't have to hard-code values. @@ -62,22 +63,6 @@ job `test_variable`, which is `test`: ![Output `$CI_JOB_STAGE`](img/ci_job_stage_output_example.png) -As another example, let's say you're using your own GitLab -instance and you want to know what domain your GitLab Pages are -served under. You can call it by using the predefined -variable `$CI_PAGES_DOMAIN` in your script: - -```yaml -pages: - script: - - ... - - echo $CI_PAGES_DOMAIN -``` - -For GitLab.com users, the output is `gitlab.io`. For your -private instance, the output is whatever your sysadmin has -defined. - ## Custom environment variables When you need a specific custom environment variable, you can @@ -103,8 +88,8 @@ variables: You can then call its value in your script: ```yaml - script: - - echo "$TEST" +script: + - echo "$TEST" ``` For more details, see [`.gitlab-ci.yml` defined variables](#gitlab-ciyml-defined-variables). @@ -181,8 +166,8 @@ You can use tools like [the AWS CLI](https://docs.aws.amazon.com/cli/latest/user and [`kubectl`](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable) to customize your configuration by using **File** type variables. -In the past, a common pattern was to read the value of a CI variable, save it in a file, and then -use the newly created file in your script: +Previously, a common pattern was to read the value of a CI variable, save it in a file, and then +use that file in your script: ```shell # Read certificate stored in $KUBE_CA_PEM variable and save it in a new file @@ -258,7 +243,7 @@ Some variables are listed in the UI so you can choose them more quickly. | `AWS_DEFAULT_REGION` | Any | 12.10 | | `AWS_SECRET_ACCESS_KEY` | Any | 12.10 | -NOTE: **Note:** +CAUTION: **Caution:** When you store credentials, there are security implications. If you are using AWS keys, for example, follow their [best practices](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html). @@ -288,11 +273,11 @@ job_name: ### PowerShell -To access environment variables in a **Windows PowerShell** environment, prefix -the variable name with (`$env:`). For environment variables set by GitLab CI, including those set by [`variables`](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/ci/yaml/README.md#variables) -parameter, they can also be accessed by prefixing the variable name with (`$`) -as of [GitLab Runner 1.0.0](https://gitlab.com/gitlab-org/gitlab-runner/-/commit/abc44bb158008cd3a49c0d8173717c38dadb29ae#47afd7e8f12afdb8f0246262488f24e6dd071a22). -System set environment variables however must be accessed using (`$env:`). +To access variables in a **Windows PowerShell** environment, including system set +environment variables, prefix the variable name with (`$env:`). Environment variables +set by GitLab CI can also be accessed by prefixing the variable name with (`$`) with +[GitLab Runner 1.0.0](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/68) +and later. ```yaml job_name: @@ -386,9 +371,6 @@ export GITLAB_USER_ID="42" ## `.gitlab-ci.yml` defined variables -NOTE: **Note:** -This feature requires GitLab Runner 0.5.0 or higher and GitLab 7.14 or higher. - You can add variables that are set in the build environment to `.gitlab-ci.yml`. These variables are saved in the repository, and they are meant to store non-sensitive project configuration, like `RAILS_ENV` or @@ -428,10 +410,12 @@ script: > Introduced in GitLab 9.4. -You can define per-project or per-group variables -that are set in the pipeline environment. Group-level variables are stored out of -the repository (not in `.gitlab-ci.yml`) and are securely passed to GitLab Runner, -which makes them available during a pipeline run. For Premium users who do **not** use an external key store or who use GitLab's [integration with HashiCorp Vault](../secrets/index.md), we recommend using group environment variables to store secrets like passwords, SSH keys, and credentials. +You can define per-project or per-group variables that are set in the pipeline environment. Group-level variables are stored out of the repository (not in `.gitlab-ci.yml`). They are securely passed to GitLab Runner, which makes them available during a pipeline run. + +We recommend using group environment variables to store secrets (like passwords, SSH keys, and credentials) for Premium users who: + +- Do **not** use an external key store. +- Use GitLab's [integration with HashiCorp Vault](../secrets/index.md). Group-level variables can be added by: @@ -452,8 +436,7 @@ Once you set them, they are available for all subsequent pipelines. Any group-le Instance variables are useful for no longer needing to manually enter the same credentials repeatedly for all your projects. Instance-level variables are available to all projects and groups on the instance. -NOTE: **Note:** -The maximum number of instance-level variables is [planned to be 25](https://gitlab.com/gitlab-org/gitlab/-/issues/216097). +In GitLab 13.1 and later, the [maximum number of instance-level variables is 25](https://gitlab.com/gitlab-org/gitlab/-/issues/216097). You can define instance-level variables via the UI or [API](../../api/instance_level_ci_variables.md). @@ -463,7 +446,7 @@ To add an instance-level variable: 1. Click the **Add variable** button, and fill in the details: - **Key**: Must be one line, using only letters, numbers, or `_` (underscore), with no spaces. - - **Value**: [Since GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), 10,000 characters allowed. This is also bounded by the limits of the selected runner operating system. In GitLab 13.0 to 13.2, 700 characters allowed. + - **Value**: [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/220028), 10,000 characters allowed. This is also bounded by the limits of the selected runner operating system. In GitLab 13.0 to 13.2, 700 characters allowed. - **Type**: `File` or `Variable`. - **Protect variable** (Optional): If selected, the variable is only available in pipelines that run on protected branches or tags. - **Mask variable** (Optional): If selected, the variable's **Value** is not shown in job logs. The variable is not saved if the value does not meet the [masking requirements](#masked-variable-requirements). @@ -566,12 +549,11 @@ variables take precedence over those defined in `.gitlab-ci.yml`. Variable names are limited by the underlying shell used to execute scripts (see [available shells](https://docs.gitlab.com/runner/shells/index.html). Each shell has its own unique set of reserved variable names. -You also want to keep in mind the [scope of environment variables](where_variables_can_be_used.md) to ensure a variable is defined in the scope -in which you wish to use it. +Keep in mind the [scope of environment variables](where_variables_can_be_used.md) to ensure a variable is defined in the scope in which you wish to use it. ## Where variables can be used -Click [here](where_variables_can_be_used.md) for a section that describes where and how the different types of variables can be used. +[This section](where_variables_can_be_used.md) describes where and how the different types of variables can be used. ## Advanced use @@ -609,8 +591,8 @@ then available as environment variables on the running application container. CAUTION: **Caution:** -Variables with multi-line values are not currently supported due to -limitations with the current Auto DevOps scripting environment. +Variables with multi-line values are not supported due to +limitations with the Auto DevOps scripting environment. ### Override a variable by manually running a pipeline @@ -701,9 +683,10 @@ Examples: - `$VARIABLE == ""` - `$VARIABLE != ""` (introduced in GitLab 11.11) -If you want to check whether a variable is defined, but is empty, you can -simply compare it against an empty string, like `$VAR == ''` or non-empty -string `$VARIABLE != ""`. +To check if a variable is defined but empty, compare it to: + +- An empty string: `$VARIABLE == ''` +- A non-empty string: `$VARIABLE != ""` #### Comparing two variables @@ -719,9 +702,8 @@ of these variables. Example: `$STAGING` -If you only want to create a job when there is some variable present, -which means that it is defined and non-empty, you can simply use -variable name as an expression, like `$STAGING`. If `$STAGING` variable +To create a job when there is some variable present, meaning it is defined and non-empty, +use the variable name as an expression, like `$STAGING`. If the `$STAGING` variable is defined, and is non empty, expression evaluates to `true`. `$STAGING` value needs to be a string, with length higher than zero. Variable that contains only whitespace characters is not an empty variable. @@ -785,7 +767,7 @@ Examples: ##### Enable or disable parenthesis support for variables **(CORE ONLY)** -The feature is currently deployed behind a feature flag that is **enabled by default**. +The feature is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can opt to disable it for your instance. @@ -820,8 +802,7 @@ NOTE: **Note:** The available regular expression syntax is limited. See [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/35438) for more details. -If needed, you can use a test pipeline to determine whether a regular expression will -work in a variable. The example below tests the `^mast.*` regular expression directly, +If needed, you can use a test pipeline to determine whether a regular expression works in a variable. The example below tests the `^mast.*` regular expression directly, as well as from within a variable: ```yaml @@ -856,9 +837,7 @@ from being leaked into the log unless your script writes them to the screen. If a job isn't working as expected, this can make the problem difficult to investigate; in these cases, you can enable debug tracing in `.gitlab-ci.yml`. -Available on GitLab Runner v1.7+, this feature enables the shell's execution -log, resulting in a verbose job log listing all commands that were run, -variables that were set, and so on. +Available on GitLab Runner v1.7+, this feature enables the shell's execution log. This results in a verbose job log listing all commands that were run, variables that were set, and so on. Before enabling this, you should ensure jobs are visible to [team members only](../../user/permissions.md#project-features). You should diff --git a/doc/ci/variables/deprecated_variables.md b/doc/ci/variables/deprecated_variables.md index 94ec8439605..71e2b5b2e44 100644 --- a/doc/ci/variables/deprecated_variables.md +++ b/doc/ci/variables/deprecated_variables.md @@ -16,7 +16,6 @@ To follow conventions of naming across GitLab, and to further move away from the `build` term and toward `job`, some [CI/CD environment variables](README.md#predefined-environment-variables) were renamed for GitLab 9.0 release. -NOTE: **Note:** Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are strongly advised to use the new variables as we will remove the old ones in future GitLab releases.** diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 915041b71a6..08aaacd2620 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -69,7 +69,8 @@ Kubernetes-specific environment variables are detailed in the | `CI_JOB_MANUAL` | 8.12 | all | The flag to indicate that job was manually started | | `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job as defined in `.gitlab-ci.yml` | | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the stage as defined in `.gitlab-ci.yml` | -| `CI_JOB_TOKEN` | 9.0 | 1.2 | Token used for authenticating with the [GitLab Container Registry](../../user/packages/container_registry/index.md), downloading [dependent repositories](../../user/project/new_ci_build_permissions_model.md#dependent-repositories), and accessing [GitLab-managed Terraform state](../../user/infrastructure/index.md#gitlab-managed-terraform-state). | +| `CI_JOB_STATUS` | all | 13.5 | The state of the job as each runner stage is executed. Use with [`after_script`](../yaml/README.md#before_script-and-after_script) where `CI_JOB_STATUS` can be either: `success`, `failed` or `canceled`. | +| `CI_JOB_TOKEN` | 9.0 | 1.2 | Token used for authenticating with [a few API endpoints](../../api/README.md#gitlab-ci-job-token) and downloading [dependent repositories](../../user/project/new_ci_build_permissions_model.md#dependent-repositories). The token is valid as long as the job is running. | | `CI_JOB_JWT` | 12.10 | all | RS256 JSON web token that can be used for authenticating with third party systems that support JWT authentication, for example [HashiCorp's Vault](../secrets/index.md). | | `CI_JOB_URL` | 11.1 | 0.5 | Job details URL | | `CI_KUBERNETES_ACTIVE` | 13.0 | all | Included with the value `true` only if the pipeline has a Kubernetes cluster available for deployments. Not included if no cluster is available. Can be used as an alternative to [`only:kubernetes`/`except:kubernetes`](../yaml/README.md#onlykubernetesexceptkubernetes) with [`rules:if`](../yaml/README.md#rulesif) | @@ -104,7 +105,7 @@ Kubernetes-specific environment variables are detailed in the | `CI_PROJECT_ID` | all | all | The unique ID of the current project that GitLab CI/CD uses internally | | `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project that is currently being built. For example, if the project URL is `gitlab.example.com/group-name/project-1`, the `CI_PROJECT_NAME` would be `project-1`. | | `CI_PROJECT_NAMESPACE` | 8.10 | 0.5 | The project namespace (username or group name) that is currently being built | -| `CI_PROJECT_ROOT_NAMESPACE` | 13.2 | 0.5 | The **root** project namespace (username or group name) that is currently being built. For example, if `CI_PROJECT_NAME` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` would be `root-group`. | +| `CI_PROJECT_ROOT_NAMESPACE` | 13.2 | 0.5 | The **root** project namespace (username or group name) that is currently being built. For example, if `CI_PROJECT_NAMESPACE` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` would be `root-group`. | | `CI_PROJECT_PATH` | 8.10 | 0.5 | The namespace with project name | | `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` lowercased and with everything except `0-9` and `a-z` replaced with `-`. Use in URLs and domain names. | | `CI_PROJECT_REPOSITORY_LANGUAGES` | 12.3 | all | Comma-separated, lowercased list of the languages used in the repository (e.g. `ruby,javascript,html,css`) | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 330b960ca9a..b4236ca34c2 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -38,15 +38,14 @@ There are two places defined variables can be used. On the: ### `config.toml` file -NOTE: **Note:** -You can read more about `config.toml` in the [GitLab Runner docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). - | Definition | Can be expanded? | Description | |:-------------------------------------|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------| | `runners.environment` | yes | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | | `runners.kubernetes.pod_labels` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | | `runners.kubernetes.pod_annotations` | yes | The Variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | +You can read more about `config.toml` in the [GitLab Runner docs](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + ## Expansion mechanisms There are three expansion mechanisms: @@ -104,10 +103,6 @@ These restrictions are because `after_script` scripts are executed in a ## Persisted variables -NOTE: **Note:** -Some of the persisted variables contain tokens and cannot be used by some definitions -due to security reasons. - The following variables are known as "persisted": - `CI_PIPELINE_ID` @@ -130,6 +125,9 @@ They are: - For definitions where the ["Expansion place"](#gitlab-ciyml-file) is GitLab. - In the `only` and `except` [variables expressions](README.md#environment-variables-expressions). +Some of the persisted variables contain tokens and cannot be used by some definitions +due to security reasons. + ## Variables with an environment scope Variables defined with an environment scope are supported. Given that diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 40df9c7c986..2e4ab68a0e8 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -33,11 +33,8 @@ We have complete examples of configuring pipelines: > -  Learn how [Verizon reduced rebuilds](https://about.gitlab.com/blog/2019/02/14/verizon-customer-story/) > from 30 days to under 8 hours with GitLab. -NOTE: **Note:** If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository), -you may need to enable pipeline triggering. Go to your project's - -**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. +you may need to enable pipeline triggering. Go to your project's **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. ## Introduction @@ -107,12 +104,12 @@ The following table lists available parameters for jobs: | [`script`](#script) | Shell script that is executed by a runner. | | [`after_script`](#before_script-and-after_script) | Override a set of commands that are executed after job. | | [`allow_failure`](#allow_failure) | Allow job to fail. Failed job does not contribute to commit status. | -| [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:exclude`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, `artifacts:reports`. | +| [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:exclude`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, and `artifacts:reports`. | | [`before_script`](#before_script-and-after_script) | Override a set of commands that are executed before job. | -| [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, and `cache:policy`. | +| [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, `cache:when`, and `cache:policy`. | | [`coverage`](#coverage) | Code coverage settings for a given job. | | [`dependencies`](#dependencies) | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. | -| [`environment`](#environment) | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, `environment:auto_stop_in` and `environment:action`. | +| [`environment`](#environment) | Name of an environment to which the job deploys. Also available: `environment:name`, `environment:url`, `environment:on_stop`, `environment:auto_stop_in`, and `environment:action`. | | [`except`](#onlyexcept-basic) | Limit when jobs are not created. Also available: [`except:refs`, `except:kubernetes`, `except:variables`, and `except:changes`](#onlyexcept-advanced). | | [`extends`](#extends) | Configuration entries that this job inherits from. | | [`image`](#image) | Use Docker images. Also available: `image:name` and `image:entrypoint`. | @@ -184,7 +181,7 @@ To enable or disable the inheritance of all `variables:` or `default:` parameter - `variables: true` or `variables: false` To inherit only a subset of `default:` parameters or `variables:`, specify what -you wish to inherit, and any not listed will **not** be inherited. Use +you wish to inherit. Anything not listed is **not** inherited. Use one of the following formats: ```yaml @@ -208,16 +205,16 @@ inherit: In the example below: - `rubocop`: - - **will** inherit: Nothing. + - inherits: Nothing. - `rspec`: - - **will** inherit: the default `image` and the `WEBHOOK_URL` variable. - - will **not** inherit: the default `before_script` and the `DOMAIN` variable. + - inherits: the default `image` and the `WEBHOOK_URL` variable. + - does **not** inherit: the default `before_script` and the `DOMAIN` variable. - `capybara`: - - **will** inherit: the default `before_script` and `image`. - - will **not** inherit: the `DOMAIN` and `WEBHOOK_URL` variables. + - inherits: the default `before_script` and `image`. + - does **not** inherit: the `DOMAIN` and `WEBHOOK_URL` variables. - `karma`: - - **will** inherit: the default `image` and `before_script`, and the `DOMAIN` variable. - - will **not** inherit: `WEBHOOK_URL` variable. + - inherits: the default `image` and `before_script`, and the `DOMAIN` variable. + - does **not** inherit: `WEBHOOK_URL` variable. ```yaml default: @@ -347,23 +344,23 @@ workflow: This example never allows pipelines for schedules or `push` (branches and tags) pipelines, but does allow pipelines in **all** other cases, *including* merge request pipelines. -As with `rules` defined in jobs, be careful not to use a configuration that allows -merge request pipelines and branch pipelines to run at the same time, or you could -have [duplicate pipelines](#prevent-duplicate-pipelines). +Be careful not to use a configuration that might run +merge request pipelines and branch pipelines at the same time. As with `rules` defined in jobs, +it can cause [duplicate pipelines](#prevent-duplicate-pipelines). #### `workflow:rules` templates > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217732) in GitLab 13.0. -We provide pre-made templates for use with your pipelines that set up `workflow: rules` -for common scenarios. Usage of these will make things easier and prevent duplicate pipelines from running. +We provide templates that set up `workflow: rules` +for common scenarios. These templates help prevent duplicate pipelines. The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml) makes your pipelines run for branches and tags. -Branch pipeline status will be displayed within merge requests that use that branch -as a source, but this pipeline type does not support any features offered by -[Merge Request Pipelines](../merge_request_pipelines/) like +Branch pipeline status is displayed within merge requests that use the branch +as a source. However, this pipeline type does not support any features offered by +[Merge Request Pipelines](../merge_request_pipelines/), like [Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results) or [Merge Trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/). Use this template if you are intentionally avoiding those features. @@ -391,7 +388,7 @@ include: ### `include` > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. -> - Available for Starter, Premium and Ultimate since 10.6. +> - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4. Using the `include` keyword allows the inclusion of external YAML files. This helps @@ -402,6 +399,10 @@ configuration files. This helps avoid duplicated configuration, for example, glo `include` requires the external YAML file to have the extensions `.yml` or `.yaml`, otherwise the external file is not included. +Using [YAML anchors](#anchors) across different YAML files sourced by `include` is not +supported. You must only refer to anchors in the same file. Instead +of using YAML anchors, you can use the [`extends` keyword](#extends). + `include` supports the following inclusion methods: | Method | Description | @@ -413,7 +414,6 @@ otherwise the external file is not included. The `include` methods do not support [variable expansion](../variables/where_variables_can_be_used.md#variables-usage). -NOTE: **Note:** `.gitlab-ci.yml` configuration included by all methods is evaluated at pipeline creation. The configuration is a snapshot in time and persisted in the database. Any changes to referenced `.gitlab-ci.yml` configuration is not reflected in GitLab until the next pipeline is created. @@ -428,11 +428,6 @@ TIP: **Tip:** Use merging to customize and override included CI/CD configurations with local definitions. Local definitions in `.gitlab-ci.yml` override included definitions. -NOTE: **Note:** -Using [YAML anchors](#anchors) across different YAML files sourced by `include` is not -supported. You must only refer to anchors in the same file. Instead -of using YAML anchors, you can use the [`extends` keyword](#extends). - #### `include:local` `include:local` includes a file from the same repository as `.gitlab-ci.yml`. @@ -442,12 +437,11 @@ You can only use files that are tracked by Git on the same branch your configuration file is on. In other words, when using a `include:local`, make sure that both `.gitlab-ci.yml` and the local file are on the same branch. +Including local files through Git submodules paths is not supported. + All [nested includes](#nested-includes) are executed in the scope of the same project, so it's possible to use local, project, remote, or template includes. -NOTE: **Note:** -Including local files through Git submodules paths is not supported. - Example: ```yaml @@ -455,7 +449,6 @@ include: - local: '/templates/.gitlab-ci-template.yml' ``` -TIP: **Tip:** Local includes can be used as a replacement for symbolic links that are not followed. This can be defined as a short local include: @@ -495,8 +488,8 @@ include: file: '/templates/.gitlab-ci-template.yml' ``` -All [nested includes](#nested-includes) are executed in the scope of the target project, -so it's possible to use local (relative to target project), project, remote +All [nested includes](#nested-includes) are executed in the scope of the target project. +This means you can use local (relative to target project), project, remote, or template includes. #### `include:remote` @@ -548,7 +541,7 @@ Nested includes allow you to compose a set of includes. A total of 100 includes is allowed, but duplicate includes are considered a configuration error. -Since [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/28212), the time limit +In [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/28212) and later, the time limit for resolving all files is 30 seconds. #### Additional `includes` examples @@ -635,10 +628,9 @@ job: - bundle exec rspec ``` -NOTE: **Note:** Sometimes, `script` commands must be wrapped in single or double quotes. -For example, commands that contain a colon (`:`) must be wrapped in quotes so -that the YAML parser knows to interpret the whole thing as a string rather than +For example, commands that contain a colon (`:`) must be wrapped in quotes. +The YAML parser needs to interpret the text as a string rather than a "key: value" pair. Be careful when using special characters: `:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``. @@ -657,15 +649,18 @@ job: > Introduced in GitLab 8.7 and requires GitLab Runner v1.2. -`before_script` is used to define a command that should be run before each +`before_script` is used to define commands that should be run before each job, including deploy jobs, but after the restoration of any [artifacts](#artifacts). This must be an array. Scripts specified in `before_script` are concatenated with any scripts specified in the main [`script`](#script), and executed together in a single shell. -`after_script` is used to define the command that runs after each -job, including failed ones. This must be an array. +`after_script` is used to define commands that run after each +job, including failed jobs. This must be an array. If a job times out or is cancelled, +the `after_script` commands are not executed. Support for executing `after_script` +commands for timed-out or cancelled jobs +[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/15603). Scripts specified in `after_script` are executed in a new shell, separate from any `before_script` or `script` scripts. As a result, they: @@ -744,11 +739,11 @@ using [`|` (literal) and `>` (folded) YAML multi-line block scalar indicators](h CAUTION: **Warning:** If multiple commands are combined into one command string, only the last command's -failure or success is reported, -[incorrectly ignoring failures from earlier commands due to a bug](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25394). -If the success of the job depends on the success or failure of these commands, -you can run the commands as separate `script:` items, or add `exit 1` commands -as appropriate to the command string where needed. +failure or success is reported. +[Failures from earlier commands are ignored due to a bug](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25394). +To work around this, +run each command as a separate `script:` item, or add an `exit 1` command +to each command string. You can use the `|` (literal) YAML multiline block scalar indicator to write commands over multiple lines in the `script` section of a job description. @@ -808,7 +803,7 @@ Second command line. ``` When you omit the `>` or `|` block scalar indicators, GitLab forms the command -by concatenating non-empty lines, so make sure the lines can run when concatenated. +by concatenating non-empty lines. Make sure the lines can run when concatenated. Shell [here documents](https://en.wikipedia.org/wiki/Here_document) work with the `|` and `>` operators as well. The example below transliterates the lower case letters @@ -895,6 +890,8 @@ The following stages are available to every pipeline: User-defined stages are executed after `.pre` and before `.post`. +A pipeline is not created if all jobs are in `.pre` or `.post` stages. + The order of `.pre` and `.post` can't be changed, even if defined out of order in `.gitlab-ci.yml`. For example, the following are equivalent configuration: @@ -926,9 +923,6 @@ For example, the following are equivalent configuration: - b ``` -NOTE: **Note:** -A pipeline is not created if all jobs are in `.pre` or `.post` stages. - ### `extends` > Introduced in GitLab 11.3. @@ -961,7 +955,7 @@ GitLab performs a reverse deep merge based on the keys. GitLab: - Merges the `rspec` contents into `.tests` recursively. - Doesn't merge the values of the keys. -The result is this `rspec` job: +The result is this `rspec` job, where `script: rake test` is overwritten by `script: rake rspec`: ```yaml rspec: @@ -974,9 +968,6 @@ rspec: - $RSPEC ``` -NOTE: **Note:** -Note that `script: rake test` has been overwritten by `script: rake rspec`. - If you do want to include the `rake test`, see [`before_script` and `after_script`](#before_script-and-after_script). `.tests` in this example is a [hidden job](#hide-jobs), but it's @@ -1113,7 +1104,6 @@ is either included or excluded from the pipeline, depending on the configuration If included, the job also has [certain attributes](#rules-attributes) added to it. -CAUTION: **Caution:** `rules` replaces [`only/except`](#onlyexcept-basic) and can't be used in conjunction with it. If you attempt to use both keywords in the same job, the linter returns a `key may not be used with rules` error. @@ -1500,9 +1490,8 @@ job: - spec/**.rb ``` -NOTE: **Note:** -For performance reasons, using `exists` with patterns is limited to 10000 -checks. After the 10000th check, rules with patterned globs always match. +For performance reasons, using `exists` with patterns is limited to 10,000 +checks. After the 10,000th check, rules with patterned globs always match. #### `rules:allow_failure` @@ -1543,15 +1532,15 @@ docker build: script: docker build -t my-image:$CI_COMMIT_REF_SLUG . rules: - if: '$VAR == "string value"' - changes: # Will include the job and set to when:manual if any of the follow paths match a modified file. + changes: # Include the job and set to when:manual if any of the follow paths match a modified file. - Dockerfile - docker/scripts/* when: manual - # - when: never would be redundant here, this is implied any time rules are listed. + # - when: never would be redundant here, this is implied any time rules are listed. ``` -Keywords such as `branches` or `refs` that are currently available for -`only`/`except` are not yet available in `rules` as they are being individually +Keywords such as `branches` or `refs` that are available for +`only`/`except` are not available in `rules`. They are being individually considered for their usage and behavior in this context. Future keyword improvements are being discussed in our [epic for improving `rules`](https://gitlab.com/groups/gitlab-org/-/epics/2783), where anyone can add suggestions or requests. @@ -1567,10 +1556,9 @@ job1: if: ($CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE ``` -NOTE: **Note:** -In GitLab 13.2 and older, the order of operations when mixing `||` and `&&` in a single rule may not have executed -in the expected order. This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) -in GitLab 13.3. +CAUTION: **Caution:** +[Before GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/230938), +rules that use both `||` and `&&` may evaluate with an unexpected order of operations. ### `only`/`except` (basic) @@ -1611,8 +1599,8 @@ In addition, `only` and `except` allow the use of special keywords: | `triggers` | For pipelines created by using a [trigger token](../triggers/README.md#trigger-token). | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | -In the example below, `job` will run only for refs that start with `issue-`, -whereas all branches will be skipped: +In the example below, `job` runs only for refs that start with `issue-`, +whereas all branches are skipped: ```yaml job: @@ -1637,8 +1625,8 @@ job: - branches ``` -In this example, `job` will run only for refs that are tagged, or if a build is -explicitly requested via an API trigger or a [Pipeline Schedule](../pipelines/schedules.md): +In this example, `job` runs only for refs that are tagged, or if a build is +explicitly requested by an API trigger or a [Pipeline Schedule](../pipelines/schedules.md): ```yaml job: @@ -1684,19 +1672,19 @@ job: #### Regular expressions -Because `@` is used to denote the beginning of a ref's repository path, -matching a ref name containing the `@` character in a regular expression -requires the use of the hex character code match `\x40`. +The `@` symbol denotes the beginning of a ref's repository path. +To match a ref name that contains the `@` character in a regular expression, +you must use the hex character code match `\x40`. Only the tag or branch name can be matched by a regular expression. The repository path, if given, is always matched literally. -If a regular expression shall be used to match the tag or branch name, -the entire ref name part of the pattern has to be a regular expression, -and must be surrounded by `/`. -(With regular expression flags appended after the closing `/`.) -So `issue-/.*/` won't work to match all tag names or branch names -that begin with `issue-`. +To match the tag or branch name, +the entire ref name part of the pattern must be a regular expression surrounded by `/`. +For example, you can't use `issue-/.*/` to match all tag names or branch names +that begin with `issue-`, but you can use `/issue-.*/`. + +Regular expression flags must be appended after the closing `/`. TIP: **Tip:** Use anchors `^` and `$` to avoid the regular expression @@ -1706,20 +1694,17 @@ while just `/issue/` would also match a branch called `severe-issues`. #### Supported `only`/`except` regexp syntax -CAUTION: **Warning:** -This is a breaking change that was introduced with GitLab 11.9.4. - -In GitLab 11.9.4, GitLab begun internally converting regexp used +In GitLab 11.9.4, GitLab began internally converting the regexp used in `only` and `except` parameters to [RE2](https://github.com/google/re2/wiki/Syntax). -This means that only subset of features provided by [Ruby Regexp](https://ruby-doc.org/core/Regexp.html) -is supported. [RE2](https://github.com/google/re2/wiki/Syntax) limits the set of features -provided due to computational complexity, which means some features became unavailable in GitLab 11.9.4. -For example, negative lookaheads. +[RE2](https://github.com/google/re2/wiki/Syntax) limits the set of available features +due to computational complexity, and some features, like negative lookaheads, became unavailable. +Only a subset of features provided by [Ruby Regexp](https://ruby-doc.org/core/Regexp.html) +are now supported. -For GitLab versions from 11.9.7 and up to GitLab 12.0, GitLab provides a feature flag that can be -enabled by administrators that allows users to use unsafe regexp syntax. This brings compatibility -with previously allowed syntax version and allows users to gracefully migrate to the new syntax. +From GitLab 11.9.7 to GitLab 12.0, GitLab provided a feature flag to +let you use the unsafe regexp syntax. This flag allowed +compatibility with the previous syntax version so you could gracefully migrate to the new syntax. ```ruby Feature.enable(:allow_unsafe_ruby_regexp) @@ -1727,10 +1712,6 @@ Feature.enable(:allow_unsafe_ruby_regexp) ### `only`/`except` (advanced) -CAUTION: **Warning:** -This is an _alpha_ feature, and is subject to change at any time without -prior notice! - GitLab supports both simple and complex strategies, so it's possible to use an array and a hash configuration scheme. @@ -1741,7 +1722,7 @@ Four keys are available: - `changes` - `kubernetes` -If you use multiple keys under `only` or `except`, the keys will be evaluated as a +If you use multiple keys under `only` or `except`, the keys are evaluated as a single conjoined expression. That is: - `only:` includes the job if **all** of the keys have at least one condition that matches. @@ -1752,9 +1733,9 @@ the pipeline if the following is true: - `(any listed refs are true) AND (any listed variables are true) AND (any listed changes are true) AND (any chosen Kubernetes status matches)` -In the example below, the `test` job will `only` be created when **all** of the following are true: +In the example below, the `test` job is `only` created when **all** of the following are true: -- The pipeline has been [scheduled](../../user/project/pipelines/schedules.md) **or** runs for `master`. +- The pipeline has been [scheduled](../pipelines/schedules.md) **or** runs for `master`. - The `variables` keyword matches. - The `kubernetes` service is active on the project. @@ -1775,7 +1756,7 @@ added if the following is true: - `(any listed refs are true) OR (any listed variables are true) OR (any listed changes are true) OR (a chosen Kubernetes status matches)` -In the example below, the `test` job will **not** be created when **any** of the following are true: +In the example below, the `test` job is **not** created when **any** of the following are true: - The pipeline runs for the `master` branch. - There are changes to the `README.md` file in the root directory of the repository. @@ -1797,8 +1778,8 @@ test: The `refs` strategy can take the same values as the [simplified only/except configuration](#onlyexcept-basic). -In the example below, the `deploy` job is going to be created only when the -pipeline has been [scheduled](../pipelines/schedules.md) or runs for the `master` branch: +In the example below, the `deploy` job is created only when the +pipeline is [scheduled](../pipelines/schedules.md) or runs for the `master` branch: ```yaml deploy: @@ -1814,7 +1795,7 @@ deploy: The `kubernetes` strategy accepts only the `active` keyword. -In the example below, the `deploy` job is going to be created only when the +In the example below, the `deploy` job is created only when the Kubernetes service is active in the project: ```yaml @@ -1827,12 +1808,11 @@ deploy: > `variables` policy introduced in GitLab 10.7. -The `variables` keyword is used to define variables expressions. In other words, -you can use predefined variables / project / group or -environment-scoped variables to define an expression GitLab is going to -evaluate in order to decide whether a job should be created or not. +The `variables` keyword defines variable expressions. + +These expressions determine whether or not a job should be created. -Examples of using variables expressions: +Examples of using variable expressions: ```yaml deploy: @@ -1902,22 +1882,21 @@ docker build: - more_scripts/*.{rb,py,sh} ``` -In the scenario above, when pushing commits to an existing branch in GitLab, -it creates and triggers the `docker build` job, provided that one of the -commits contains changes to any of the following: +When you push commits to an existing branch, +the `docker build` job is created, but only if changes were made to any of the following: - The `Dockerfile` file. -- Any of the files inside `docker/scripts/` directory. -- Any of the files and subdirectories inside the `dockerfiles` directory. -- Any of the files with `rb`, `py`, `sh` extensions inside the `more_scripts` directory. +- Any of the files in the `docker/scripts/` directory. +- Any of the files and subdirectories in the `dockerfiles` directory. +- Any of the files with `rb`, `py`, `sh` extensions in the `more_scripts` directory. CAUTION: **Warning:** -If using `only:changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), -undesired behavior could result if you don't [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). +If you use `only:changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), +you should [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected. You can also use glob patterns to match multiple files in either the root directory -of the repository, or in _any_ directory within the repository, but they must be wrapped -in double quotes or GitLab will fail to parse the `.gitlab-ci.yml`. For example: +of the repository, or in _any_ directory within the repository. However, they must be wrapped +in double quotes or GitLab can't parse them. For example: ```yaml test: @@ -1930,10 +1909,8 @@ test: - "**/*.sql" ``` -The following example will skip the `build` job if a change is detected in any file -in the root directory of the repository with a `.md` extension. This mean that if you change multiple files, -but only one file is a `.md` file, the `build` job will still be skipped and will -not run for the other files. +You can skip a job if a change is detected in any file with a +`.md` extension in the root directory of the repository: ```yaml build: @@ -1943,13 +1920,13 @@ build: - "*.md" ``` -CAUTION: **Warning:** -There are some points to be aware of when -[using this feature with new branches or tags *without* pipelines for merge requests](#using-onlychanges-without-pipelines-for-merge-requests). +If you change multiple files, but only one file ends in `.md`, +the `build` job is still skipped. The job does not run for any of the files. -CAUTION: **Warning:** -There are some points to be aware of when -[using this feature with scheduled pipelines](#using-onlychanges-with-scheduled-pipelines). +Read more about how to use this feature with: + +- [New branches or tags *without* pipelines for merge requests](#using-onlychanges-without-pipelines-for-merge-requests). +- [Scheduled pipelines](#using-onlychanges-with-scheduled-pipelines). ##### Using `only:changes` with pipelines for merge requests @@ -1957,7 +1934,7 @@ With [pipelines for merge requests](../merge_request_pipelines/index.md), it's possible to define a job to be created based on files modified in a merge request. -In order to deduce the correct base SHA of the source branch, we recommend combining +To deduce the correct base SHA of the source branch, we recommend combining this keyword with `only: [merge_requests]`. This way, file differences are correctly calculated from any further commits, thus all changes in the merge requests are properly tested in pipelines. @@ -1975,13 +1952,9 @@ docker build service one: - service-one/**/* ``` -In the scenario above, if a merge request is created or updated that changes -either files in `service-one` directory or the `Dockerfile`, GitLab creates -and triggers the `docker build service one` job. - -Note that if [pipelines for merge requests](../merge_request_pipelines/index.md) is -combined with `only: [change]`, but `only: [merge_requests]` is omitted, there could be -unwanted behavior. +In this scenario, if a merge request changes +files in the `service-one` directory or the `Dockerfile`, GitLab creates +the `docker build service one` job. For example: @@ -1994,15 +1967,17 @@ docker build service one: - service-one/**/* ``` -In the example above, a pipeline could fail due to changes to a file in `service-one/**/*`. -A later commit could then be pushed that does not include any changes to this file, -but includes changes to the `Dockerfile`, and this pipeline could pass because it's only -testing the changes to the `Dockerfile`. GitLab checks the **most recent pipeline**, -that **passed**, and will show the merge request as mergeable, despite the earlier -failed pipeline caused by a change that was not yet corrected. +In the example above, the pipeline might fail because of changes to a file in `service-one/**/*`. + +A later commit that doesn't have changes in `service-one/**/*` +but does have changes to the `Dockerfile` can pass. The job +only tests the changes to the `Dockerfile`. -With this configuration, care must be taken to check that the most recent pipeline -properly corrected any failures from previous pipelines. +GitLab checks the **most recent pipeline** that **passed**. If the merge request is mergeable, +it doesn't matter that an earlier pipeline failed because of a change that has not been corrected. + +When you use this configuration, ensure that the most recent pipeline +properly corrects any failures from previous pipelines. ##### Using `only:changes` without pipelines for merge requests @@ -2068,15 +2043,15 @@ production: This example creates four paths of execution: -- Linter: the `lint` job will run immediately without waiting for the `build` stage to complete because it has no needs (`needs: []`). +- Linter: the `lint` job runs immediately without waiting for the `build` stage to complete because it has no needs (`needs: []`). -- Linux path: the `linux:rspec` and `linux:rubocop` jobs will be run as soon +- Linux path: the `linux:rspec` and `linux:rubocop` jobs runs as soon as the `linux:build` job finishes without waiting for `mac:build` to finish. -- macOS path: the `mac:rspec` and `mac:rubocop` jobs will be run as soon +- macOS path: the `mac:rspec` and `mac:rubocop` jobs runs as soon as the `mac:build` job finishes, without waiting for `linux:build` to finish. -- The `production` job will be executed as soon as all previous jobs +- The `production` job runs as soon as all previous jobs finish; in this case: `linux:build`, `linux:rspec`, `linux:rubocop`, `mac:build`, `mac:rspec`, `mac:rubocop`. @@ -2084,14 +2059,14 @@ This example creates four paths of execution: - If `needs:` is set to point to a job that is not instantiated because of `only/except` rules or otherwise does not exist, the - pipeline will be created with YAML error. + pipeline is not created and a YAML error is shown. - The maximum number of jobs that a single job can need in the `needs:` array is limited: - For GitLab.com, the limit is 50. For more information, see our [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541). - For self-managed instances, the limit is: 50. This limit [can be changed](#changing-the-needs-job-limit). - If `needs:` refers to a job that is marked as `parallel:`. - the current job will depend on all parallel jobs created. -- `needs:` is similar to `dependencies:` in that it needs to use jobs from prior stages, + the current job depends on all parallel jobs being created. +- `needs:` is similar to `dependencies:` in that it must use jobs from prior stages, meaning it's impossible to create circular dependencies. Depending on jobs in the current stage is not possible either, but support [is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/30632). - Related to the above, stages must be explicitly defined for all jobs @@ -2108,8 +2083,7 @@ can choose a custom limit. For example, to set the limit to 100: Plan.default.actual_limits.update!(ci_needs_size_limit: 100) ``` -NOTE: **Note:** -To disable the ability to use DAG, set the limit to `0`. +To disable directed acyclic graphs (DAG), set the limit to `0`. #### Artifact downloads with `needs` @@ -2117,12 +2091,12 @@ To disable the ability to use DAG, set the limit to `0`. When using `needs`, artifact downloads are controlled with `artifacts: true` (default) or `artifacts: false`. -Since GitLab 12.6, you can't combine the [`dependencies`](#dependencies) keyword +In GitLab 12.6 and later, you can't combine the [`dependencies`](#dependencies) keyword with `needs` to control artifact downloads in jobs. `dependencies` is still valid in jobs that do not use `needs`. -In the example below, the `rspec` job will download the `build_job` artifacts, while the -`rubocop` job won't: +In the example below, the `rspec` job downloads the `build_job` artifacts, while the +`rubocop` job doesn't: ```yaml build_job: @@ -2144,9 +2118,9 @@ rubocop: artifacts: false ``` -Additionally, in the three syntax examples below, the `rspec` job will download the artifacts -from all three `build_jobs`, as `artifacts` is true for `build_job_1`, and will -**default** to true for both `build_job_2` and `build_job_3`. +Additionally, in the three syntax examples below, the `rspec` job downloads the artifacts +from all three `build_jobs`. `artifacts` is true for `build_job_1` and +**defaults** to true for both `build_job_2` and `build_job_3`. ```yaml rspec: @@ -2161,9 +2135,10 @@ rspec: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.7. -`needs` can be used to download artifacts from up to five jobs in pipelines on -[other refs in the same project](#artifact-downloads-between-pipelines-in-the-same-project), -or pipelines in different projects, groups and namespaces: +Use `needs` to download artifacts from up to five jobs in pipelines: + +- [On other refs in the same project](#artifact-downloads-between-pipelines-in-the-same-project). +- In different projects, groups and namespaces. ```yaml build_job: @@ -2177,7 +2152,7 @@ build_job: artifacts: true ``` -`build_job` will download the artifacts from the latest successful `build-1` job +`build_job` downloads the artifacts from the latest successful `build-1` job on the `master` branch in the `group/project-name` project. If the project is in the same group or namespace, you can omit them from the `project:` key. For example, `project: group/project-name` or `project: project-name`. @@ -2186,9 +2161,10 @@ The user running the pipeline must have at least `reporter` access to the group ##### Artifact downloads between pipelines in the same project -`needs` can be used to download artifacts from different pipelines in the current project -by setting the `project` keyword as the current project's name, and specifying a ref. -In the example below, `build_job` will download the artifacts for the latest successful +Use `needs` to download artifacts from different pipelines in the current project. +Set the `project` keyword as the current project's name, and specify a ref. + +In this example, `build_job` downloads the artifacts for the latest successful `build-1` job with the `other-ref` ref: ```yaml @@ -2220,7 +2196,6 @@ build_job: artifacts: true ``` -NOTE: **Note:** Downloading artifacts from jobs that are run in [`parallel:`](#parallel) is not supported. ### `tags` @@ -2232,7 +2207,7 @@ When you register a runner, you can specify the runner's tags, for example `ruby`, `postgres`, `development`. In this example, the job is run by a runner that -has both `ruby` AND `postgres` tags defined. +has both `ruby` and `postgres` tags defined. ```yaml job: @@ -2271,16 +2246,16 @@ The default value is `false`, except for [manual](#whenmanual) jobs using the `when: manual` syntax, unless using [`rules:`](#rules) syntax, where all jobs default to false, *including* `when: manual` jobs. -When enabled and the job fails, the job will show an orange warning in the UI. -However, the logical flow of the pipeline will consider the job a +When `allow_failure` is enabled and the job fails, the job shows an orange warning in the UI. +However, the logical flow of the pipeline considers the job a success/passed, and is not blocked. -Assuming all other jobs are successful, the job's stage and its pipeline will -show the same orange warning. However, the associated commit will be marked +Assuming all other jobs are successful, the job's stage and its pipeline +show the same orange warning. However, the associated commit is marked as "passed", without warnings. -In the example below, `job1` and `job2` will run in parallel, but if `job1` -fails, it won't stop the next stage from running, since it's marked with +In the example below, `job1` and `job2` run in parallel, but if `job1` +fails, it doesn't stop the next stage from running, because it's marked with `allow_failure: true`: ```yaml @@ -2309,15 +2284,15 @@ failure. `when` can be set to one of the following values: 1. `on_success` - execute job only when all jobs from prior stages - succeed (or are considered succeeding because they are marked - `allow_failure`). This is the default. + succeed (or are considered succeeding because they have `allow_failure: true`). + This is the default. 1. `on_failure` - execute job only when at least one job from prior stages fails. 1. `always` - execute job regardless of the status of jobs from prior stages. 1. `manual` - execute job manually (added in GitLab 8.10). Read about - [manual actions](#whenmanual) below. + [manual jobs](#whenmanual) below. 1. `delayed` - execute job after a certain period (added in GitLab 11.14). - Read about [delayed actions](#whendelayed) below. + Read about [delayed jobs](#whendelayed) below. 1. `never`: - With [`rules`](#rules), don't execute job. - With [`workflow:rules`](#workflowrules), don't run pipeline. @@ -2371,45 +2346,44 @@ The above script: #### `when:manual` > - Introduced in GitLab 8.10. -> - Blocking manual actions were introduced in GitLab 9.0. +> - Blocking manual jobs were introduced in GitLab 9.0. > - Protected actions were introduced in GitLab 9.2. -Manual actions are a special type of job that are not executed automatically, -they need to be explicitly started by a user. An example usage of manual actions -would be a deployment to a production environment. Manual actions can be started -from the pipeline, job, environment, and deployment views. Read more at the -[environments documentation](../environments/index.md#configuring-manual-deployments). +A manual job is a type of job that is not executed automatically and must be explicitly +started by a user. You might want to use manual jobs for things like deploying to production. -Manual actions can be either optional or blocking. Blocking manual actions will -block the execution of the pipeline at the stage this action is defined in. It's -possible to resume execution of the pipeline when someone executes a blocking -manual action by clicking a _play_ button. +To make a job manual, add `when: manual` to its configuration. -When a pipeline is blocked, it won't be merged if Merge When Pipeline Succeeds -is set. Blocked pipelines also do have a special status, called _manual_. -When the `when:manual` syntax is used, manual actions are non-blocking by -default. If you want to make manual action blocking, it's necessary to add -`allow_failure: false` to the job's definition in `.gitlab-ci.yml`. +Manual jobs can be started from the pipeline, job, [environment](../environments/index.md#configuring-manual-deployments), +and deployment views. -Optional manual actions have `allow_failure: true` set by default and their -Statuses don't contribute to the overall pipeline status. So, if a manual -action fails, the pipeline will eventually succeed. +Manual jobs can be either optional or blocking: -NOTE: **Note:** -When using [`rules:`](#rules), `allow_failure` defaults to `false`, including for manual jobs. +- **Optional**: Manual jobs have [`allow_failure: true](#allow_failure) set by default + and are considered optional. The status of an optional manual job does not contribute + to the overall pipeline status. A pipeline can succeed even if all its manual jobs fail. -Manual actions are considered to be write actions, so permissions for -[protected branches](../../user/project/protected_branches.md) are used when -a user wants to trigger an action. In other words, in order to trigger a manual -action assigned to a branch that the pipeline is running for, the user needs to -have the ability to merge to this branch. It's possible to use protected environments -to more strictly [protect manual deployments](#protecting-manual-jobs) from being -run by unauthorized users. +- **Blocking**: To make a blocking manual job, add `allow_failure: false` to its configuration. + Blocking manual jobs stop further execution of the pipeline at the stage where the + job is defined. To let the pipeline continue running, click **{play}** (play) on + the blocking manual job. -NOTE: **Note:** -Using `when:manual` and `trigger` together results in the error `jobs:#{job-name} when -should be on_success, on_failure or always`, because `when:manual` prevents triggers -being used. + Merge requests in projects with [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md) + enabled can't be merged with a blocked pipeline. Blocked pipelines show a status + of **blocked**. + +When you use [`rules:`](#rules), `allow_failure` defaults to `false`, including for manual jobs. + +To trigger a manual job, a user must have permission to merge to the assigned branch. +You can use [protected branches](../../user/project/protected_branches.md) to more strictly +[protect manual deployments](#protecting-manual-jobs) from being run by unauthorized users. + +In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you +can use `when:manual` in the same job as [`trigger`](#trigger). In GitLab 13.4 and +earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. +It is deployed behind the `:ci_manual_bridges` [feature flag](../../user/feature_flags.md), which is **enabled by default**. +[GitLab administrators with access to the Rails console](../../administration/feature_flags.md) +can opt to disable it. ##### Protecting manual jobs **(PREMIUM)** @@ -2441,12 +2415,12 @@ To do this, you must: 1. In the [protected environments settings](../environments/protected_environments.md#protecting-environments), select the environment (`production` in the example above) and add the users, roles or groups that are authorized to trigger the manual job to the **Allowed to Deploy** list. Only those in - this list will be able to trigger this manual job, as well as GitLab administrators + this list can trigger this manual job, as well as GitLab administrators who are always able to use protected environments. -Additionally, if a manual job is defined as blocking by adding `allow_failure: false`, -the next stages of the pipeline won't run until the manual job is triggered. This -can be used as a way to have a defined list of users allowed to "approve" later pipeline +Additionally, if you define a manual job as blocking by adding `allow_failure: false`, +the pipeline's next stages don't run until the manual job is triggered. You can use this +to define a list of users allowed to "approve" later pipeline stages by triggering the blocking manual job. #### `when:delayed` @@ -2465,11 +2439,11 @@ provided. `start_in` key must be less than or equal to one week. Examples of val - `1 day` - `1 week` -When there is a delayed job in a stage, the pipeline won't progress until the delayed job has finished. +When there is a delayed job in a stage, the pipeline doesn't progress until the delayed job has finished. This means this keyword can also be used for inserting delays between different stages. The timer of a delayed job starts immediately after the previous stage has completed. -Similar to other types of jobs, a delayed job's timer won't start unless the previous stage passed. +Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passed. The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed: @@ -2482,7 +2456,7 @@ timed rollout 10%: ``` You can stop the active timer of a delayed job by clicking the **{time-out}** (**Unschedule**) button. -This job will never be executed in the future unless you execute the job manually. +This job can no longer be scheduled to run automatically. You can, however, execute the job manually. To start a delayed job immediately, click the **Play** button. Soon GitLab Runner picks up and starts the job. @@ -2495,7 +2469,7 @@ Soon GitLab Runner picks up and starts the job. `environment` is used to define that a job deploys to a specific environment. If `environment` is specified and no environment under that name exists, a new -one will be created automatically. +one is created automatically. In its simplest form, the `environment` keyword can be defined like: @@ -2506,7 +2480,7 @@ deploy to production: environment: production ``` -In the above example, the `deploy to production` job will be marked as doing a +In the above example, the `deploy to production` job is marked as doing a deployment to the `production` environment. #### `environment:name` @@ -2574,12 +2548,12 @@ deploy to production: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) in GitLab 8.13. > - Starting with GitLab 8.14, when you have an environment that has a stop action -> defined, GitLab will automatically trigger a stop action when the associated +> defined, GitLab automatically triggers a stop action when the associated > branch is deleted. -Closing (stopping) environments can be achieved with the `on_stop` keyword defined under -`environment`. It declares a different job that runs in order to close -the environment. +Closing (stopping) environments can be achieved with the `on_stop` keyword +defined under `environment`. It declares a different job that runs to close the +environment. Read the `environment:action` section for an example. @@ -2591,7 +2565,7 @@ The `action` keyword can be used to specify jobs that prepare, start, or stop en | **Value** | **Description** | |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| -| start | Default value. Indicates that job starts the environment. Deployment will be created after job starts. | +| start | Default value. Indicates that job starts the environment. The deployment is created after the job starts. | | prepare | Indicates that job is only preparing the environment. Does not affect deployments. [Read more about environments](../environments/index.md#prepare-an-environment) | | stop | Indicates that job stops deployment. See the example below. | @@ -2617,21 +2591,20 @@ stop_review_app: action: stop ``` -In the above example we set up the `review_app` job to deploy to the `review` -environment, and we also defined a new `stop_review_app` job under `on_stop`. -Once the `review_app` job is successfully finished, it will trigger the -`stop_review_app` job based on what is defined under `when`. In this case we -set it up to `manual` so it will need a [manual action](#whenmanual) via -GitLab's web interface in order to run. +In the above example, the `review_app` job deploys to the `review` +environment. A new `stop_review_app` job is listed under `on_stop`. +After the `review_app` job is finished, it triggers the +`stop_review_app` job based on what is defined under `when`. In this case, +it is set to `manual`, so it needs a [manual action](#whenmanual) from +GitLab's user interface to run. -Also in the example, `GIT_STRATEGY` is set to `none` so that GitLab Runner won’t -try to check out the code after the branch is deleted when the `stop_review_app` -job is [automatically triggered](../environments/index.md#automatically-stopping-an-environment). +Also in the example, `GIT_STRATEGY` is set to `none`. If the +`stop_review_app` job is [automatically triggered](../environments/index.md#automatically-stopping-an-environment), +the runner won’t try to check out the code after the branch is deleted. -NOTE: **Note:** -The above example overwrites global variables. If your stop environment job depends -on global variables, you can use [anchor variables](#yaml-anchors-for-variables) when setting the `GIT_STRATEGY` -to change it without overriding the global variables. +The example also overwrites global variables. If your `stop` `environment` job depends +on global variables, you can use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`. +This changes the job without overriding the global variables. The `stop_review_app` job is **required** to have the following keywords defined: @@ -2640,10 +2613,12 @@ The `stop_review_app` job is **required** to have the following keywords defined - `environment:action` Additionally, both jobs should have matching [`rules`](../yaml/README.md#onlyexcept-basic) -or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. In the example -above, if the configuration is not identical, the `stop_review_app` job might not be -included in all pipelines that include the `review_app` job, and it will not be -possible to trigger the `action: stop` to stop the environment automatically. +or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. + +In the example above, if the configuration is not identical: + +- The `stop_review_app` job might not be included in all pipelines that include the `review_app` job. +- It is not possible to trigger the `action: stop` to stop the environment automatically. #### `environment:auto_stop_in` @@ -2687,7 +2662,7 @@ deploy: namespace: production ``` -This will set up the `deploy` job to deploy to the `production` +This configuration sets up the `deploy` job to deploy to the `production` environment, using the `production` [Kubernetes namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). @@ -2719,11 +2694,11 @@ deploy as review app: url: https://$CI_ENVIRONMENT_SLUG.example.com/ ``` -The `deploy as review app` job will be marked as deployment to dynamically +The `deploy as review app` job is marked as deployment to dynamically create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME` is an [environment variable](../variables/README.md) set by the runner. The `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable -for inclusion in URLs. In this case, if the `deploy as review app` job was run +for inclusion in URLs. In this case, if the `deploy as review app` job is run in a branch named `pow`, this environment would be accessible with an URL like `https://review-pow.example.com/`. @@ -2742,16 +2717,15 @@ as Review Apps. You can see a simple example using Review Apps at > by default. > - From GitLab 9.2, caches are restored before [artifacts](#artifacts). -TIP: **Learn more:** -Read how caching works and find out some good practices in the -[caching dependencies documentation](../caching/index.md). - `cache` is used to specify a list of files and directories that should be cached between jobs. You can only use paths that are within the local working copy. If `cache` is defined outside the scope of jobs, it means it's set -globally and all jobs will use that definition. +globally and all jobs use that definition. + +Read how caching works and find out some good practices in the +[caching dependencies documentation](../caching/index.md). #### `cache:paths` @@ -2777,7 +2751,7 @@ rspec: ``` Locally defined cache overrides globally defined options. The following `rspec` -job will cache only `binaries/`: +job caches only `binaries/`: ```yaml cache: @@ -2792,20 +2766,20 @@ rspec: - binaries/ ``` -Note that since cache is shared between jobs, if you're using different -paths for different jobs, you should also set a different **cache:key** -otherwise cache content can be overwritten. +The cache is shared between jobs, so if you're using different +paths for different jobs, you should also set a different `cache:key`. +Otherwise cache content can be overwritten. #### `cache:key` > Introduced in GitLab Runner v1.0.0. -Since the cache is shared between jobs, if you're using different -paths for different jobs, you should also set a different `cache:key` -otherwise cache content can be overwritten. +The cache is shared between jobs, so if you're using different +paths for different jobs, you should also set a different `cache:key`. +Otherwise cache content can be overwritten. -The `key` parameter defines the affinity of caching between jobs, -to have a single cache for all jobs, cache per-job, cache per-branch +The `key` parameter defines the affinity of caching between jobs. +You can have a single cache for all jobs, cache per-job, cache per-branch, or any other way that fits your workflow. This way, you can fine tune caching, including caching data between different jobs or even different branches. @@ -2814,10 +2788,6 @@ The `cache:key` variable can use any of the set, is just literal `default`, which means everything is shared between pipelines and jobs by default, starting from GitLab 9.0. -NOTE: **Note:** -The `cache:key` variable can't contain the `/` character, or the equivalent -URI-encoded `%2F`; a value made only of dots (`.`, `%2E`) is also forbidden. - For example, to enable per-branch caching: ```yaml @@ -2837,18 +2807,23 @@ cache: - binaries/ ``` +The `cache:key` variable can't contain the `/` character, or the equivalent +URI-encoded `%2F`. A value made only of dots (`.`, `%2E`) is also forbidden. + +You can specify a [fallback cache key](#fallback-cache-key) to use if the specified `cache:key` is not found. + ##### `cache:key:files` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. The `cache:key:files` keyword extends the `cache:key` functionality by making it easier -to reuse some caches, and rebuild them less often, which will speed up subsequent pipeline +to reuse some caches, and rebuild them less often, which speeds up subsequent pipeline runs. -When you include `cache:key:files`, you must also list the project files that will be used to generate the key, up to a maximum of two files. -The cache `key` will be a SHA checksum computed from the most recent commits (up to two, if two files are listed) +When you include `cache:key:files`, you must also list the project files that are used to generate the key, up to a maximum of two files. +The cache `key` is a SHA checksum computed from the most recent commits (up to two, if two files are listed) that changed the given files. If neither file was changed in any commits, -the fallback key will be `default`. +the fallback key is `default`. ```yaml cache: @@ -2864,7 +2839,7 @@ cache: In this example we're creating a cache for Ruby and Node.js dependencies that is tied to current versions of the `Gemfile.lock` and `package.json` files. Whenever one of these files changes, a new cache key is computed and a new cache is created. Any future -job runs using the same `Gemfile.lock` and `package.json` with `cache:key:files` will +job runs that use the same `Gemfile.lock` and `package.json` with `cache:key:files` use the new cache, instead of rebuilding the dependencies. ##### `cache:key:prefix` @@ -2897,11 +2872,11 @@ rspec: - bundle exec rspec ``` -For example, adding a `prefix` of `$CI_JOB_NAME` will -cause the key to look like: `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5` and +For example, adding a `prefix` of `$CI_JOB_NAME` +causes the key to look like: `rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5` and the job cache is shared across different branches. If a branch changes -`Gemfile.lock`, that branch will have a new SHA checksum for `cache:key:files`. A new cache key -will be generated, and a new cache will be created for that key. +`Gemfile.lock`, that branch has a new SHA checksum for `cache:key:files`. A new cache key +is generated, and a new cache is created for that key. If `Gemfile.lock` is not found, the prefix is added to `default`, so the key in the example would be `rspec-default`. @@ -2928,6 +2903,28 @@ rspec: - binaries/ ``` +#### `cache:when` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18969) in GitLab 13.5 and GitLab Runner v13.5.0. + +`cache:when` defines when to save the cache, based on the status of the job. You can +set `cache:when` to: + +- `on_success` - save the cache only when the job succeeds. This is the default. +- `on_failure` - save the cache only when the job fails. +- `always` - save the cache regardless of the job status. + +For example, to store a cache whether or not the job fails or succeeds: + +```yaml +rspec: + script: rspec + cache: + paths: + - rspec/ + when: 'always' +``` + #### `cache:policy` > Introduced in GitLab 9.4. @@ -2967,13 +2964,13 @@ rspec: - bundle exec rspec ... ``` -This helps to speed up job execution and reduce load on the cache server, -especially when you have a large number of cache-using jobs executing in +This helps to speed up job execution and reduce load on the cache server. +It is especially helpful when you have a large number of cache-using jobs executing in parallel. -Additionally, if you have a job that unconditionally recreates the cache without -reference to its previous contents, you can use `policy: push` in that job to -skip the download step. +If you have a job that unconditionally recreates the cache without +referring to its previous contents, you can skip the download step. +To do so, add `policy: push` to the job. ### `artifacts` @@ -2986,8 +2983,8 @@ skip the download step. `artifacts` is used to specify a list of files and directories that are attached to the job when it [succeeds, fails, or always](#artifactswhen). -The artifacts will be sent to GitLab after the job finishes and will -be available for download in the GitLab UI provided that the size is not +The artifacts are sent to GitLab after the job finishes. They are +available for download in the GitLab UI if the size is not larger than the [maximum artifact size](../../user/gitlab_com/index.md#gitlab-cicd). [Read more about artifacts](../pipelines/job_artifacts.md). @@ -3003,7 +3000,7 @@ patterns and: - In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath/#Match). -To restrict which jobs a specific job will fetch artifacts from, see [dependencies](#dependencies). +To restrict which jobs a specific job fetches artifacts from, see [dependencies](#dependencies). Send all files in `binaries` and `.config`: @@ -3026,7 +3023,7 @@ job: You may want to create artifacts only for tagged releases to avoid filling the build server storage with temporary build artifacts. -Create artifacts only for tags (`default-job` won't create artifacts): +Create artifacts only for tags (`default-job` doesn't create artifacts): ```yaml default-job: @@ -3098,10 +3095,10 @@ test: paths: ['file.txt'] ``` -With this configuration, GitLab will add a link **artifact 1** to the relevant merge request +With this configuration, GitLab adds a link **artifact 1** to the relevant merge request that points to `file1.txt`. -An example that will match an entire directory: +An example that matches an entire directory: ```yaml test: @@ -3116,12 +3113,12 @@ Note the following: - Artifacts do not display in the merge request UI when using variables to define the `artifacts:paths`. - A maximum of 10 job artifacts per merge request can be exposed. - Glob patterns are unsupported. -- If a directory is specified, the link will be to the job [artifacts browser](../pipelines/job_artifacts.md#browsing-artifacts) if there is more than +- If a directory is specified, the link is to the job [artifacts browser](../pipelines/job_artifacts.md#browsing-artifacts) if there is more than one file in the directory. - For exposed single file artifacts with `.html`, `.htm`, `.txt`, `.json`, `.xml`, and `.log` extensions, if [GitLab Pages](../../administration/pages/index.md) is: - - Enabled, GitLab will automatically render the artifact. - - Not enabled, you will see the file in the artifacts browser. + - Enabled, GitLab automatically renders the artifact. + - Not enabled, the file is displayed in the artifacts browser. #### `artifacts:name` @@ -3133,11 +3130,6 @@ useful when you want to download the archive from GitLab. The `artifacts:name` variable can make use of any of the [predefined variables](../variables/README.md). The default name is `artifacts`, which becomes `artifacts.zip` when you download it. -NOTE: **Note:** -If your branch-name contains forward slashes -(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG` -instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact. - To create an archive with a name of the current job: ```yaml @@ -3159,6 +3151,10 @@ job: - binaries/ ``` +If your branch-name contains forward slashes +(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG` +instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact. + To create an archive with a name of the current job and the current branch or tag including only the binaries directory: @@ -3207,10 +3203,8 @@ job: #### `artifacts:untracked` `artifacts:untracked` is used to add all Git untracked files as artifacts (along -to the paths defined in `artifacts:paths`). - -NOTE: **Note:** -`artifacts:untracked` ignores configuration in the repository's `.gitignore` file. +to the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration +in the repository's `.gitignore` file. Send all Git untracked files: @@ -3250,7 +3244,7 @@ failure. 1. `on_failure` - upload artifacts only when the job fails. 1. `always` - upload artifacts regardless of the job status. -To upload artifacts only when job fails: +For example, to upload artifacts only when a job fails: ```yaml job: @@ -3300,7 +3294,6 @@ job: expire_in: 1 week ``` -NOTE: **Note:** The latest artifacts for refs are locked against deletion, and kept regardless of the expiry time. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) GitLab 13.0 behind a disabled feature flag, and [made the default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) @@ -3335,24 +3328,27 @@ These are the available report types: > Introduced in GitLab 8.6 and GitLab Runner v1.1.1. -By default, all [`artifacts`](#artifacts) from all previous [stages](#stages) -are passed, but you can use the `dependencies` parameter to define a limited -list of jobs (or no jobs) to fetch artifacts from. +By default, all [`artifacts`](#artifacts) from previous [stages](#stages) +are passed to each job. However, you can use the `dependencies` parameter to +define a limited list of jobs to fetch artifacts from. You can also set a job to download no artifacts at all. To use this feature, define `dependencies` in context of the job and pass a list of all previous jobs the artifacts should be downloaded from. -You can only define jobs from stages that are executed before the current one. -An error will be shown if you define jobs from the current stage or next ones. -Defining an empty array will skip downloading any artifacts for that job. -The status of the previous job is not considered when using `dependencies`, so -if it failed or it's a manual job that was not run, no error occurs. -In the following example, we define two jobs with artifacts, `build:osx` and +You can define jobs from stages that were executed before the current one. +An error occurs if you define jobs from the current or an upcoming stage. + +To prevent a job from downloading artifacts, define an empty array. + +When you use `dependencies`, the status of the previous job is not considered. +If a job fails or it's a manual job that was not run, no error occurs. + +The following example defines two jobs with artifacts: `build:osx` and `build:linux`. When the `test:osx` is executed, the artifacts from `build:osx` -will be downloaded and extracted in the context of the build. The same happens +are downloaded and extracted in the context of the build. The same happens for `test:linux` and artifacts from `build:linux`. -The job `deploy` will download artifacts from all previous jobs because of +The job `deploy` downloads artifacts from all previous jobs because of the [stage](#stages) precedence: ```yaml @@ -3387,16 +3383,15 @@ deploy: script: make deploy ``` -##### When a dependent job will fail +##### When a dependent job fails > Introduced in GitLab 10.3. If the artifacts of the job that is set as a dependency have been [expired](#artifactsexpire_in) or [erased](../pipelines/job_artifacts.md#erasing-artifacts), then -the dependent job will fail. +the dependent job fails. -NOTE: **Note:** You can ask your administrator to [flip this switch](../../administration/job_artifacts.md#validation-for-dependencies) and bring back the old behavior. @@ -3409,7 +3404,7 @@ Use `coverage` to configure how code coverage is extracted from the job output. Regular expressions are the only valid kind of value expected here. So, using -surrounding `/` is mandatory in order to consistently and explicitly represent +surrounding `/` is mandatory to consistently and explicitly represent a regular expression string. You must escape special characters if you want to match them literally. @@ -3426,17 +3421,17 @@ job1: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3442) in GitLab 9.5. > - [Behavior expanded](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3515) in GitLab 11.5 to control which failures to retry on. -Use `retry` to configure how many times a job is going to be retried in +Use `retry` to configure how many times a job is retried in case of a failure. -When a job fails and has `retry` configured, it's going to be processed again -up to the amount of times specified by the `retry` keyword. +When a job fails, the job is processed again, +until the limit specified by the `retry` keyword is reached. -If `retry` is set to 2, and a job succeeds in a second run (first retry), it won't be retried -again. `retry` value has to be a positive integer, equal or larger than 0, but -lower or equal to 2 (two retries maximum, three runs in total). +If `retry` is set to `2`, and a job succeeds in a second run (first retry), it is not retried. +The `retry` value must be a positive integer, from `0` to `2` +(two retries maximum, three runs in total). -A simple example to retry in all failure cases: +This example retries all failure cases: ```yaml test: @@ -3444,7 +3439,7 @@ test: retry: 2 ``` -By default, a job will be retried on all failure cases. To have a better control +By default, a job is retried on all failure cases. To have better control over which failures to retry, `retry` can be a hash with the following keys: - `max`: The maximum number of retries. @@ -3460,8 +3455,8 @@ test: when: runner_system_failure ``` -If there is another failure, other than a runner system failure, the job will -not be retried. +If there is another failure, other than a runner system failure, the job +is not retried. To retry on multiple failure cases, `when` can also be an array of failures: @@ -3478,10 +3473,10 @@ test: Possible values for `when` are: @@ -3543,7 +3538,6 @@ test: parallel: 5 ``` -TIP: **Tip:** Parallelize tests suites across parallel jobs. Different languages have different tools to facilitate this. @@ -3578,6 +3572,12 @@ job split into three separate jobs. Use `matrix:` to configure different variables for jobs that are running in parallel. There can be from 2 to 50 jobs. +[In GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/26362) and later, +you can have one-dimensional matrices with a single job. +The ability to have one-dimensional matrices is [deployed behind a feature flag](../../user/feature_flags.md), +enabled by default. It's enabled on GitLab.com. For self-managed GitLab instances, +administrators can opt to disable it by [disabling the `one_dimensional_matrix:` feature flag](../../administration/feature_flags.md). **(CORE ONLY)** + Every job gets the same `CI_NODE_TOTAL` [environment variable](../variables/README.md#predefined-environment-variables) value, and a unique `CI_NODE_INDEX` value. ```yaml @@ -3623,19 +3623,25 @@ Job naming style [was improved](https://gitlab.com/gitlab-org/gitlab/-/issues/23 Use `trigger` to define a downstream pipeline trigger. When GitLab starts a job created with a `trigger` definition, a downstream pipeline is created. +Jobs with `trigger` can only use a [limited set of keywords](../multi_project_pipelines.md#limitations). +For example, you can't run commands with [`script`](#script), [`before_script`](#before_script-and-after_script), +or [`after_script`](#before_script-and-after_script). + You can use this keyword to create two different types of downstream pipelines: - [Multi-project pipelines](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml) - [Child pipelines](../parent_child_pipelines.md) -[Since GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can -see which job triggered a downstream pipeline by hovering your mouse cursor over -the downstream pipeline job in the [pipeline graph](../pipelines/index.md#visualize-pipelines). +[In GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/) and later, you can +view which job triggered a downstream pipeline. In the [pipeline graph](../pipelines/index.md#visualize-pipelines), +hover over the downstream pipeline job. -NOTE: **Note:** -Using a `trigger` with `when:manual` together results in the error `jobs:#{job-name} -when should be on_success, on_failure or always`, because `when:manual` prevents -triggers being used. +In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you +can use [`when:manual`](#whenmanual) in the same job as `trigger`. In GitLab 13.4 and +earlier, using them together causes the error `jobs:#{job-name} when should be on_success, on_failure or always`. +It is deployed behind the `:ci_manual_bridges` [feature flag](../../user/feature_flags.md), which is **enabled by default**. +[GitLab administrators with access to the Rails console](../../administration/feature_flags.md) +can opt to disable it. #### Simple `trigger` syntax for multi-project pipelines @@ -3654,7 +3660,7 @@ staging: #### Complex `trigger` syntax for multi-project pipelines -It's possible to configure a branch name that GitLab will use to create +You can configure a branch name that GitLab uses to create a downstream pipeline with: ```yaml @@ -3669,7 +3675,7 @@ staging: branch: stable ``` -It's possible to mirror the status from a triggered pipeline: +To mirror the status from a triggered pipeline: ```yaml trigger_job: @@ -3678,7 +3684,7 @@ trigger_job: strategy: depend ``` -It's possible to mirror the status from an upstream pipeline: +To mirror the status from an upstream pipeline: ```yaml upstream_bridge: @@ -3736,14 +3742,30 @@ child-pipeline: The `generated-config.yml` is extracted from the artifacts and used as the configuration for triggering the child pipeline. +##### Trigger child pipeline with files from another project + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205157) in GitLab 13.5. + +To trigger child pipelines with files from another private project under the same +GitLab instance, use [`include:file`](#includefile): + +```yaml +child-pipeline: + trigger: + include: + - project: 'my-group/my-pipeline-library' + ref: 'master' + file: '/path/to/child-pipeline.yml' +``` + #### Linking pipelines with `trigger:strategy` By default, the `trigger` job completes with the `success` status as soon as the downstream pipeline is created. To force the `trigger` job to wait for the downstream (multi-project or child) pipeline to complete, use -`strategy: depend`. This will make the trigger job wait with a "running" status until the triggered -pipeline completes. At that point, the `trigger` job will complete and display the same status as +`strategy: depend`. This setting makes the trigger job wait with a "running" status until the triggered +pipeline completes. At that point, the `trigger` job completes and displays the same status as the downstream job. ```yaml @@ -3753,16 +3775,16 @@ trigger_job: strategy: depend ``` -This can help keep your pipeline execution linear. In the example above, jobs from -subsequent stages will wait for the triggered pipeline to successfully complete before -starting, at the cost of reduced parallelization. +This setting can help keep your pipeline execution linear. In the example above, jobs from +subsequent stages wait for the triggered pipeline to successfully complete before +starting, which reduces parallelization. #### Trigger a pipeline by API call -Triggers can be used to force a rebuild of a specific branch, tag or commit, -with an API call when a pipeline gets created using a trigger token. +To force a rebuild of a specific branch, tag, or commit, you can use an API call +with a trigger token. -Not to be confused with the [`trigger`](#trigger) parameter. +The trigger token is different than the [`trigger`](#trigger) parameter. [Read more in the triggers documentation.](../triggers/README.md) @@ -3771,19 +3793,18 @@ Not to be confused with the [`trigger`](#trigger) parameter. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. `interruptible` is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to `false`. -This value will only be used if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines) +This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines) is enabled. -When enabled, a pipeline on the same branch will be canceled when: +When enabled, a pipeline on the same branch is canceled when: - It's made redundant by a newer pipeline run. - Either all jobs are set as interruptible, or any uninterruptible jobs haven't started. -Pending jobs are always considered interruptible. - -TIP: **Tip:** Set jobs as interruptible that can be safely canceled once started (for instance, a build job). +Pending jobs are always considered interruptible. + Here is a simple example: ```yaml @@ -3806,17 +3827,16 @@ step-2: step-3: stage: stage3 script: - - echo "Because step-2 can not be canceled, this step will never be canceled, even though set as interruptible." + - echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible." interruptible: true ``` -In the example above, a new pipeline run will cause an existing running pipeline to be: +In the example above, a new pipeline run causes an existing running pipeline to be: - Canceled, if only `step-1` is running or pending. - Not canceled, once `step-2` starts running. -NOTE: **Note:** -Once an uninterruptible job is running, the pipeline will never be canceled, regardless of the final job's state. +When an uninterruptible job is running, the pipeline can never be canceled, regardless of the final job's state. ### `resource_group` @@ -3826,12 +3846,13 @@ Sometimes running multiple jobs or pipelines at the same time in an environment can lead to errors during the deployment. To avoid these errors, the `resource_group` attribute can be used to ensure that -the runner doesn't run certain jobs simultaneously. +the runner doesn't run certain jobs simultaneously. Resource groups behave similar +to semaphores in other programming languages. When the `resource_group` key is defined for a job in `.gitlab-ci.yml`, job executions are mutually exclusive across different pipelines for the same project. If multiple jobs belonging to the same resource group are enqueued simultaneously, -only one of the jobs is picked by the runner, and the other jobs wait until the +only one of the jobs is picked by the runner. The other jobs wait until the `resource_group` is free. Here is a simple example: @@ -3842,17 +3863,14 @@ deploy-to-production: resource_group: production ``` -In this case, if a `deploy-to-production` job is running in a pipeline, and a new -`deploy-to-production` job is created in a different pipeline, it won't run until -the currently running/pending `deploy-to-production` job is finished. As a result, -you can ensure that concurrent deployments will never happen to the production environment. +In this case, two `deploy-to-production` jobs in two separate pipelines can never run at the same time. As a result, +you can ensure that concurrent deployments never happen to the production environment. There can be multiple `resource_group`s defined per environment. A good use case for this -is when deploying to physical devices. You may have more than one physical device, and each -one can be deployed to, but there can be only one deployment per device at any given time. +is when deploying to physical devices. You may have multiple physical devices that +can be deployed to, but there can be only one deployment per device at any given time. -NOTE: **Note:** -This key can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces. +The `resource_group` value can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces. It can't start or end with `/`. For more information, see [Deployments Safety](../environments/deployment_safety.md). @@ -3962,7 +3980,11 @@ The title of each milestone the release is associated with. #### `release:released_at` The date and time when the release is ready. Defaults to the current date and time if not -defined. Expected in ISO 8601 format (2019-03-15T08:00:00Z). +defined. Should be enclosed in quotes and expressed in ISO 8601 format. + +```json +released_at: '2021-03-15T08:00:00Z' +``` #### Complete example for `release` @@ -3990,7 +4012,7 @@ tags. These options cannot be used together, so choose one: - 'm1' - 'm2' - 'm3' - released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined, or can use a variable. + released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. ``` - To create a release automatically when commits are pushed or merged to the default branch, @@ -4036,9 +4058,14 @@ tags. These options cannot be used together, so choose one: - 'm1' - 'm2' - 'm3' - released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined, or can use a variable. + released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. ``` +#### Release assets as Generic packages + +You can use [Generic packages](../../user/packages/generic_packages/) to host your release assets. +For a complete example of how to do this, see the [example in the repository](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/). + #### `releaser-cli` command line The entries under the `:release` node are transformed into a `bash` command line and sent @@ -4056,14 +4083,16 @@ release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33014) in GitLab 13.4. `secrets` indicates the [CI Secrets](../secrets/index.md) this job needs. It should be a hash, -and the keys should be the names of the environment variables the job needs to access the secrets. +and the keys should be the names of the environment variables that are made available to the job. +The value of each secret is saved in a temporary file. This file's path is stored in these +environment variables. #### `secrets:vault` **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4. `vault` keyword specifies secrets provided by [Hashicorp's Vault](https://www.vaultproject.io/). -This syntax has multiple forms. The shortest form asssumes the use of the +This syntax has multiple forms. The shortest form assumes the use of the [KV-V2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) secrets engine, mounted at the default path `kv-v2`. The last part of the secret's path is the field to fetch the value for: @@ -4072,7 +4101,7 @@ field to fetch the value for: job: secrets: DATABASE_PASSWORD: - vault: production/db/password # translates to secret `kv-v2/data/production/db`, field `password` + vault: production/db/password # translates to secret `kv-v2/data/production/db`, field `password` ``` You can specify a custom secrets engine path by adding a suffix starting with `@`: @@ -4081,7 +4110,7 @@ You can specify a custom secrets engine path by adding a suffix starting with `@ job: secrets: DATABASE_PASSWORD: - vault: production/db/password@ops # translates to secret `ops/data/production/db`, field `password` + vault: production/db/password@ops # translates to secret `ops/data/production/db`, field `password` ``` In the detailed form of the syntax, you can specify all details explicitly: @@ -4131,34 +4160,40 @@ Read more on [GitLab Pages user documentation](../../user/project/pages/index.md > Introduced in GitLab Runner v0.5.0. -NOTE: **Note:** -Integers (as well as strings) are legal both for variable's name and value. -Floats are not legal and can't be used. +Variables are configurable values that are passed to jobs. They can be set +globally and per-job. + +There are two types of variables. + +- [Custom variables](../variables/README.md#custom-environment-variables): + You can define their values in the `.gitlab-ci.yml` file, in the GitLab UI, + or by using the API. +- [Predefined variables](../variables/predefined_variables.md): + These values are set by the runner itself. + One example is `CI_COMMIT_REF_NAME`, which is the branch or tag the project is built for. -Variables are configurable values in `.gitlab-ci.yml` that are passed to jobs. -They can be set globally and per-job. -When you use the `variables` keyword in jobs, it overrides the global -YAML variables and predefined ones of the same name. +After you define a variable, you can use it in all executed commands and scripts. -Variables are stored in the Git repository and are meant for non-sensitive -project configuration, for example: +Variables are meant for non-sensitive project configuration, for example: ```yaml variables: DATABASE_URL: "postgres://postgres@postgres/my_database" ``` -You can use these variables later in all executed commands and scripts. -The YAML-defined variables are also set to all created service containers, -so that you can fine tune them. +You can use integers and strings for the variable's name and value. +You cannot use floats. + +If you define a variable at the top level of the `gitlab-ci.yml` file, it is global, +meaning it applies to all jobs. + +If you define a variable within a job, it's available to that job only. -Except for the user-defined variables, there are also variables [set up by the -runner itself](../variables/README.md#predefined-environment-variables). -One example would be `CI_COMMIT_REF_NAME`, which has the value of -the branch or tag name the project is built for. Apart from the variables -you can set in `.gitlab-ci.yml`, there are also environment -[variables](../variables/README.md#gitlab-cicd-environment-variables), -which can be set in the GitLab UI. +If a variable of the same name is defined globally and for a specific job, the +[job-specific variable is used](../variables/README.md#priority-of-environment-variables). + +All YAML-defined variables are also set to any linked +[service containers](../docker/using_docker_images.md#what-is-a-service). [YAML anchors for variables](#yaml-anchors-for-variables) are available. @@ -4169,12 +4204,9 @@ Learn more about [variables and their priority](../variables/README.md). > - Introduced in GitLab 8.9 as an experimental feature. > - `GIT_STRATEGY=none` requires GitLab Runner v1.7+. -CAUTION: **Caution:** -May change or be removed completely in future releases. - You can set the `GIT_STRATEGY` used for getting recent application code, either globally or per-job in the [`variables`](#variables) section. If left -unspecified, the default from project settings will be used. +unspecified, the default from the project settings is used. There are three possible values: `clone`, `fetch`, and `none`. @@ -4195,10 +4227,11 @@ variables: GIT_STRATEGY: fetch ``` -`none` also re-uses the local working copy, but skips all Git operations -(including GitLab Runner's pre-clone script, if present). It's mostly useful -for jobs that operate exclusively on artifacts (for example, `deploy`). Git repository -data may be present, but it's certain to be out of date, so you should only +`none` also re-uses the local working copy. However, it skips all Git operations, +including GitLab Runner's pre-clone script, if present. + +It's useful for jobs that operate exclusively on artifacts, like a deployment job. +Git repository data may be present, but it's likely out-of-date. You should only rely on files brought into the local working copy from cache or artifacts. ```yaml @@ -4222,10 +4255,10 @@ globally or per-job in the [`variables`](#variables) section. There are three possible values: `none`, `normal`, and `recursive`: -- `none` means that submodules won't be included when fetching the project +- `none` means that submodules are not included when fetching the project code. This is the default, which matches the pre-v1.10 behavior. -- `normal` means that only the top-level submodules will be included. It's +- `normal` means that only the top-level submodules are included. It's equivalent to: ```shell @@ -4234,7 +4267,7 @@ There are three possible values: `none`, `normal`, and `recursive`: ``` - `recursive` means that all submodules (including submodules of submodules) - will be included. This feature needs Git v1.8.1 and later. When using a + are included. This feature needs Git v1.8.1 and later. When using a GitLab Runner with an executor not based on Docker, make sure the Git version meets that requirement. It's equivalent to: @@ -4243,7 +4276,7 @@ There are three possible values: `none`, `normal`, and `recursive`: git submodule update --init --recursive ``` -Note that for this feature to work correctly, the submodules must be configured +For this feature to work correctly, the submodules must be configured (in `.gitmodules`) with either: - the HTTP(S) URL of a publicly-accessible repository, or @@ -4259,15 +4292,15 @@ The `GIT_CHECKOUT` variable can be used when the `GIT_STRATEGY` is set to either specified, it defaults to true. You can set them globally or per-job in the [`variables`](#variables) section. -If set to `false`, the runner will: +If set to `false`, the runner: -- when doing `fetch` - update the repository and leave working copy on +- when doing `fetch` - updates the repository and leaves the working copy on the current revision, -- when doing `clone` - clone the repository and leave working copy on the +- when doing `clone` - clones the repository and leaves the working copy on the default branch. -Having this setting set to `true` will mean that for both `clone` and `fetch` -strategies the runner will checkout the working copy to a revision related +If `GIT_CHECKOUT` is set to `true`, both `clone` and `fetch` work the same way. +The runner checks out the working copy of a revision related to the CI pipeline: ```yaml @@ -4313,7 +4346,7 @@ script: The `GIT_FETCH_EXTRA_FLAGS` variable is used to control the behavior of `git fetch`. You can set it globally or per-job in the [`variables`](#variables) section. -`GIT_FETCH_EXTRA_FLAGS` accepts all possible options of the [`git fetch`](https://git-scm.com/docs/git-fetch) command, but please note that `GIT_FETCH_EXTRA_FLAGS` flags will be appended after the default flags that can't be modified. +`GIT_FETCH_EXTRA_FLAGS` accepts all options of the [`git fetch`](https://git-scm.com/docs/git-fetch) command. However, `GIT_FETCH_EXTRA_FLAGS` flags are appended after the default flags that can't be modified. The default flags are: @@ -4335,7 +4368,7 @@ script: - ls -al cache/ ``` -The configuration above will result in `git fetch` being called this way: +The configuration above results in `git fetch` being called this way: ```shell git fetch origin $REFSPECS --depth 50 --prune @@ -4347,13 +4380,13 @@ Where `$REFSPECS` is a value provided to the runner internally by GitLab. > Introduced in GitLab, it requires GitLab Runner v1.9+. -You can set the number for attempts the running job will try to execute each -of the following stages: +You can set the number of attempts that the running job tries to execute +the following stages: | Variable | Description | |-----------------------------------|--------------------------------------------------------| | **ARTIFACT_DOWNLOAD_ATTEMPTS** | Number of attempts to download artifacts running a job | -| **EXECUTOR_JOB_SECTION_ATTEMPTS** | [Since GitLab 12.10](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450), the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). | +| **EXECUTOR_JOB_SECTION_ATTEMPTS** | [In GitLab 12.10](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) and later, the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). | | **GET_SOURCES_ATTEMPTS** | Number of attempts to fetch sources running a job | | **RESTORE_CACHE_ATTEMPTS** | Number of attempts to restore the cache running a job | @@ -4368,27 +4401,52 @@ variables: You can set them globally or per-job in the [`variables`](#variables) section. +### Fallback cache key + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4. + +You can use the `$CI_COMMIT_REF_SLUG` variable to specify your [`cache:key`](#cachekey). +For example, if your `$CI_COMMIT_REF_SLUG` is `test` you can set a job +to download cache that's tagged with `test`. + +If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to +specify a cache to use when none exists. + +For example: + +```yaml +variables: + CACHE_FALLBACK_KEY: fallback-key + +cache: + key: "$CI_COMMIT_REF_SLUG" + paths: + - binaries/ +``` + +In this example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined +by the `CACHE_FALLBACK_KEY` variable. + ### Shallow cloning > Introduced in GitLab 8.9 as an experimental feature. -NOTE: **Note:** -As of GitLab 12.0, newly created projects will automatically have a [default `git depth` value of `50`](../pipelines/settings.md#git-shallow-clone). - -You can specify the depth of fetching and cloning using `GIT_DEPTH`. This does a -shallow clone of the repository and can significantly speed up cloning for -repositories with a large number of commits or old, large binaries. The value is +You can specify the depth of fetching and cloning using `GIT_DEPTH`. +`GIT_DEPTH` does a shallow clone of the repository and can significantly speed up cloning. +It can be helpful for repositories with a large number of commits or old, large binaries. The value is passed to `git fetch` and `git clone`. -NOTE: **Note:** -If you use a depth of 1 and have a queue of jobs or retry +In GitLab 12.0 and later, newly-created projects automatically have a +[default `git depth` value of `50`](../pipelines/settings.md#git-shallow-clone). + +If you use a depth of `1` and have a queue of jobs or retry jobs, jobs may fail. -Since Git fetching and cloning is based on a ref, such as a branch name, runners -can't clone a specific commit SHA. If there are multiple jobs in the queue, or -you're retrying an old job, the commit to be tested needs to be within the +Git fetching and cloning is based on a ref, such as a branch name, so runners +can't clone a specific commit SHA. If multiple jobs are in the queue, or +you're retrying an old job, the commit to be tested must be within the Git history that is cloned. Setting too small a value for `GIT_DEPTH` can make -it impossible to run these old commits. You will see `unresolved reference` in +it impossible to run these old commits and `unresolved reference` is displayed in job logs. You should then reconsider changing `GIT_DEPTH` to a higher value. Jobs that rely on `git describe` may not work correctly when `GIT_DEPTH` is @@ -4407,11 +4465,6 @@ You can set it globally or per-job in the [`variables`](#variables) section. > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2211) in GitLab Runner 11.10. -NOTE: **Note:** -This can only be used when `custom_build_dir` is enabled in the [runner's -configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section). -This is the default configuration for `docker` and `kubernetes` executor. - By default, GitLab Runner clones the repository in a unique subpath of the `$CI_BUILDS_DIR` directory. However, your project might require the code in a specific directory (Go projects, for example). In that case, you can specify @@ -4431,12 +4484,17 @@ The `GIT_CLONE_PATH` has to always be within `$CI_BUILDS_DIR`. The directory set is dependent on executor and configuration of [runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) setting. +This can only be used when `custom_build_dir` is enabled in the +[runner's configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section). +This is the default configuration for the `docker` and `kubernetes` executors. + #### Handling concurrency -An executor using a concurrency greater than `1` might lead -to failures because multiple jobs might be working on the same directory if the `builds_dir` +An executor that uses a concurrency greater than `1` might lead +to failures. Multiple jobs might be working on the same directory if the `builds_dir` is shared between jobs. -GitLab Runner does not try to prevent this situation. It's up to the administrator + +The runner does not try to prevent this situation. It's up to the administrator and developers to comply with the requirements of runner configuration. To avoid this scenario, you can use a unique path within `$CI_BUILDS_DIR`, because runner @@ -4503,15 +4561,20 @@ need to be used to merge arrays. > Introduced in GitLab 8.6 and GitLab Runner v1.1.1. -YAML has a handy feature called 'anchors', which lets you easily duplicate -content across your document. Anchors can be used to duplicate/inherit -properties, and is a perfect example to be used with [hidden jobs](#hide-jobs) -to provide templates for your jobs. When there is duplicate keys, GitLab will -perform a reverse deep merge based on the keys. +YAML has a feature called 'anchors' that you can use to duplicate +content across your document. + +Use anchors to duplicate or inherit properties. Use anchors with [hidden jobs](#hide-jobs) +to provide templates for your jobs. When there are duplicate keys, GitLab +performs a reverse deep merge based on the keys. + +You can't use YAML anchors across multiple files when leveraging the [`include`](#include) +feature. Anchors are only valid within the file they were defined in. Instead +of using YAML anchors, you can use the [`extends` keyword](#extends). -The following example uses anchors and map merging. It will create two jobs, -`test1` and `test2`, that will inherit the parameters of `.job_template`, each -having their own custom `script` defined: +The following example uses anchors and map merging. It creates two jobs, +`test1` and `test2`, that inherit the parameters of `.job_template`, each +with their own custom `script` defined: ```yaml .job_template: &job_definition # Hidden key that defines an anchor named 'job_definition' @@ -4559,9 +4622,9 @@ test2: - test2 project ``` -Let's see another one example. This time we will use anchors to define two sets -of services. This will create two jobs, `test:postgres` and `test:mysql`, that -will share the `script` directive defined in `.job_template`, and the `services` +Let's see another example. This time we use anchors to define two sets +of services. This configuration creates two jobs, `test:postgres` and `test:mysql`, that +share the `script` directive defined in `.job_template`, and the `services` directive defined in `.postgres_services` and `.mysql_services` respectively: ```yaml @@ -4630,15 +4693,8 @@ test:mysql: - dev ``` -You can see that the hidden jobs are conveniently used as templates. - -NOTE: **Note:** -Note that `tags: [dev]` has been overwritten by `tags: [postgres]`. - -NOTE: **Note:** -You can't use YAML anchors across multiple files when leveraging the [`include`](#include) -feature. Anchors are only valid within the file they were defined in. Instead -of using YAML anchors, you can use the [`extends` keyword](#extends). +You can see that the hidden jobs are conveniently used as templates, and +`tags: [dev]` has been overwritten by `tags: [postgres]`. #### YAML anchors for `before_script` and `after_script` @@ -4692,7 +4748,7 @@ job_name: of variables across multiple jobs. It can also enable more flexibility when a job requires a specific `variables` block that would otherwise override the global variables. -In the example below, we will override the `GIT_STRATEGY` variable without affecting +In the example below, we override the `GIT_STRATEGY` variable without affecting the use of the `SAMPLE_VARIABLE` variable: ```yaml @@ -4701,7 +4757,7 @@ variables: &global-variables SAMPLE_VARIABLE: sample_variable_value ANOTHER_SAMPLE_VARIABLE: another_sample_variable_value -# a job that needs to set the GIT_STRATEGY variable, yet depend on global variables +# a job that must set the GIT_STRATEGY variable, yet depend on global variables job_no_git_strategy: stage: cleanup variables: @@ -4723,8 +4779,8 @@ lines where the job is defined: # - run test ``` -You can instead start its name with a dot (`.`) and it won't be processed by -GitLab CI/CD. In the following example, `.hidden_job` will be ignored: +Instead, you can start its name with a dot (`.`) and it is not processed by +GitLab CI/CD. In the following example, `.hidden_job` is ignored: ```yaml .hidden_job: @@ -4739,18 +4795,18 @@ into templates. ## Skip Pipeline If your commit message contains `[ci skip]` or `[skip ci]`, using any -capitalization, the commit will be created but the pipeline will be skipped. +capitalization, the commit is created but the pipeline is skipped. Alternatively, one can pass the `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd) if using Git 2.10 or newer. ## Processing Git pushes -GitLab will create at most 4 branch and tag pipelines when -pushing multiple changes in single `git push` invocation. +GitLab creates at most four branch and tag pipelines when +pushing multiple changes in a single `git push` invocation. -This limitation does not affect any of the updated Merge Request pipelines. -All updated Merge Requests will have a pipeline created when using +This limitation does not affect any of the updated merge request pipelines. +All updated merge requests have a pipeline created when using [pipelines for merge requests](../merge_request_pipelines/index.md). ## Deprecated parameters diff --git a/doc/ci/yaml/img/ci_config_visualization_hover_v13_5.png b/doc/ci/yaml/img/ci_config_visualization_hover_v13_5.png new file mode 100644 index 00000000000..e6c85bd39e4 Binary files /dev/null and b/doc/ci/yaml/img/ci_config_visualization_hover_v13_5.png differ diff --git a/doc/ci/yaml/img/ci_config_visualization_v13_5.png b/doc/ci/yaml/img/ci_config_visualization_v13_5.png new file mode 100644 index 00000000000..0aee5cff7be Binary files /dev/null and b/doc/ci/yaml/img/ci_config_visualization_v13_5.png differ diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index f7ed7248dc4..d7945617dc9 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -73,10 +73,11 @@ automatically fetched and evaluated along with the content of `.gitlab-ci.yml`. Content of `https://gitlab.com/awesome-project/raw/master/.before-script-template.yml`: ```yaml -before_script: - - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs - - gem install bundler --no-document - - bundle install --jobs $(nproc) "${FLAGS[@]}" +default: + before_script: + - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs + - gem install bundler --no-document + - bundle install --jobs $(nproc) "${FLAGS[@]}" ``` Content of `.gitlab-ci.yml`: diff --git a/doc/ci/yaml/visualization.md b/doc/ci/yaml/visualization.md new file mode 100644 index 00000000000..ac5f5c8fd14 --- /dev/null +++ b/doc/ci/yaml/visualization.md @@ -0,0 +1,46 @@ +# Visualize your CI/CD configuration + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241722) in GitLab 13.5. +> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cicd-configuration-visualization). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +To see a visualization of your `gitlab-ci.yml` configuration, navigate to any CI/CD +configuration file and click on the `Visualization` tab. The visualization shows +all stages and jobs. [`needs`](README.md#needs) relationships are displayed as lines +connecting jobs together, showing the hierarchy of execution: + +![CI Config Visualization](img/ci_config_visualization_v13_5.png) + +Hovering on a job highlights its `needs` relationships: + +![CI Config Visualization on hover](img/ci_config_visualization_hover_v13_5.png) + +If the configuration does not have any `needs` relationships, then no lines are drawn because +each job depends only on the previous stage being completed successfully. + +You can only preview one `gitlab-ci.yml` file at a time. Configuration imported with +[`includes`](README.md#include) is ignored and not included in the visualization. + +## Enable or disable CI/CD configuration visualization **(CORE ONLY)** + +CI/CD configuration visualization 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(:gitlab_ci_yml_preview) +``` + +To disable it: + +```ruby +Feature.disable(:gitlab_ci_yml_preview) +``` diff --git a/doc/container_registry/README.md b/doc/container_registry/README.md deleted file mode 100644 index b98d1b51999..00000000000 --- a/doc/container_registry/README.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../user/packages/container_registry/index.md' ---- - -This document was moved to [another location](../user/packages/container_registry/index.md). diff --git a/doc/container_registry/troubleshooting.md b/doc/container_registry/troubleshooting.md deleted file mode 100644 index 092d7831e35..00000000000 --- a/doc/container_registry/troubleshooting.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -redirect_to: '../user/packages/container_registry/index.md#troubleshooting-the-gitlab-container-registry' ---- - -This document was moved to [user/project/container_registry](../user/packages/container_registry/index.md#troubleshooting-the-gitlab-container-registry). diff --git a/doc/customization/welcome_message.md b/doc/customization/welcome_message.md index 45f1fed355e..9667e5e380a 100644 --- a/doc/customization/welcome_message.md +++ b/doc/customization/welcome_message.md @@ -1,5 +1,5 @@ --- -redirect_to: 'branded_login_page.md' +redirect_to: '../user/admin_area/appearance.md#sign-in--sign-up-pages' --- -This document was moved to [another location](branded_login_page.md). +This document was moved to [another location](../user/admin_area/appearance.md#sign-in--sign-up-pages). diff --git a/doc/development/README.md b/doc/development/README.md index abdd5c662f3..7b8a5cd5f75 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -43,6 +43,7 @@ For information on how to install, configure, update, and upgrade your own GitLa **Must-reads:** +- [Guide on adapting existing and introducing new components](architecture.md#adapting-existing-and-introducing-new-components) - [Code review guidelines](code_review.md) for reviewing code and having code reviewed - [Database review guidelines](database_review.md) for reviewing database-related changes and complex SQL queries, and having them reviewed - [Secure coding guidelines](secure_coding_guidelines.md) @@ -115,6 +116,7 @@ Complementary reads: - [Code Intelligence](code_intelligence/index.md) - [Approval Rules](approval_rules.md) - [Feature categorization](feature_categorization/index.md) +- [Wikis development guide](wikis.md) ## Performance guides @@ -163,11 +165,11 @@ See [database guidelines](database/index.md). - [Externalization](i18n/externalization.md) - [Translation](i18n/translation.md) -## Telemetry guides +## Product Analytics guides -- [Telemetry guide](telemetry/index.md) -- [Usage Ping guide](telemetry/usage_ping.md) -- [Snowplow guide](telemetry/snowplow.md) +- [Product Analytics guide](product_analytics/index.md) +- [Usage Ping guide](product_analytics/usage_ping.md) +- [Snowplow guide](product_analytics/snowplow.md) ## Experiment guide diff --git a/doc/development/adding_database_indexes.md b/doc/development/adding_database_indexes.md index 03557491e68..d2526d6c4f2 100644 --- a/doc/development/adding_database_indexes.md +++ b/doc/development/adding_database_indexes.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Adding Database Indexes Indexes can be used to speed up database queries, but when should you add a new diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index 2801e27145d..bb5af286c1d 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.md @@ -46,7 +46,7 @@ TIP: **Tip:** **For services that depend on the existing GitLab codebase:** -The first iteration should be opt-in, either through the `gitlab.yml` configuration or through [feature flags](feature_flags.md). For these types of services it is often necessary to [bundle the service and its dependencies with GitLab](#bundling-a-service-with-gitlab) as part of the initial integration. +The first iteration should be opt-in, either through the `gitlab.yml` configuration or through [feature flags](feature_flags/index.md). For these types of services it is often necessary to [bundle the service and its dependencies with GitLab](#bundling-a-service-with-gitlab) as part of the initial integration. TIP: **Tip:** [ActionCable](https://docs.gitlab.com/omnibus/settings/actioncable.html) is an example of a service that has been added this way. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 18fc0fb7d33..3d4c033e676 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -49,6 +49,20 @@ See also: - [Exposing Global IDs](#exposing-global-ids). - [Mutation arguments](#object-identifier-arguments). +We have a custom scalar type (`Types::GlobalIDType`) which should be used as the +type of input and output arguments when the value is a `GlobalID`. The benefits +of using this type instead of `ID` are: + +- it validates that the value is a `GlobalID` +- it parses it into a `GlobalID` before passing it to user code +- it can be parameterized on the type of the object (e.g. + `GlobalIDType[Project]`) which offers even better validation and security. + +Consider using this type for all new arguments and result types. Remember that +it is perfectly possible to parameterize this type with a concern or a +supertype, if you want to accept a wider range of objects (e.g. +`GlobalIDType[Issuable]` vs `GlobalIDType[Issue]`). + ## Types We use a code-first schema, and we declare what type everything is in Ruby. @@ -371,8 +385,8 @@ end GitLab's GraphQL API is versionless, which means we maintain backwards compatibility with older versions of the API with every change. Rather than removing a field or [enum value](#enums), we need to _deprecate_ it instead. -In future, GitLab -[may remove deprecated parts of the schema](https://gitlab.com/gitlab-org/gitlab/-/issues/32292). +The deprecated parts of the schema can then be removed in a future release +in accordance with [GitLab's deprecation process](../api/graphql/index.md#deprecation-process). Fields and enum values are deprecated using the `deprecated` property. The value of the property is a `Hash` of: @@ -472,6 +486,28 @@ end Enum values can be deprecated using the [`deprecated` keyword](#deprecating-fields-and-enum-values). +### Defining GraphQL enums dynamically from Rails enums + +If your GraphQL enum is backed by a [Rails enum](creating_enums.md), then consider +using the Rails enum to dynamically define the GraphQL enum values. Doing so +binds the GraphQL enum values to the Rails enum definition, so if values are +ever added to the Rails enum then the GraphQL enum automatically reflects the change. + +Example: + +```ruby +module Types + class IssuableSeverityEnum < BaseEnum + graphql_name 'IssuableSeverity' + description 'Incident severity' + + ::IssuableSeverity.severities.keys.each do |severity| + value severity.upcase, value: severity, description: "#{severity.titleize} severity" + end + end +end +``` + ## JSON When data to be returned by GraphQL is stored as @@ -780,6 +816,25 @@ to advertise the need for lookahead: For an example of real world use, please see [`ResolvesMergeRequests`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/concerns/resolves_merge_requests.rb). +### Negated arguments + +Negated filters can filter some resources (for example, find all issues that +have the `bug` label, but don't have the `bug2` label assigned). The `not` +argument is the preferred syntax to pass negated arguments: + +```graphql +issues(labelName: "bug", not: {labelName: "bug2"}) { + nodes { + id + title + } +} +``` + +To avoid duplicated argument definitions, you can place these arguments in a reusable module (or +class, if the arguments are nested). Alternatively, you can consider to add a +[helper resolver method](https://gitlab.com/gitlab-org/gitlab/-/issues/258969). + ## Pass a parent object into a child Presenter Sometimes you need to access the resolved query parent in a child context to compute fields. Usually the parent is only @@ -827,10 +882,39 @@ mutation. ### Building Mutations -Mutations live in `app/graphql/mutations` ideally grouped per +Mutations are stored in `app/graphql/mutations`, ideally grouped per resources they are mutating, similar to our services. They should inherit `Mutations::BaseMutation`. The fields defined on the mutation -will be returned as the result of the mutation. +are returned as the result of the mutation. + +#### Update mutation granularity + +GitLab's service-oriented architecture means that most mutations call a Create, Delete, or Update +service, for example `UpdateMergeRequestService`. +For Update mutations, a you might want to only update one aspect of an object, and thus only need a +_fine-grained_ mutation, for example `MergeRequest::SetWip`. + +It's acceptable to have both fine-grained mutations and coarse-grained mutations, but be aware +that too many fine-grained mutations can lead to organizational challenges in maintainability, code +comprehensibility, and testing. +Each mutation requires a new class, which can lead to technical debt. +It also means the schema becomes very big, and we want users to easily navigate our schema. +As each new mutation also needs tests (including slower request integration tests), adding mutations +slows down the test suite. + +To minimize changes: + +- Use existing mutations, such as `MergeRequest::Update`, when available. +- Expose existing services as a coarse-grained mutation. + +When a fine-grained mutation might be more appropriate: + +- Modifying a property that requires specific permissions or other specialized logic. +- Exposing a state-machine-like transition (locking issues, merging MRs, closing epics, etc). +- Accepting nested properties (where we accept properties for a child object). +- The semantics of the mutation can be expressed clearly and concisely. + +See [issue #233063](https://gitlab.com/gitlab-org/gitlab/-/issues/233063) for further context. ### Naming conventions @@ -1361,5 +1445,4 @@ For information on generating GraphQL documentation and schema files, see [updating the schema documentation](rake_tasks.md#update-graphql-documentation-and-schema-definitions). To help our readers, you should also add a new page to our [GraphQL API](../api/graphql/index.md) documentation. -For guidance, see the [GraphQL API](documentation/styleguide.md#graphql-api) section -of our documentation style guide. +For guidance, see the [GraphQL API](documentation/graphql_styleguide.md) page. diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 400752c69e9..47c06377d88 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -17,7 +17,7 @@ Each new or updated API endpoint must come with documentation, unless it is inte The docs should be in the same merge request, or, if strictly necessary, in a follow-up with the same milestone as the original merge request. -See the [Documentation Style Guide RESTful API section](documentation/styleguide.md#restful-api) for details on documenting API resources in Markdown as well as in OpenAPI definition files. +See the [Documentation Style Guide RESTful API page](documentation/restful_api_styleguide.md) for details on documenting API resources in Markdown as well as in OpenAPI definition files. ## Methods and parameters description diff --git a/doc/development/architecture.md b/doc/development/architecture.md index f6b1c8cd914..513af491576 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -1,32 +1,91 @@ -# GitLab Architecture Overview +# GitLab architecture overview ## Software delivery -There are two software distributions of GitLab: the open source [Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/) (CE), and the open core [Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/) (EE). GitLab is available under [different subscriptions](https://about.gitlab.com/pricing/). +There are two software distributions of GitLab: -New versions of GitLab are released in stable branches and the master branch is for bleeding edge development. +- The open source [Community Edition](https://gitlab.com/gitlab-org/gitlab-foss/) (CE). +- The open core [Enterprise Edition](https://gitlab.com/gitlab-org/gitlab/) (EE). -For information, see the [GitLab Release Process](https://gitlab.com/gitlab-org/release/docs/-/tree/master#gitlab-release-process). +GitLab is available under [different subscriptions](https://about.gitlab.com/pricing/). -Both EE and CE require some add-on components called GitLab Shell and Gitaly. These components are available from the [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell/-/tree/master) and [Gitaly](https://gitlab.com/gitlab-org/gitaly/-/tree/master) repositories respectively. New versions are usually tags but staying on the master branch will give you the latest stable version. New releases are generally around the same time as GitLab CE releases with the exception of informal security updates deemed critical. +New versions of GitLab are released from stable branches, and the `master` branch is used for +bleeding-edge development. + +For more information, visit the [GitLab Release Process](https://about.gitlab.com/handbook/engineering/releases/). + +Both distributions require additional components. These components are described in the +[Component details](#components) section, and all have their own repositories. +New versions of each dependent component are usually tags, but staying on the `master` branch of the +GitLab codebase gives you the latest stable version of those components. New versions are +generally released around the same time as GitLab releases, with the exception of informal security +updates deemed critical. ## Components -A typical install of GitLab will be on GNU/Linux. It uses NGINX or Apache as a web front end to proxypass the Unicorn web server. By default, communication between Unicorn and the front end is via a Unix domain socket but forwarding requests via TCP is also supported. The web front end accesses `/home/git/gitlab/public` bypassing the Unicorn server to serve static pages, uploads (e.g. avatar images or attachments), and pre-compiled assets. GitLab serves web pages and the [GitLab API](../api/README.md) using the Unicorn web server. It uses Sidekiq as a job queue which, in turn, uses Redis as a non-persistent database backend for job information, meta data, and incoming jobs. +A typical install of GitLab is on GNU/Linux, but growing number of deployments also use the +Kubernetes platform. The largest known GitLab instance is on GitLab.com, which is deployed using our +[official GitLab Helm chart](https://docs.gitlab.com/charts/) and the [official Linux package](https://about.gitlab.com/install/). -We also support deploying GitLab on Kubernetes using our [GitLab Helm chart](https://docs.gitlab.com/charts/). +A typical installation uses NGINX or Apache as a web server to proxy through +[GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) and into the [Puma](https://puma.io) +application server. GitLab serves web pages and the [GitLab API](../api/README.md) using the Puma +application server. It uses Sidekiq as a job queue which, in turn, uses Redis as a non-persistent +database backend for job information, metadata, and incoming jobs. -The GitLab web app uses PostgreSQL for persistent database information (e.g. users, permissions, issues, other meta data). GitLab stores the bare Git repositories it serves in `/home/git/repositories` by default. It also keeps default branch and hook information with the bare repository. +By default, communication between Puma and Workhorse is via a Unix domain socket, but forwarding +requests via TCP is also supported. Workhorse accesses the `gitlab/public` directory, bypassing the +Puma application server to serve static pages, uploads (for example, avatar images or attachments), +and pre-compiled assets. -When serving repositories over HTTP/HTTPS GitLab utilizes the GitLab API to resolve authorization and access as well as serving Git objects. +The GitLab application uses PostgreSQL for persistent database information (for example, users, +permissions, issues, or other metadata). GitLab stores the bare Git repositories in the location +defined in [the configuration file, `repositories:` section](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example). +It also keeps default branch and hook information with the bare repository. -The add-on component GitLab Shell serves repositories over SSH. It manages the SSH keys within `/home/git/.ssh/authorized_keys` which should not be manually edited. GitLab Shell accesses the bare repositories through Gitaly to serve Git objects and communicates with Redis to submit jobs to Sidekiq for GitLab to process. GitLab Shell queries the GitLab API to determine authorization and access. +When serving repositories over HTTP/HTTPS GitLab uses the GitLab API to resolve authorization and +access and to serve Git objects. -Gitaly executes Git operations from GitLab Shell and the GitLab web app, and provides an API to the GitLab web app to get attributes from Git (e.g. title, branches, tags, other meta data), and to get blobs (e.g. diffs, commits, files). +The add-on component GitLab Shell serves repositories over SSH. It manages the SSH keys within the +location defined in [the configuration file, `GitLab Shell` section](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example). +The file in that location should never be manually edited. GitLab Shell accesses the bare +repositories through Gitaly to serve Git objects, and communicates with Redis to submit jobs to +Sidekiq for GitLab to process. GitLab Shell queries the GitLab API to determine authorization and access. + +Gitaly executes Git operations from GitLab Shell and the GitLab web app, and provides an API to the +GitLab web app to get attributes from Git (for example, title, branches, tags, or other metadata), +and to get blobs (for example, diffs, commits, or files). You may also be interested in the [production architecture of GitLab.com](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/). -### Simplified Component Overview +## Adapting existing and introducing new components + +There are fundamental differences in how the application behaves when it is installed on a +traditional Linux machine compared to a containerized platform, such as Kubernetes. + +Compared to [our official installation methods](https://about.gitlab.com/install/), some of the +notable differences are: + +- Official Linux packages can access files on the same file system with different services. + [Shared files](shared_files.md) are not an option for the application running on the Kubernetes + platform. +- Official Linux packages by default have services that have access to the shared configuration and + network. This is not the case for services running in Kubernetes, where services might be running + in complete isolation, or only accessible through specific ports. + +In other words, the shared state between services needs to be carefully considered when +architecting new features and adding new components. Services that need to have access to the same +files, need to be able to exchange information through the appropriate APIs. Whenever possible, +this should not be done with files. + +Since components written with the API-first philosophy in mind are compatible with both methods, all +new features and services must be written to consider Kubernetes compatibility **first**. + +The simplest way to ensure this, is to add support for your feature or service to +[the official GitLab Helm chart](https://docs.gitlab.com/charts/) or reach out to +[the Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/#how-to-work-with-distribution). + +### Simplified component overview This is a simplified architecture diagram that can be used to understand GitLab's architecture. @@ -51,23 +110,25 @@ SSH -- TCP 22 --> GitLabShell[GitLab Shell] SMTP[SMTP Gateway] Geo[GitLab Geo Node] -- TCP 22, 80, 443 --> NGINX -GitLabShell --TCP 8080 -->Unicorn["Unicorn (GitLab Rails)"] +GitLabShell --TCP 8080 -->Puma["Puma (GitLab Rails)"] GitLabShell --> Praefect -Unicorn --> PgBouncer[PgBouncer] -Unicorn --> Redis -Unicorn --> Praefect +Puma --> PgBouncer[PgBouncer] +Puma --> Redis +Puma --> Praefect Sidekiq --> Redis Sidekiq --> PgBouncer Sidekiq --> Praefect -GitLabWorkhorse[GitLab Workhorse] --> Unicorn +GitLabWorkhorse[GitLab Workhorse] --> Puma GitLabWorkhorse --> Redis GitLabWorkhorse --> Praefect Praefect --> Gitaly NGINX --> GitLabWorkhorse NGINX -- TCP 8090 --> GitLabPages[GitLab Pages] NGINX --> Grafana[Grafana] +NGINX -- TCP 8150 --> GitLabKas[GitLab Kubernetes Agent Server] +GitLabKas --> Praefect Grafana -- TCP 9090 --> Prometheus[Prometheus] -Prometheus -- TCP 80, 443 --> Unicorn +Prometheus -- TCP 80, 443 --> Puma RedisExporter[Redis Exporter] --> Redis Prometheus -- TCP 9121 --> RedisExporter PostgreSQLExporter[PostgreSQL Exporter] --> PostgreSQL @@ -83,27 +144,27 @@ PgBouncer --> Consul PostgreSQL --> Consul PgBouncer --> PostgreSQL NGINX --> Registry -Unicorn --> Registry +Puma --> Registry NGINX --> Mattermost -Mattermost --- Unicorn +Mattermost --- Puma Prometheus --> Alertmanager Migrations --> PostgreSQL Runner -- TCP 443 --> NGINX -Unicorn -- TCP 9200 --> Elasticsearch +Puma -- TCP 9200 --> Elasticsearch Sidekiq -- TCP 9200 --> Elasticsearch Sidekiq -- TCP 80, 443 --> Sentry -Unicorn -- TCP 80, 443 --> Sentry +Puma -- TCP 80, 443 --> Sentry Sidekiq -- UDP 6831 --> Jaeger -Unicorn -- UDP 6831 --> Jaeger +Puma -- UDP 6831 --> Jaeger Gitaly -- UDP 6831 --> Jaeger GitLabShell -- UDP 6831 --> Jaeger GitLabWorkhorse -- UDP 6831 --> Jaeger Alertmanager -- TCP 25 --> SMTP Sidekiq -- TCP 25 --> SMTP -Unicorn -- TCP 25 --> SMTP -Unicorn -- TCP 369 --> LDAP +Puma -- TCP 25 --> SMTP +Puma -- TCP 369 --> LDAP Sidekiq -- TCP 369 --> LDAP -Unicorn -- TCP 443 --> ObjectStorage["Object Storage"] +Puma -- TCP 443 --> ObjectStorage["Object Storage"] Sidekiq -- TCP 443 --> ObjectStorage GitLabWorkhorse -- TCP 443 --> ObjectStorage Registry -- TCP 443 --> ObjectStorage @@ -121,7 +182,7 @@ click Gitaly "./architecture.html#gitaly" click Jaeger "./architecture.html#jaeger" click GitLabWorkhorse "./architecture.html#gitlab-workhorse" click LDAP "./architecture.html#ldap-authentication" -click Unicorn "./architecture.html#unicorn" +click Puma "./architecture.html#puma" click GitLabShell "./architecture.html#gitlab-shell" click SSH "./architecture.html#ssh-request-22" click Sidekiq "./architecture.html#sidekiq" @@ -175,6 +236,7 @@ Table description links: | [GitLab Geo Node](#gitlab-geo) | Geographically distributed GitLab nodes | ⚙ | ⚙ | ❌ | ✅ | ❌ | ⚙ | EE Only | | [GitLab Managed Apps](#gitlab-managed-apps) | Deploy Helm, Ingress, Cert-Manager, Prometheus, GitLab Runner, JupyterHub, or Knative to a cluster | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | | [GitLab Pages](#gitlab-pages) | Hosts static websites | ⚙ | ❌ | ❌ | ✅ | ⚙ | ⚙ | CE & EE | +| [GitLab Kubernetes Agent](#gitlab-kubernetes-agent) | Integrate Kubernetes clusters in a cloud-native way | ⚙ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | EE Only | | [GitLab self-monitoring: Alertmanager](#alertmanager) | Deduplicates, groups, and routes alerts from Prometheus | ⚙ | ✅ | ⚙ | ✅ | ❌ | ❌ | CE & EE | | [GitLab self-monitoring: Grafana](#grafana) | Metrics dashboard | ✅ | ⚙ | ⤓ | ✅ | ❌ | ❌ | CE & EE | | [GitLab self-monitoring: Jaeger](#jaeger) | View traces generated by the GitLab instance | ❌ | ⚙ | ❌ | ❌ | ⤓ | ⚙ | CE & EE | @@ -201,7 +263,7 @@ Table description links: | [Runner](#gitlab-runner) | Executes GitLab CI/CD jobs | ⤓ | ✅ | ⚙ | ✅ | ⚙ | ⚙ | CE & EE | | [Sentry integration](#sentry) | Error tracking for deployed apps | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | ⤓ | CE & EE | | [Sidekiq](#sidekiq) | Background jobs processor | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | CE & EE | -| [Unicorn (GitLab Rails)](#unicorn) | Handles requests for the web interface and API | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | +| [Puma (GitLab Rails)](#puma) | Handles requests for the web interface and API | ✅ | ✅ | ✅ | ✅ | ⚙ | ✅ | CE & EE | ### Component details @@ -271,7 +333,7 @@ Consul is a tool for service discovery and configuration. Consul is distributed, - [Source](../integration/elasticsearch.md) - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/elasticsearch.md) - Layer: Core Service (Data) -- GitLab.com: [Get Advanced Global Search working on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/153) epic. +- GitLab.com: [Get Advanced Search working on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/153) epic. Elasticsearch is a distributed RESTful search engine built for the cloud. @@ -321,6 +383,19 @@ repository updates to secondary nodes. GitLab Exporter is a process designed in house that allows us to export metrics about GitLab application internals to Prometheus. You can read more [in the project's README](https://gitlab.com/gitlab-org/gitlab-exporter). +#### GitLab Kubernetes Agent + +- [Project page](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) +- Configuration: + - [Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template) + - [Charts](https://docs.gitlab.com/charts/charts/gitlab/kas/index.html) + +[GitLab Kubernetes Agent](../user/clusters/agent/index.md) is an active in-cluster +component for solving GitLab and Kubernetes integration tasks in a secure and +cloud-native way. + +You can use it to sync deployments onto your Kubernetes cluster. + #### GitLab Pages - Configuration: @@ -368,13 +443,13 @@ GitLab CI/CD is the open-source continuous integration service included with Git - [Project page](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/README.md) - Configuration: - [Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template) - - [Charts](https://docs.gitlab.com/charts/charts/gitlab/unicorn/) + - [Charts](https://docs.gitlab.com/charts/charts/gitlab/webservice/) - [Source](../install/installation.md#install-gitlab-workhorse) - Layer: Core Service (Processor) - Process: `gitlab-workhorse` - GitLab.com: [Service Architecture](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/#service-architecture) -[GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) is a program designed at GitLab to help alleviate pressure from Unicorn. You can read more about the [historical reasons for developing](https://about.gitlab.com/blog/2016/04/12/a-brief-history-of-gitlab-workhorse/). It's designed to act as a smart reverse proxy to help speed up GitLab as a whole. +[GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse) is a program designed at GitLab to help alleviate pressure from Puma. You can read more about the [historical reasons for developing](https://about.gitlab.com/blog/2016/04/12/a-brief-history-of-gitlab-workhorse/). It's designed to act as a smart reverse proxy to help speed up GitLab as a whole. #### Grafana @@ -411,7 +486,8 @@ For monitoring deployed apps, see [Jaeger tracing documentation](../operations/t - Layer: Core Service - Process: `logrotate` -GitLab is comprised of a large number of services that all log. We started bundling our own logrotate as of 7.4 to make sure we were logging responsibly. This is just a packaged version of the common open source offering. +GitLab is comprised of a large number of services that all log. We started bundling our own Logrotate +as of GitLab 7.4 to make sure we were logging responsibly. This is just a packaged version of the common open source offering. #### Mattermost @@ -560,7 +636,7 @@ Redis is packaged to provide a place to store: - [Source](../administration/packages/container_registry.md#enable-the-container-registry) - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/registry.md) - Layer: Core Service (Processor) -- GitLab.com: [GitLab Container Registry](../user/packages/container_registry/index.md#build-and-push-images-using-gitlab-cicd) +- GitLab.com: [GitLab Container Registry](../user/packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) The registry is what users use to store their own Docker images. The bundled registry uses NGINX as a load balancer and GitLab as an authentication manager. @@ -603,8 +679,30 @@ For monitoring deployed apps, see the [Sentry integration docs](../operations/er Sidekiq is a Ruby background job processor that pulls jobs from the Redis queue and processes them. Background jobs allow GitLab to provide a faster request/response cycle by moving work into the background. +#### Puma + +NOTE: **Note:** +Starting with GitLab 13.0, Puma is the default web server and Unicorn has been +disabled by default. + +- [Project page](https://gitlab.com/gitlab-org/gitlab/blob/master/README.md) +- Configuration: + - [Omnibus](https://docs.gitlab.com/omnibus/settings/puma.html) + - [Charts](https://docs.gitlab.com/charts/charts/gitlab/webservice/) + - [Source](../install/installation.md#configure-it) + - [GDK](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) +- Layer: Core Service (Processor) +- Process: `puma` +- GitLab.com: [Puma](../user/gitlab_com/index.md#puma) + +[Puma](https://puma.io/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often process output you will see this as `bundle` or `config.ru` depending on the GitLab version. + #### Unicorn +NOTE: **Note:** +Starting with GitLab 13.0, Puma is the default web server and Unicorn has been +disabled by default. + - [Project page](https://gitlab.com/gitlab-org/gitlab/blob/master/README.md) - Configuration: - [Omnibus](https://docs.gitlab.com/omnibus/settings/unicorn.html) @@ -669,7 +767,7 @@ You can install them after you create a cluster. This includes: - [JupyterHub](https://jupyter.org) - [Knative](https://cloud.google.com/knative/) -## GitLab by Request Type +## GitLab by request type GitLab provides two "interfaces" for end users to access the service: @@ -678,20 +776,20 @@ GitLab provides two "interfaces" for end users to access the service: It's important to understand the distinction as some processes are used in both and others are exclusive to a specific request type. -### GitLab Web HTTP Request Cycle +### GitLab Web HTTP request cycle When making a request to an HTTP Endpoint (think `/users/sign_in`) the request will take the following path through the GitLab Service: - NGINX - Acts as our first line reverse proxy. -- GitLab Workhorse - This determines if it needs to go to the Rails application or somewhere else to reduce load on Unicorn. -- Unicorn - Since this is a web request, and it needs to access the application it will go to Unicorn. +- GitLab Workhorse - This determines if it needs to go to the Rails application or somewhere else to reduce load on Puma. +- Puma - Since this is a web request, and it needs to access the application it will go to Puma. - PostgreSQL/Gitaly/Redis - Depending on the type of request, it may hit these services to store or retrieve data. -### GitLab Git Request Cycle +### GitLab Git request cycle Below we describe the different paths that HTTP vs. SSH Git requests will take. There is some overlap with the Web Request Cycle but also some differences. -### Web Request (80/443) +### Web request (80/443) Git operations over HTTP use the stateless "smart" protocol described in the [Git documentation](https://git-scm.com/docs/http-protocol), but responsibility @@ -736,7 +834,7 @@ sequenceDiagram The sequence is similar for `git push`, except `git-receive-pack` is used instead of `git-upload-pack`. -### SSH Request (22) +### SSH request (22) Git operations over SSH can use the stateful protocol described in the [Git documentation](https://git-scm.com/docs/pack-protocol#_ssh_transport), but @@ -801,7 +899,7 @@ except there is no round-trip into Gitaly - Rails performs the action as part of the [internal API](internal_api.md) call, and GitLab Shell streams the response back to the user directly. -## System Layout +## System layout When referring to `~git` in the pictures it means the home directory of the Git user which is typically `/home/git`. @@ -811,9 +909,9 @@ The bare repositories are located in `/home/git/repositories`. GitLab is a Ruby To serve repositories over SSH there's an add-on application called GitLab Shell which is installed in `/home/git/gitlab-shell`. -### Installation Folder Summary +### Installation folder summary -To summarize here's the [directory structure of the `git` user home directory](../install/structure.md). +To summarize here's the [directory structure of the `git` user home directory](../install/installation.md#gitlab-directory-structure). ### Processes @@ -823,12 +921,12 @@ ps aux | grep '^git' GitLab has several components to operate. It requires a persistent database (PostgreSQL) and Redis database, and uses Apache `httpd` or NGINX to proxypass -Unicorn. All these components should run as different system users to GitLab -(e.g., `postgres`, `redis` and `www-data`, instead of `git`). +Puma. All these components should run as different system users to GitLab +(for example, `postgres`, `redis`, and `www-data`, instead of `git`). -As the `git` user it starts Sidekiq and Unicorn (a simple Ruby HTTP server +As the `git` user it starts Sidekiq and Puma (a simple Ruby HTTP server running on port `8080` by default). Under the GitLab user there are normally 4 -processes: `unicorn_rails master` (1 process), `unicorn_rails worker` +processes: `puma master` (1 process), `puma cluster worker` (2 processes), `sidekiq` (1 process). ### Repository access @@ -841,7 +939,7 @@ See the README for more information. ### Init scripts of the services -The GitLab init script starts and stops Unicorn and Sidekiq: +The GitLab init script starts and stops Puma and Sidekiq: ```plaintext /etc/init.d/gitlab @@ -881,9 +979,9 @@ Usage: /etc/init.d/postgresql {start|stop|restart|reload|force-reload|status} [v ### Log locations of the services -GitLab (includes Unicorn and Sidekiq logs): +GitLab (includes Puma and Sidekiq logs): -- `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `unicorn.stdout.log`, `git_json.log` and `unicorn.stderr.log` normally. +- `/home/git/gitlab/log/` contains `application.log`, `production.log`, `sidekiq.log`, `puma.stdout.log`, `git_json.log` and `puma.stderr.log` normally. GitLab Shell: @@ -914,17 +1012,18 @@ PostgreSQL: ### GitLab specific configuration files -GitLab has configuration files located in `/home/git/gitlab/config/*`. Commonly referenced config files include: +GitLab has configuration files located in `/home/git/gitlab/config/*`. Commonly referenced +configuration files include: -- `gitlab.yml` - GitLab configuration. -- `unicorn.rb` - Unicorn web server settings. -- `database.yml` - Database connection settings. +- `gitlab.yml` - GitLab configuration +- `puma.rb` - Puma web server settings +- `database.yml` - Database connection settings GitLab Shell has a configuration file at `/home/git/gitlab-shell/config.yml`. -### Maintenance Tasks +### Maintenance tasks -[GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master) provides Rake tasks with which you see version information and run a quick check on your configuration to ensure it is configured properly within the application. See [maintenance Rake tasks](../raketasks/maintenance.md). +[GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master) provides Rake tasks with which you see version information and run a quick check on your configuration to ensure it is configured properly within the application. See [maintenance Rake tasks](../administration/raketasks/maintenance.md). In a nutshell, do the following: ```shell @@ -934,7 +1033,8 @@ bundle exec rake gitlab:env:info RAILS_ENV=production bundle exec rake gitlab:check RAILS_ENV=production ``` -Note: It is recommended to log into the `git` user using `sudo -i -u git` or `sudo su - git`. While the sudo commands provided by GitLab work in Ubuntu they do not always work in RHEL. +Note: It is recommended to log into the `git` user using `sudo -i -u git` or `sudo su - git`. While +the `sudo` commands provided by GitLab work in Ubuntu they do not always work in RHEL. ## GitLab.com diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index 4b58758b5c7..e5cc2ae4d1d 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -1,4 +1,11 @@ -# Background Migrations +--- +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + +# Background migrations Background migrations can be used to perform data migrations that would otherwise take a very long time (hours, days, years, etc) to complete. For @@ -92,6 +99,20 @@ bulk_migrate_async( ) ``` +Note that this will queue a Sidekiq job immediately: if you have a large number +of records, this may not be what you want. You can use the function +`queue_background_migration_jobs_by_range_at_intervals` to split the job into +batches: + +```ruby +queue_background_migration_jobs_by_range_at_intervals( + ClassName, + BackgroundMigrationClassName, + 2.minutes, + batch_size: 10_000 + ) +``` + You'll also need to make sure that newly created data is either migrated, or saved in both the old and new version upon creation. For complex and time consuming migrations it's best to schedule a background job using an diff --git a/doc/development/changelog.md b/doc/development/changelog.md index f57e666540c..922c4814d91 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -31,14 +31,16 @@ the `author` field. GitLab team members **should not**. - Any change that introduces a database migration, whether it's regular, post, or data migration, **must** have a changelog entry, even if it is behind a - disabled feature flag. + disabled feature flag. Since the migration is executed on [GitLab FOSS](https://gitlab.com/gitlab-org/gitlab-foss/), + the changelog for database schema changes should be written to the + `changelogs/unreleased/` directory, even when other elements of that change affect only GitLab EE. + - [Security fixes](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md) **must** have a changelog entry, without `merge_request` value and with `type` set to `security`. -- Any user-facing change **should** have a changelog entry. Example: "GitLab now - uses system fonts for all text." +- Any user-facing change **should** have a changelog entry. This includes both visual changes (regardless of how minor), and changes to the rendered DOM which impact how a screen reader may announce the content. - Performance improvements **should** have a changelog entry. -- Changes that need to be documented in the Telemetry [Event Dictionary](telemetry/event_dictionary.md) +- Changes that need to be documented in the Product Analytics [Event Dictionary](product_analytics/event_dictionary.md) also require a changelog entry. - _Any_ contribution from a community member, no matter how small, **may** have a changelog entry regardless of these guidelines if the contributor wants one. @@ -46,6 +48,7 @@ the `author` field. GitLab team members **should not**. - Any docs-only changes **should not** have a changelog entry. - Any change behind a disabled feature flag **should not** have a changelog entry. - Any change behind an enabled feature flag **should** have a changelog entry. +- Any change that adds new usage data metrics and changes that needs to be documented in Product Analytics [Event Dictionary](telemetry/event_dictionary.md) **should** have a changelog entry. - A change that [removes a feature flag](feature_flags/development.md) **should** have a changelog entry - only if the feature flag did not default to true already. - A fix for a regression introduced and then fixed in the same release (i.e., diff --git a/doc/development/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md index 3c1c7750842..c64766af589 100644 --- a/doc/development/chatops_on_gitlabcom.md +++ b/doc/development/chatops_on_gitlabcom.md @@ -22,9 +22,7 @@ To request access to Chatops on GitLab.com: 1. Log into **using the same username** as for GitLab.com (you may have to rename it). 1. You could also use the "Sign in with" Google button to sign in, with your GitLab.com email address. 1. Ask one of your team members to add you to the `chatops` project in Ops. They can do it by running `/chatops run member add gitlab-com/chatops --ops` command in the `#chat-ops-test` Slack channel. - -NOTE: **Note:** -If you had to change your username for GitLab.com on the first step, make sure [to reflect this information](https://gitlab.com/gitlab-com/www-gitlab-com#adding-yourself-to-the-team-page) on [the team page](https://about.gitlab.com/company/team/). +1. If you had to change your username for GitLab.com on the first step, make sure [to reflect this information](https://gitlab.com/gitlab-com/www-gitlab-com#adding-yourself-to-the-team-page) on [the team page](https://about.gitlab.com/company/team/). ## See also diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index 77cedc9814e..7d522a55559 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -13,15 +13,16 @@ This document explains how to develop [GitLab CI/CD templates](../../ci/examples All template files reside in the `lib/gitlab/ci/templates` directory, and are categorized by the following sub-directories: -| Sub-directory | Content | [Selectable in UI](#make-sure-the-new-template-can-be-selected-in-ui) | -|----------------|--------------------------------------------------------------|-----------------------------------------------------------------------| -| `/AWS/*` | Cloud Deployment (AWS) related jobs | No | -| `/Jobs/*` | Auto DevOps related jobs | No | -| `/Pages/*` | Static site generators for GitLab Pages (for example Jekyll) | Yes | -| `/Security/*` | Security related jobs | Yes | -| `/Verify/*` | Verify/testing related jobs | Yes | -| `/Workflows/*` | Common uses of the `workflow:` keyword | No | -| `/*` (root) | General templates | Yes | +| Sub-directory | Content | [Selectable in UI](#make-sure-the-new-template-can-be-selected-in-ui) | +|----------------|----------------------------------------------------|-----------------------------------------------------------------------| +| `/AWS/*` | Cloud Deployment (AWS) related jobs | No | +| `/Jobs/*` | Auto DevOps related jobs | No | +| `/Pages/*` | Static site generators for GitLab Pages (for example Jekyll) | Yes | +| `/Security/*` | Security related jobs | Yes | +| `/Terraform/*` | Infrastructure as Code related templates | No | +| `/Verify/*` | Verify/testing related jobs | Yes | +| `/Workflows/*` | Common uses of the `workflow:` keyword | No | +| `/*` (root) | General templates | Yes | ## Criteria @@ -110,7 +111,7 @@ to include older template versions. If other templates are included with `includ they can be combined with the `include: remote`: ```yaml -# To use the v13 stable template, which is not included in v14, fetch the specifc +# To use the v13 stable template, which is not included in v14, fetch the specific # template from the remote template repository with the `include:remote:` keyword. # If you fetch from the GitLab canonical project, use the following URL format: # https://gitlab.com/gitlab-org/gitlab/-/raw//lib/gitlab/ci/templates/ diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 2e319efa5f3..3ff802d3b23 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -67,6 +67,10 @@ page, with these behaviors: contains the string 'OOO', or the emoji is `:palm_tree:` or `:beach:`. 1. [Trainee maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#trainee-maintainer) are three times as likely to be picked as other reviewers. +1. People whose [GitLab status](../user/profile/index.md#current-status) emoji + is `:large_blue_circle:` are more likely to be picked. This applies to both reviewers and trainee maintainers. + - Reviewers with `:large_blue_circle:` are two times as likely to be picked as other reviewers. + - Trainee maintainers with `:large_blue_circle:` are four times as likely to be picked as other reviewers. 1. It always picks the same reviewers and maintainers for the same branch name (unless their OOO status changes, as in point 1). It removes leading `ce-` and `ee-`, and trailing `-ce` and `-ee`, so @@ -100,6 +104,7 @@ with [domain expertise](#domain-experts). by a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors)**. 1. If your merge request only includes end-to-end changes (*3*) **or** if the MR author is a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors), it must be **approved by a [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa)** 1. If your merge request includes a new or updated [application limit](https://about.gitlab.com/handbook/product/product-processes/#introducing-application-limits), it must be **approved by a [product manager](https://about.gitlab.com/company/team/)**. +1. If your merge request includes Product Analytics (telemetry) changes, it should be reviewed and approved by a [Product analytics engineer](https://gitlab.com/gitlab-org/growth/product-analytics/engineers). - (*1*): Please note that specs other than JavaScript specs are considered backend code. - (*2*): We encourage you to seek guidance from a database maintainer if your merge diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index 7d2d1b77a0e..d880361e3aa 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -1,3 +1,9 @@ +--- +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Community members & roles GitLab community members and their privileges/responsibilities. diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index 352392931c0..891c764f07f 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -1,3 +1,10 @@ +--- +type: reference, dev +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Implement design & UI elements For guidance on UX implementation at GitLab, please refer to our [Design System](https://design.gitlab.com/). diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 7550fe69546..6cbe57bf926 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -1,3 +1,10 @@ +--- +type: reference, dev +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Contribute to GitLab Thank you for your interest in contributing to GitLab. This guide details how diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index bb7b4713a5e..b7c05a369f0 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -1,3 +1,10 @@ +--- +type: reference, dev +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Issues workflow ## Issue tracker guidelines @@ -320,6 +327,11 @@ look for issues labeled `~"Accepting merge requests"` with a [weight of 1](https More experienced contributors are very welcome to tackle [any of them](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None). +For more complex features that have a weight of 2 or more and clear scope, we recommend looking at issues +with the [label `~"Community Challenge"`](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Accepting%20merge%20requests&label_name[]=Community%20challenge). +If your MR for the `~"Community Challenge"` issue gets merged, you will also have a chance to win a custom +GitLab merchandise. + If you've decided that you would like to work on an issue, please @-mention the [appropriate product manager](https://about.gitlab.com/handbook/product/#who-to-talk-to-for-what) as soon as possible. The product manager will then pull in appropriate GitLab team diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index d88b159b666..31f59ad875c 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -1,3 +1,10 @@ +--- +type: reference, dev +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Merge requests workflow We welcome merge requests from everyone, with fixes and improvements @@ -218,7 +225,7 @@ requirements. 1. [Secure coding guidelines](https://gitlab.com/gitlab-com/gl-security/security-guidelines) have been followed. 1. [Documented](../documentation/index.md) in the `/doc` directory. 1. [Changelog entry added](../changelog.md), if necessary. -1. Reviewed by relevant (UX/FE/BE/tech writing) reviewers and all concerns are addressed. +1. Reviewed by relevant reviewers and all concerns are addressed for Availability, Regressions, Security. Documentation reviews should take place as soon as possible, but they should not block a merge request. 1. Merged by a project maintainer. 1. Create an issue in the [infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues) to inform the Infrastructure department when your contribution is changing default settings or introduces a new setting, if relevant. 1. Confirmed to be working in the [Canary stage](https://about.gitlab.com/handbook/engineering/#canary-testing) or on GitLab.com once the contribution is deployed. diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index f6e64c1f1e6..773c1a771cd 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -1,3 +1,10 @@ +--- +type: reference, dev +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Style guides ## Editor/IDE styling standardization diff --git a/doc/development/database/add_foreign_key_to_existing_column.md b/doc/development/database/add_foreign_key_to_existing_column.md index 1b41a52c95e..85411ff9aa7 100644 --- a/doc/development/database/add_foreign_key_to_existing_column.md +++ b/doc/development/database/add_foreign_key_to_existing_column.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Adding foreign key constraint to an existing column Foreign keys help ensure consistency between related database tables. The current database review process **always** encourages you to add [foreign keys](../foreign_keys.md) when creating tables that reference records from other tables. @@ -103,7 +109,7 @@ class RemoveRecordsWithoutUserFromEmailsTable < ActiveRecord::Migration[5.2] end def down - # Can be a no-op when data inconsistency is not affecting the pre and post deploymnet version of the application. + # Can be a no-op when data inconsistency is not affecting the pre and post deployment version of the application. # In this case we might have records in the `emails` table where the associated record in the `users` table is not there anymore. end end diff --git a/doc/development/database/client_side_connection_pool.md b/doc/development/database/client_side_connection_pool.md new file mode 100644 index 00000000000..1a30d2d73a3 --- /dev/null +++ b/doc/development/database/client_side_connection_pool.md @@ -0,0 +1,63 @@ +--- +type: dev, reference +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +--- + +# Client-side connection-pool + +Ruby processes accessing the database through +ActiveRecord, automatically calculate the connection-pool size for the +process based on the concurrency. + +Because of the way [Ruby on Rails manages database +connections](#connection-lifecycle), it is important that we have at +least as many connections as we have threads. While there is a 'pool' +setting in [`database.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/database.yml.postgresql), it is not very practical because you need to +maintain it in tandem with the number of application threads. For this +reason, we override the number of allowed connections in the database +connection-pool based on the configured number of application threads. + +`Gitlab::Runtime.max_threads` is the number of user-facing +application threads the process has been configured with. We also have +auxiliary threads that use database connections. As it isn't +straightforward to keep an accurate count of the number of auxiliary threads as +the application evolves over time, we just add a fixed headroom to the +number of user-facing threads. It is OK if this number is too large +because connections are instantiated lazily. + +## Troubleshooting connection-pool issues + +The connection-pool usage can be seen per environment in the [connection-pool +saturation +dashboard](https://dashboards.gitlab.net/d/alerts-sat_rails_db_connection_pool/alerts-rails_db_connection_pool-saturation-detail?orgId=1). + +If the connection-pool is too small, this would manifest in +`ActiveRecord::ConnectionTimeoutError`s from the application. Because we alert +when almost all connections are used, we should know this before +timeouts occur. If this happens we can remediate by setting the +`DB_POOL_HEADROOM` environment variable to something bigger than the +hardcoded value (10). + +At this point, we need to investigate what is using more connections +than we anticipated. To do that, we can use the +`gitlab_ruby_threads_running_threads` metric. For example, [this +graph](https://thanos-query.ops.gitlab.net/graph?g0.range_input=1h&g0.max_source_resolution=0s&g0.expr=sum%20by%20(thread_name)%20(%20gitlab_ruby_threads_running_threads%7Buses_db_connection%3D%22yes%22%7D%20)&g0.tab=0) +shows all running threads that connect to the database by their +name. Threads labeled `puma worker` or `sidekiq_worker_thread` are +the threads that define `Gitlab::Runtime.max_threads` so those are +accounted for. If there's more than 10 other threads running, we could +consider raising the default headroom. + +## Connection lifecycle + +For web requests, a connection is obtained from the pool at the first +time a database query is made. The connection is returned to the pool +after the request completes. + +For background jobs, the behavior is very similar. The thread obtains +a connection for the first query, and returns it after the job is +finished. + +This is managed by Rails internally. diff --git a/doc/development/database/database_reviewer_guidelines.md b/doc/development/database/database_reviewer_guidelines.md index 6cb061f9959..3345df8b46b 100644 --- a/doc/development/database/database_reviewer_guidelines.md +++ b/doc/development/database/database_reviewer_guidelines.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Database Reviewer Guidelines This page includes introductory material for new database reviewers. diff --git a/doc/development/database/index.md b/doc/development/database/index.md index 9ea5b6fcaac..4bcefefe7a7 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Database guides ## Database Reviews @@ -24,6 +30,7 @@ - [Background migrations](../background_migrations.md) - [Swapping tables](../swapping_tables.md) - [Deleting migrations](../deleting_migrations.md) +- [Partitioning tables](table_partitioning.md) ## Debugging @@ -49,6 +56,8 @@ - [Database Debugging and Troubleshooting](../database_debugging.md) - [Query Count Limits](../query_count_limits.md) - [Creating enums](../creating_enums.md) +- [Client-side connection-pool](client_side_connection_pool.md) +- [Updating multiple values](./setting_multiple_values.md) ## Case studies diff --git a/doc/development/database/not_null_constraints.md b/doc/development/database/not_null_constraints.md index e4dec2afa10..96271863d94 100644 --- a/doc/development/database/not_null_constraints.md +++ b/doc/development/database/not_null_constraints.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # `NOT NULL` constraints > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38358) in GitLab 13.0. @@ -33,7 +39,7 @@ end ## Add a `NOT NULL` column to an existing table -With PostgreSQL 11 being the minimum version since GitLab 13.0, adding columns with `NULL` and/or +With PostgreSQL 11 being the minimum version in GitLab 13.0 and later, adding columns with `NULL` and/or default values has become much easier and the standard `add_column` helper should be used in all cases. For example, consider a migration that adds a new `NOT NULL` column `active` to table `db_guides`, diff --git a/doc/development/database/setting_multiple_values.md b/doc/development/database/setting_multiple_values.md new file mode 100644 index 00000000000..5569a0e10b7 --- /dev/null +++ b/doc/development/database/setting_multiple_values.md @@ -0,0 +1,103 @@ +# Setting Multiple Values + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32921) in GitLab 13.5. + +Frequently, we will want to update multiple objects with new values for one +or more columns. The obvious way to do this is using `Relation#update_all`: + +```ruby +user.issues.open.update_all(due_date: 7.days.from_now) # (1) +user.issues.update_all('relative_position = relative_position + 1') # (2) +``` + +But what do you do if you cannot express the update as either a static value (1) +or as a calculation (2)? + +Thankfully we can use `UPDATE FROM` to express the need to update multiple rows +with distinct values in a single query. One can either use a temporary table, or +a Common Table Expression (CTE), and then use that as the source of the updates: + +```sql +with updates(obj_id, new_title, new_weight) as ( + values (1 :: integer, 'Very difficult issue' :: text, 8 :: integer), + (2, 'Very easy issue', 1) +) +update issues + set title = new_title, weight = new_weight + from updates + where id = obj_id +``` + +The bad news: There is no way to express this in ActiveRecord or even dropping +down to ARel - the `UpdateManager` just does not support `update from`, so this +is not expressible. + +The good news: We supply an abstraction to help you generate these kinds of +updates, called `Gitlab::Database::BulkUpdate`. This constructs queries such as the +above, and uses binding parameters to avoid SQL injection. + +## Usage + +To use this, we need: + +- the list of columns to update +- a mapping from object/ID to the new values to set for that object +- a way to determine the table for each object + +So for example, we can express the query above as: + +```ruby +issue_a = Issue.find(..) +issue_b = Issue.find(..) + +# Issues a single query: +::Gitlab::Database::BulkUpdate.execute(%i[title weight], { + issue_a => { title: 'Very difficult issue', weight: 8 }, + issue_b => { title: 'Very easy issue', weight: 1 } +}) +``` + +Here the table can be determined automatically, from calling +`object.class.table_name`, so we don't need to provide anything. + +We can even pass heterogeneous sets of objects, if the updates all make sense +for them: + +```ruby +issue_a = Issue.find(..) +issue_b = Issue.find(..) +merge_request = MergeRequest.find(..) + +# Issues two queries +::Gitlab::Database::BulkUpdate.execute(%i[title], { + issue_a => { title: 'A' }, + issue_b => { title: 'B' }, + merge_request => { title: 'B' } +}) +``` + +If your objects do not return the correct model class (perhaps because they are +part of a union), then we need to specify this explicitly in a block: + +```ruby +bazzes = params +objects = Foo.from_union([ + Foo.select("id, 'foo' as object_type").where(quux: true), + Bar.select("id, 'bar' as object_type").where(wibble: true) + ]) +# At this point, all the objects are instances of Foo, even the ones from the +# Bar table +mapping = objects.to_h { |obj| [obj, bazzes[obj.id] } + +# Issues at most 2 queries +::Gitlab::Database::BulkUpdate.execute(%i[baz], mapping) do |obj| + obj.object_type.constantize +end +``` + +## Caveats + +Note that this is a **very low level** tool, and operates on the raw column +values. Enumerations and state fields must be translated into their underlying +representations, for example, and nested associations are not supported. No +validations or hooks will be called. diff --git a/doc/development/database/strings_and_the_text_data_type.md b/doc/development/database/strings_and_the_text_data_type.md index b73dfa859fb..fe8cfa5cd22 100644 --- a/doc/development/database/strings_and_the_text_data_type.md +++ b/doc/development/database/strings_and_the_text_data_type.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Strings and the Text data type > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30453) in GitLab 13.0. diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md new file mode 100644 index 00000000000..30d0b0a2f5b --- /dev/null +++ b/doc/development/database/table_partitioning.md @@ -0,0 +1,259 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Database table partitioning + +Table partitioning is a powerful database feature that allows a table's +data to be split into smaller physical tables that act as a single large +table. If the application is designed to work with partitioning in mind, +there can be multiple benefits, such as: + +- Query performance can be improved greatly, because the database can +cheaply eliminate much of the data from the search space, while still +providing full SQL capabilities. + +- Bulk deletes can be achieved with minimal impact on the database by +dropping entire partitions. This is a natural fit for features that need +to periodically delete data that falls outside the retention window. + +- Administrative tasks like `VACUUM` and index rebuilds can operate on +individual partitions, rather than across a single massive table. + +Unfortunately, not all models fit a partitioning scheme, and there are +significant drawbacks if implemented incorrectly. Additionally, tables +can only be partitioned at their creation, making it nontrivial to apply +partitioning to a busy database. A suite of migration tools are available +to enable backend developers to partition existing tables, but the +migration process is rather heavy, taking multiple steps split across +several releases. Due to the limitations of partitioning and the related +migrations, you should understand how partitioning fits your use case +before attempting to leverage this feature. + +## Determining when to use partitioning + +While partitioning can be very useful when properly applied, it's +imperative to identify if the data and workload of a table naturally fit a +partitioning scheme. There are a few details you'll have to understand +in order to decide if partitioning is a good fit for your particular +problem. + +First, a table is partitioned on a partition key, which is a column or +set of columns which determine how the data will be split across the +partitions. The partition key is used by the database when reading or +writing data, to decide which partition(s) need to be accessed. The +partition key should be a column that would be included in a `WHERE` +clause on almost all queries accessing that table. + +Second, it's necessary to understand the strategy the database will +use to split the data across the partitions. The scheme supported by the +GitLab migration helpers is date-range partitioning, where each partition +in the table contains data for a single month. In this case, the partitioning +key would need to be a timestamp or date column. In order for this type of +partitioning to work well, most queries would need to access data within a +certain date range. + +For a more concrete example, the `audit_events` table can be used, which +was the first table to be partitioned in the application database +(scheduled for deployment with the GitLab 13.5 release). This +table tracks audit entries of security events that happen in the +application. In almost all cases, users want to see audit activity that +occurs in a certain timeframe. As a result, date-range partitioning +was a natural fit for how the data would be accessed. + +To look at this in more detail, imagine a simplified `audit_events` schema: + +```sql +CREATE TABLE audit_events ( + id SERIAL NOT NULL PRIMARY KEY, + author_id INT NOT NULL, + details jsonb NOT NULL, + created_at timestamptz NOT NULL); +``` + +Now imagine typical queries in the UI would display the data within a +certain date range, like a single week: + +```sql +SELECT * +FROM audit_events +WHERE created_at >= '2020-01-01 00:00:00' + AND created_at < '2020-01-08 00:00:00' +ORDER BY created_at DESC +LIMIT 100 +``` + +If the table is partitioned on the `created_at` column the base table would +look like: + +```sql +CREATE TABLE audit_events ( + id SERIAL NOT NULL, + author_id INT NOT NULL, + details jsonb NOT NULL, + created_at timestamptz NOT NULL, + PRIMARY KEY (id, created_at)) +PARTITION BY RANGE(created_at); +``` + +NOTE: **Note:** +The primary key of a partitioned table must include the partition key as +part of the primary key definition. + +And we might have a list of partitions for the table, such as: + +```sql +audit_events_202001 FOR VALUES FROM ('2020-01-01') TO ('2020-02-01') +audit_events_202002 FOR VALUES FROM ('2020-02-01') TO ('2020-03-01') +audit_events_202003 FOR VALUES FROM ('2020-03-01') TO ('2020-04-01') +``` + +Each partition is a separate physical table, with the same structure as +the base `audit_events` table, but contains only data for rows where the +partition key falls in the specified range. For example, the partition +`audit_events_202001` contains rows where the `created_at` column is +greater than or equal to `2020-01-01` and less than `2020-02-01`. + +Now, if we look at the previous example query again, the database can +use the `WHERE` to recognize that all matching rows will be in the +`audit_events_202001` partition. Rather than searching all of the data +in all of the partitions, it can search only the single month's worth +of data in the appropriate partition. In a large table, this can +dramatically reduce the amount of data the database needs to access. +However, imagine a query that does not filter based on the partitioning +key, such as: + +```sql +SELECT * +FROM audit_events +WHERE author_id = 123 +ORDER BY created_at DESC +LIMIT 100 +``` + +In this example, the database can't prune any partitions from the search, +because matching data could exist in any of them. As a result, it has to +query each partition individually, and aggregate the rows into a single result +set. Since `author_id` would be indexed, the performance impact could +likely be acceptable, but on more complex queries the overhead can be +substantial. Partitioning should only be leveraged if the access patterns +of the data support the partitioning strategy, otherwise performance will +suffer. + +## Partitioning a table + +Unfortunately, tables can only be partitioned at their creation, making +it nontrivial to apply to a busy database. A suite of migration +tools have been developed to enable backend developers to partition +existing tables. This migration process takes multiple steps which must +be split across several releases. + +### Caveats + +The partitioning migration helpers work by creating a partitioned duplicate +of the original table and using a combination of a trigger and a background +migration to copy data into the new table. Changes to the original table +schema can be made in parallel with the partitioning migration, but they +must take care to not break the underlying mechanism that makes the migration +work. For example, if a column is added to the table that is being +partitioned, both the partitioned table and the trigger definition need to +be updated to match. + +### Step 1: Creating the partitioned copy (Release N) + +The first step is to add a migration to create the partitioned copy of +the original table. This migration will also create the appropriate +partitions based on the data in the original table, and install a +trigger that will sync writes from the original table into the +partitioned copy. + +An example migration of partitioning the `audit_events` table by its +`created_at` column would look like: + +```ruby +class PartitionAuditEvents < ActiveRecord::Migration[6.0] + include Gitlab::Database::PartitioningMigrationHelpers + + def up + partition_table_by_date :audit_events, :created_at + end + + def down + drop_partitioned_table_for :audit_events + end +end +``` + +Once this has executed, any inserts, updates or deletes in the +original table will also be duplicated in the new table. For updates and +deletes, the operation will only have an effect if the corresponding row +exists in the partitioned table. + +### Step 2: Backfill the partitioned copy (Release N) + +The second step is to add a post-deployment migration that will schedule +the background jobs that will backfill existing data from the original table +into the partitioned copy. + +Continuing the above example, the migration would look like: + +```ruby +class BackfillPartitionAuditEvents < ActiveRecord::Migration[6.0] + include Gitlab::Database::PartitioningMigrationHelpers + + def up + enqueue_partitioning_data_migration :audit_events + end + + def down + cleanup_partitioning_data_migration :audit_events + end +end +``` + +This step uses the same mechanism as any background migration, so you +may want to read the [Background Migration](../background_migrations.md) +guide for details on that process. Background jobs are scheduled every +2 minutes and copy `50_000` records at a time, which can be used to +estimate the timing of the background migration portion of the +partitioning migration. + +### Step 3: Post-backfill cleanup (Release N+1) + +The third step must occur at least one release after the release that +includes the background migration. This gives time for the background +migration to execute properly in self-managed installations. In this step, +add another post-deployment migration that will cleanup after the +background migration. This includes forcing any remaining jobs to +execute, and copying data that may have been missed, due to dropped or +failed jobs. + +Once again, continuing the example, this migration would look like: + +```ruby +class CleanupPartitionedAuditEventsBackfill < ActiveRecord::Migration[6.0] + include Gitlab::Database::PartitioningMigrationHelpers + + def up + finalize_backfilling_partitioned_table :audit_events + end + + def down + # no op + end +end +``` + +After this migration has completed, the original table and partitioned +table should contain identical data. The trigger installed on the +original table guarantees that the data will remain in sync going +forward. + +### Step 4: Swap the partitioned and non-partitioned tables (Release N+1) + +The final step of the migration will make the partitioned table ready +for use by the application. This section will be updated when the +migration helper is ready, for now development can be followed in the +[Tracking Issue](https://gitlab.com/gitlab-org/gitlab/-/issues/241267). diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index 61e8ac60bfe..ebd57df498e 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Troubleshooting and Debugging Database This section is to help give some copy-pasta you can use as a reference when you @@ -19,7 +25,7 @@ If you just want to delete everything and start over with an empty DB (approxima bundle exec rake db:reset RAILS_ENV=development ``` -If you just want to delete everything and start over with dummy data (approximately 4 minutes). This +If you just want to delete everything and start over with sample data (approximately 4 minutes). This also does `db:reset` and runs DB-specific migrations: ```shell diff --git a/doc/development/database_query_comments.md b/doc/development/database_query_comments.md index 77943f2b261..ccaaadef4f4 100644 --- a/doc/development/database_query_comments.md +++ b/doc/development/database_query_comments.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Database query comments with Marginalia The [Marginalia gem](https://github.com/basecamp/marginalia) is used to add diff --git a/doc/development/database_review.md b/doc/development/database_review.md index f56ffdbad21..3f5f36b0b6e 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Database Review Guidelines This page is specific to database reviews. Please refer to our @@ -21,7 +27,7 @@ A database review is required for: database review. - Changes in usage data metrics that use `count` and `distinct_count`. These metrics could have complex queries over large tables. - See the [Telemetry Guide](telemetry/usage_ping.md#implementing-usage-ping) + See the [Product Analytics Guide](product_analytics/usage_ping.md#implementing-usage-ping) for implementation details. A database reviewer is expected to look out for obviously complex @@ -184,10 +190,6 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - [Check query plans](understanding_explain_plans.md) and suggest improvements to queries (changing the query, schema or adding indexes and similar) - General guideline is for queries to come in below 100ms execution time - - If queries rely on prior migrations that are not present yet on production - (eg indexes, columns), you can use a [one-off instance from the restore - pipeline](https://ops.gitlab.net/gitlab-com/gl-infra/gitlab-restore/postgres-gprd) - in order to establish a proper testing environment. If you don't have access to this project, reach out to #database on Slack to get advice on how to proceed. - Avoid N+1 problems and minimalize the [query count](merge_request_performance_guidelines.md#query-counts). ### Timing guidelines for migrations diff --git a/doc/development/db_dump.md b/doc/development/db_dump.md index 4095932e44c..b16cd4b08d1 100644 --- a/doc/development/db_dump.md +++ b/doc/development/db_dump.md @@ -1,3 +1,9 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + # Importing a database dump into a staging environment Sometimes it is useful to import the database from a production environment diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 9a4c15c5c19..952435150d6 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -1,15 +1,12 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Distributed Tracing - development guidelines -NOTE: **Note:** -Distributed Tracing in GitLab is currently considered **experimental**, as it has not yet been tested at scale on GitLab.com. - -GitLab is instrumented for distributed tracing. +GitLab is instrumented for distributed tracing. Distributed Tracing in GitLab is currently considered **experimental**, as it has not yet been tested at scale on GitLab.com. According to [Open Tracing](https://opentracing.io/docs/overview/what-is-tracing/): diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index a4a6ee2fa0f..0f03ceeb4b5 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -52,7 +52,7 @@ For feature flags disabled by default, if they can be used by end users: do not say anything about it. - Say whether it's recommended for production use. - Document how to enable and disable it. -- Add a warning to the user saying that the feature is disabled. +- Add a warning to the user saying that the feature might be disabled. For example, for a feature disabled by default, disabled on GitLab.com, cannot be enabled for a single project, and is not ready for production use: @@ -250,7 +250,7 @@ be enabled by project, and is ready for production use: > - [Introduced](link-to-issue) in GitLab 12.0. > - It's [deployed behind a feature flag](/user/feature_flags.md), enabled by default. > - It's enabled on GitLab.com. -> - It can be enabled or disable for a single project. +> - It can be enabled or disabled for a single project. > - It's recommended for production use. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#anchor-to-section). **(CORE ONLY)** diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md new file mode 100644 index 00000000000..11e6b159359 --- /dev/null +++ b/doc/development/documentation/graphql_styleguide.md @@ -0,0 +1,92 @@ +--- +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +description: "Writing styles, markup, formatting, and other standards for GraphQL API's GitLab Documentation." +--- + +# GraphQL API + +GraphQL APIs are different from [RESTful APIs](restful_api_styleguide.md). Reference +information is generated in our [GraphQL reference](../../api/graphql/reference/index.md). + +However, it's helpful to include examples on how to use GraphQL for different +*use cases*, with samples that readers can use directly in the +[GraphiQL explorer](../api_graphql_styleguide.md#graphiql). + +This section describes the steps required to add your GraphQL examples to +GitLab documentation. + +## Add a dedicated GraphQL page + +To create a dedicated GraphQL page, create a new `.md` file in the +`doc/api/graphql/` directory. Give that file a functional name, such as +`import_from_specific_location.md`. + +## Start the page with an explanation + +Include a page title that describes the GraphQL functionality in a few words, +such as: + +```markdown +# Search for [substitute kind of data] +``` + +Describe the search. One sentence may be all you need. More information may +help readers learn how to use the example for their GitLab deployments. + +## Include a procedure using the GraphiQL explorer + +The GraphiQL explorer can help readers test queries with working deployments. +Set up the section with the following: + +- Use the following title: + + ```markdown + ## Set up the GraphiQL explorer + ``` + +- Include a code block with the query that anyone can include in their + instance of the GraphiQL explorer: + + ````markdown + ```graphql + query { + + } + ``` + ```` + +- Tell the user what to do: + + ```markdown + 1. Open the GraphiQL explorer tool in the following URL: `https://gitlab.com/-/graphql-explorer`. + 1. Paste the `query` listed above into the left window of your GraphiQL explorer tool. + 1. Select **Play** to get the result shown here: + ``` + +- Include a screenshot of the result in the GraphiQL explorer. Follow the naming + convention described in the [Save the image](styleguide.md#save-the-image) section of the Documentation style guide. +- Follow up with an example of what you can do with the output. Make sure the + example is something that readers can do on their own deployments. +- Include a link to the [GraphQL API resources](../../api/graphql/reference/index.md). + +## Add the GraphQL example to the global navigation + +You should include a link for your new document in the global navigation (the list on the +left side of the documentation website). To do so, open a second MR, against the +[GitLab documentation repository](https://gitlab.com/gitlab-org/gitlab-docs/). + +We store our global navigation in the [`default-nav.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_data/default-nav.yaml) file, in the +`content/_data` subdirectory. You can find the GraphQL section under the +following line: + +```yaml +- category_title: GraphQL +``` + +Be aware that CI tests for that second MR will fail with a bad link until the +main MR that adds the new GraphQL page is merged. Therefore, only merge the MR against the +[`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) repository after the content has +been merged and live on `docs.gitlab.com`. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index d6f24d6374d..e51f966ee6e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -1,4 +1,7 @@ --- +stage: none +group: Documentation Guidelines +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers description: Learn how to contribute to GitLab Documentation. --- @@ -52,9 +55,9 @@ docs-only merge requests using the following guide: [Contributions to GitLab docs](workflow.md) are welcome from the entire GitLab community. -To ensure that GitLab docs are current, there are special processes and responsibilities for all [feature changes](feature-change-workflow.md), that is development work that impacts the appearance, usage, or administration of a feature. +To ensure that GitLab docs are current, there are special processes and responsibilities for all [feature changes](workflow.md), that is development work that impacts the appearance, usage, or administration of a feature. -However, anyone can contribute [documentation improvements](improvement-workflow.md) that are not associated with a feature change. For example, adding a new doc on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab. +However, anyone can contribute [documentation improvements](workflow.md) that are not associated with a feature change. For example, adding a new doc on how to accomplish a use case that's already possible with GitLab or with third-party tools and GitLab. ## Markdown and styles @@ -128,7 +131,7 @@ The following metadata should be added when a page is moved to another location: - `redirect_to`: The relative path and filename (with an `.md` extension) of the location to which visitors should be redirected for a moved page. - [Learn more](#changing-document-location). + [Learn more](#move-or-rename-a-page). - `disqus_identifier`: Identifier for Disqus commenting system. Used to keep comments with a page that's been moved to a new URL. [Learn more](#redirections-for-pages-with-disqus-comments). @@ -156,17 +159,18 @@ Nanoc layout), which will be displayed at the top of the page if defined: [algorithm](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/lib/helpers/reading_time.rb) to calculate the reading time based on the number of words. -## Changing document location +## Move or rename a page + +Moving or renaming a document is the same as changing its location. This process +requires specific steps to ensure that visitors can find the new +documentation page, whether they're using `/help` from a GitLab instance or by +visiting . -Changing a document's location requires specific steps to ensure that -users can seamlessly access the new doc page, whether they are accessing content -on a GitLab instance domain at `/help` or at . Be sure to assign a -technical writer if you have any questions during the process (such as -whether the move is necessary), and ensure that a technical writer reviews this -change prior to merging. +Be sure to assign a technical writer to a page move or rename MR. Technical +Writers can help with any questions and can review your change. -If you indeed need to change a document's location, do not remove the old -document, but instead replace all of its content with the following: +To change a document's location, don't remove the old document, but instead +replace all of its content with the following: ```markdown --- @@ -176,14 +180,18 @@ redirect_to: '../path/to/file/index.md' This document was moved to [another location](../path/to/file/index.md). ``` -Where `../path/to/file/index.md` is usually the relative path to the old document. +Replace `../path/to/file/index.md` with the relative path to the old document. + +The `redirect_to` variable supports both full and relative URLs; for example: -The `redirect_to` variable supports both full and relative URLs, for example -`https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`. -It ensures that the redirect will work for and any `*.md` paths -will be compiled to `*.html`. -The new line underneath the front matter informs the user that the document -changed location and is useful for someone that browses that file from the repository. +- `https://docs.gitlab.com/ee/path/to/file.html` +- `../path/to/file.html` +- `path/to/file.md` + +The redirect works for , and any `*.md` paths are +changed to `*.html`. The description line following the `redirect_to` code +informs the visitor that the document changed location if the redirect process +doesn't complete successfully. For example, if you move `doc/workflow/lfs/index.md` to `doc/administration/lfs.md`, then the steps would be: @@ -208,9 +216,8 @@ For example, if you move `doc/workflow/lfs/index.md` to git grep -n "lfs/lfs_administration" ``` -NOTE: **Note:** -If the document being moved has any Disqus comments on it, there are extra steps -to follow documented just [below](#redirections-for-pages-with-disqus-comments). +1. If the document being moved has any Disqus comments on it, follow the steps + described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). Things to note: @@ -241,7 +248,8 @@ using the old URL as value. For example, let's say we moved the document available under `https://docs.gitlab.com/my-old-location/README.html` to a new location, `https://docs.gitlab.com/my-new-location/index.html`. -Into the **new document** front matter, we add the following: +Into the **new document** front matter, we add the following information. You must +include the file name in the `disqus_identifier` URL, even if it's `index.html` or `README.html`. ```yaml --- @@ -249,9 +257,6 @@ disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html' --- ``` -Note: it is necessary to include the file name in the `disqus_identifier` URL, -even if it's `index.html` or `README.html`. - ## Merge requests for GitLab documentation Before getting started, make sure you read the introductory section @@ -267,9 +272,8 @@ represents a good-faith effort to follow the template and style standards, and is believed to be accurate. Further needs for what would make the doc even better should be immediately addressed -in a follow-up MR or issue. +in a follow-up merge request or issue. -NOTE: **Note:** If the release version you want to add the documentation to has already been frozen or released, use the label `~"Pick into X.Y"` to get it merged into the correct release. Avoid picking into a past release as much as you can, as @@ -392,8 +396,7 @@ You will need at least Maintainer permissions to be able to run it. ![Manual trigger a docs build](img/manual_build_docs.png) -NOTE: **Note:** -You will need to push a branch to those repositories, it doesn't work for forks. +You must push a branch to those repositories, as it doesn't work for forks. The `review-docs-deploy*` job will: @@ -410,17 +413,16 @@ minutes and it should appear online, otherwise you can check the status of the remote pipeline from the link in the merge request's job output. If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. -TIP: **Tip:** -Someone with no merge rights to the GitLab projects (think of forks from -contributors) cannot run the manual job. In that case, you can -ask someone from the GitLab team who has the permissions to do that for you. - -NOTE: **Note:** Make sure that you always delete the branch of the merge request you were working on. If you don't, the remote docs branch won't be removed either, and the server where the Review Apps are hosted will eventually be out of disk space. +TIP: **Tip:** +Someone with no merge rights to the GitLab projects (think of forks from +contributors) cannot run the manual job. In that case, you can +ask someone from the GitLab team who has the permissions to do that for you. + ### Troubleshooting review apps In case the review app URL returns 404, follow these steps to debug: @@ -462,7 +464,7 @@ If you want to know the in-depth details, here's what's really happening: The following GitLab features are used among others: - [Manual actions](../../ci/yaml/README.md#whenmanual) -- [Multi project pipelines](../../ci/multi_project_pipeline_graphs.md) +- [Multi project pipelines](../../ci/multi_project_pipelines.md) - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/README.md#artifacts) - [Specific runner](../../ci/runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) @@ -668,7 +670,7 @@ build pipelines: ``` We recommend installing the version of `markdownlint-cli` currently used in the documentation - linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/dockerfiles/Dockerfile.gitlab-docs-lint#L38). + linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L420). 1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using `brew` for macOS, run: @@ -678,7 +680,7 @@ build pipelines: ``` We recommend installing the version of Vale currently used in the documentation linting - [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/dockerfiles/Dockerfile.gitlab-docs-lint#L16). + [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L419). In addition to using markdownlint and Vale at the command line, these tools can be [integrated with your code editor](#configure-editors). diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md new file mode 100644 index 00000000000..b12578b5d98 --- /dev/null +++ b/doc/development/documentation/restful_api_styleguide.md @@ -0,0 +1,180 @@ +--- +type: reference, dev +stage: none +group: Development +info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines" +description: "Writing styles, markup, formatting, and other standards for GitLab's RESTful APIs." +--- + +# RESTful API + +REST API resources are documented in Markdown under +[`/doc/api`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api). Each +resource has its own Markdown file, which is linked from `api_resources.md`. + +When modifying the Markdown, also update the corresponding +[OpenAPI definition](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi) +if one exists for the resource. If not, consider creating one. Match the latest +[OpenAPI 3.0.x specification](https://swagger.io/specification/). (For more +information, see the discussion in this +[issue](https://gitlab.com/gitlab-org/gitlab/-/issues/16023#note_370901810).) + +In the Markdown doc for a resource (AKA endpoint): + +- Every method must have the REST API request. For example: + + ```plaintext + GET /projects/:id/repository/branches + ``` + +- Every method must have a detailed [description of the parameters](#method-description). +- Every method must have a cURL example. +- Every method must have a response body (in JSON format). + +## API topic template + +The following can be used as a template to get started: + +````markdown +## Descriptive title + +One or two sentence description of what endpoint does. + +```plaintext +METHOD /endpoint +``` + +| Attribute | Type | Required | Description | +|:------------|:---------|:---------|:----------------------| +| `attribute` | datatype | yes/no | Detailed description. | +| `attribute` | datatype | yes/no | Detailed description. | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/endpoint?parameters" +``` + +Example response: + +```json +[ + { + } +] +``` +```` + +## Method description + +Use the following table headers to describe the methods. Attributes should +always be in code blocks using backticks (`` ` ``). + +```markdown +| Attribute | Type | Required | Description | +|:----------|:-----|:---------|:------------| +``` + +Rendered example: + +| Attribute | Type | Required | Description | +|:----------|:-------|:---------|:--------------------| +| `user` | string | yes | The GitLab username. | + +## cURL commands + +- Use `https://gitlab.example.com/api/v4/` as an endpoint. +- Wherever needed use this personal access token: ``. +- Always put the request first. `GET` is the default so you don't have to + include it. +- Wrap the URL in double quotes (`"`). +- Prefer to use examples using the personal access token and don't pass data of + username and password. + +| Methods | Description | +|:------------------------------------------- |:------------------------------------------------------| +| `--header "PRIVATE-TOKEN: "` | Use this method as is, whenever authentication needed. | +| `--request POST` | Use this method when creating new objects | +| `--request PUT` | Use this method when updating existing objects | +| `--request DELETE` | Use this method when removing existing objects | + +## cURL Examples + +The following sections include a set of [cURL](https://curl.haxx.se) examples +you can use in the API documentation. + +CAUTION: **Caution:** +Do not use information for real users, URLs, or tokens. For documentation, refer to our +relevant style guide sections on [Fake user information](styleguide.md#fake-user-information), +[Fake URLs](styleguide.md#fake-urls), and [Fake tokens](styleguide.md#fake-tokens). + +### Simple cURL command + +Get the details of a group: + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/gitlab-org" +``` + +### cURL example with parameters passed in the URL + +Create a new project under the authenticated user's namespace: + +```shell +curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects?name=foo" +``` + +### Post data using cURL's `--data` + +Instead of using `--request POST` and appending the parameters to the URI, you +can use cURL's `--data` option. The example below will create a new project +`foo` under the authenticated user's namespace. + +```shell +curl --data "name=foo" --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects" +``` + +### Post data using JSON content + +NOTE: **Note:** +In this example we create a new group. Watch carefully the single and double +quotes. + +```shell +curl --request POST --header "PRIVATE-TOKEN: " --header "Content-Type: application/json" --data '{"path": "my-group", "name": "My group"}' "https://gitlab.example.com/api/v4/groups" +``` + +### Post data using form-data + +Instead of using JSON or urlencode you can use multipart/form-data which +properly handles data encoding: + +```shell +curl --request POST --header "PRIVATE-TOKEN: " --form "title=ssh-key" --form "key=ssh-rsa AAAAB3NzaC1yc2EA..." "https://gitlab.example.com/api/v4/users/25/keys" +``` + +The above example is run by and administrator and will add an SSH public key +titled `ssh-key` to user's account which has an ID of 25. + +### Escape special characters + +Spaces or slashes (`/`) may sometimes result to errors, thus it is recommended +to escape them when possible. In the example below we create a new issue which +contains spaces in its title. Observe how spaces are escaped using the `%20` +ASCII code. + +```shell +curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude" +``` + +Use `%2F` for slashes (`/`). + +### Pass arrays to API calls + +The GitLab API sometimes accepts arrays of strings or integers. For example, to +exclude specific users when requesting a list of users for a project, you would +do something like this: + +```shell +curl --request PUT --header "PRIVATE-TOKEN: " --data "skip_users[]=" --data "skip_users[]=" "https://gitlab.example.com/api/v4/projects//users" +``` diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 22d97a9e2cf..9fce9b4e4b3 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -324,7 +324,6 @@ There are three main considerations on the logic built for the nav: - `https://docs.gitlab.com/ee/` - `https://docs.gitlab.com/omnibus/` - `https://docs.gitlab.com/runner/` - - `https://docs.gitlab.com/debug/` - `https://docs.gitlab.com/*` - [EE-only](#ee-only-docs): documentation only available in `/ee/`, not on `/ce/`, e.g.: - `https://docs.gitlab.com/ee/user/group/epics/` @@ -342,8 +341,8 @@ all the nav links to other pages: <% dir = @item.identifier.to_s[%r{(?<=/)[^/]+}] %> ``` -For instance, for `https://docs.gitlab.com/ce/user/index.html`, -`dir` == `ce`, and for `https://docs.gitlab.com/omnibus/README.html`, +For instance, for `https://docs.gitlab.com/ee/user/index.html`, +`dir` == `ee`, and for `https://docs.gitlab.com/omnibus/README.html`, `dir` == `omnibus`. #### Default URL diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index 98bb116aba6..d04d34ff786 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -121,10 +121,11 @@ versions (stable branches `X.Y` of the `gitlab-docs` project): pipelines succeed: NOTE: **Note:** - The `release-X-Y` branch needs to be present locally, otherwise the Rake - task will abort. + The `release-X-Y` branch needs to be present locally, + and you need to have switched to it, otherwise the Rake task will fail. ```shell + git checkout release-X-Y ./bin/rake release:dropdowns ``` diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 984c64b9e9e..6075124ef40 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -251,7 +251,7 @@ The table below shows what kind of documentation goes where. | `doc/legal/` | Legal documents about contributing to GitLab. | | `doc/install/` | Contains instructions for installing GitLab. | | `doc/update/` | Contains instructions for updating GitLab. | -| `doc/topics/` | Indexes per topic (`doc/topics/topic-name/index.md`): all resources for that topic. | +| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | ### Work with directories and files @@ -287,9 +287,8 @@ The table below shows what kind of documentation goes where. 1. The `doc/topics/` directory holds topic-related technical content. Create `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. General user- and admin- related documentation, should be placed accordingly. -1. The directories `/workflow/`, `/university/`, and `/articles/` have been - *deprecated* and the majority their documentation has been moved to their - correct location in small iterations. +1. The `/university/` directory is *deprecated* and the majority of its documentation + has been moved. If you are unsure where to place a document or a content addition, this should not stop you from authoring and contributing. You can use your best judgment and @@ -369,7 +368,7 @@ create an issue or an MR to propose a change to the user interface text. - milestones - reorder issues - runner, runners, shared runners - - a to-do, to-dos + - a to-do item, to dos - *Some features are capitalized*, typically nouns naming GitLab-specific capabilities or tools. For example: - GitLab CI/CD @@ -410,7 +409,7 @@ Use forms of *sign in*, instead of *log in* or *login*. For example: Exceptions to this rule include the concept of *single sign-on* and references to user interface elements. For example: -- To sign in to product X, enter your credentials, and then click **Log in**. +- To sign in to product X, enter your credentials, and then select **Log in**. ### Inclusive language @@ -418,8 +417,11 @@ We strive to create documentation that is inclusive. This section includes guidance and examples in the following categories: - [Gender-specific wording](#avoid-gender-specific-wording). + (Tested in [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml).) - [Ableist language](#avoid-ableist-language). + (Tested in [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml).) - [Cultural sensitivity](#culturally-sensitive-language). + (Tested in [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml).) We write our developer documentation with inclusivity and diversity in mind. This page is not an exhaustive reference, but describes some general guidelines and @@ -433,12 +435,16 @@ a gender-neutral pronoun. Avoid the use of gender-specific pronouns, unless referring to a specific person. + + | Use | Avoid | |-----------------------------------|---------------------------------| | People, humanity | Mankind | | GitLab Team Members | Manpower | | You can install; They can install | He can install; She can install | + + If you need to set up [Fake user information](#fake-user-information), use diverse or non-gendered names with common surnames. @@ -446,6 +452,8 @@ diverse or non-gendered names with common surnames. Avoid terms that are also used in negative stereotypes for different groups. + + | Use | Avoid | |------------------------|----------------------| | Check for completeness | Sanity check | @@ -455,6 +463,8 @@ Avoid terms that are also used in negative stereotypes for different groups. | Active/Inactive | Enabled/Disabled | | On/Off | Enabled/Disabled | + + Credit: [Avoid ableist language](https://developers.google.com/style/inclusive-documentation#ableist-language) in the Google Developer Style Guide. @@ -464,13 +474,57 @@ Avoid terms that reflect negative cultural stereotypes and history. In most cases, you can replace terms such as `master` and `slave` with terms that are more precise and functional, such as `primary` and `secondary`. + + | Use | Avoid | |----------------------|-----------------------| | Primary / secondary | Master / slave | | Allowlist / denylist | Blacklist / whitelist | + + For more information see the following [Internet Draft specification](https://tools.ietf.org/html/draft-knodel-terminology-02). +### Fake user information + +You may need to include user information in entries such as a REST call or user profile. +**Do not** use real user information or email addresses in GitLab documentation. For email +addresses and names, do use: + +- **Email addresses**: Use an email address ending in `example.com`. +- **Names**: Use strings like `example_username`. Alternatively, use diverse or + non-gendered names with common surnames, such as `Sidney Jones`, `Zhang Wei`, + or `Alex Garcia`. + +### Fake URLs + +When including sample URLs in the documentation, use: + +- `example.com` when the domain name is generic. +- `gitlab.example.com` when referring to self-managed instances of GitLab. + +### Fake tokens + +There may be times where a token is needed to demonstrate an API call using +cURL or a variable used in CI. It is strongly advised not to use real tokens in +documentation even if the probability of a token being exploited is low. + +You can use the following fake tokens as examples: + +| Token type | Token value | +|:----------------------|:-------------------------------------------------------------------| +| Private user token | `` | +| Personal access token | `n671WNGecHugsdEDPsyo` | +| Application ID | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` | +| Application secret | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` | +| CI/CD variable | `Li8j-mLUVA3eZYjPfd_H` | +| Specific runner token | `yrnZW46BrtBFqM7xDzE7dddd` | +| Shared runner token | `6Vk7ZsosqQyfreAxXTZr` | +| Trigger token | `be20d8dcc028677c931e04f3871a9b` | +| Webhook secret token | `6XhDroRcYPM5by_h-HLY` | +| Health check token | `Tu7BgjR9qeZTEyRzGG2P` | +| Request profile token | `7VgpS4Ax5utVD2esNstz` | + ### Language to avoid When creating documentation, limit or avoid the use of the following verb @@ -529,6 +583,7 @@ tenses, words, and phrases: - Avoid the use of [racially-insensitive terminology or phrases](https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/). For example: - Use *primary* and *secondary* for database and server relationships. - Use *allowlist* and *denylist* to describe access control lists. +- Avoid the word *please*. For details, see [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). ### Word usage clarifications @@ -832,8 +887,10 @@ When creating tables of lists of features (such as whether or not features are available to certain roles on the [Permissions](../../user/permissions.md#project-members-permissions) page), use the following phrases (based on the SVG icons): -- *No*: **{dotted-circle}** No -- *Yes*: **{check-circle}** Yes +| Option | Markdown | Displayed result | +|--------|--------------------------|------------------------| +| No | `**{dotted-circle}** No` | **{dotted-circle}** No | +| Yes | `**{check-circle}** Yes` | **{check-circle}** Yes | ## Quotes @@ -890,8 +947,8 @@ search engine optimization (SEO), use the imperative, where possible. For guidelines on capitalizing headings, see the section on [capitalization](#capitalization). NOTE: **Note:** -If you change an existing title, be careful. Any such changes may affect not -only [links](#anchor-links) within the page, but may also affect links to the +If you change an existing title, be careful. These changes might affect not +only [links](#anchor-links) within the page, but might also affect links to the GitLab documentation from both the GitLab application and external sites. ### Anchor links @@ -1095,14 +1152,26 @@ document to ensure it links to the most recent version of the file. ## Navigation -To indicate the steps of navigation through the user interface: +When documenting navigation through the user interface: -- Use the exact word as shown in the UI, including any capital letters as-is. +- Use the exact wording as shown in the UI, including any capital letters as-is. - Use bold text for navigation items and the char "greater than" (`>`) as a - separator (for example, `Navigate to your project's **Settings > CI/CD**` ). + separator. For example: `Navigate to your project's **Settings > CI/CD**`. - If there are any expandable menus, make sure to mention that the user needs to - expand the tab to find the settings you're referring to (for example, - `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`). + expand the tab to find the settings you're referring to. For example: + `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`. + +### Navigational elements + +Use the following terms when referring to the main GitLab user interface +elements: + +- **Top menu**: This is the top menu that spans the width of the user interface. + It includes the GitLab logo, search field, counters, and the user's avatar. +- **Left sidebar**: This is the navigation sidebar on the left of the user + interface, specific to the project or group. +- **Right sidebar**: This is the navigation sidebar on the right of the user + interface, specific to the open issue, merge request, or epic. ## Images @@ -1162,9 +1231,6 @@ that: - Are accurate, succinct, and unique. - Don't use *image of …* or *graphic of…* to describe the image. -Also, if a heading immediately follows an image, be sure to add three dashes -(`---`) between the image and the heading. - ### Remove image shadow All images displayed on the [GitLab documentation site](https://docs.gitlab.com) @@ -1249,7 +1315,7 @@ reviewed and approved by a technical writer. 1. In YouTube, visit the video URL you want to display. Copy the regular URL from your browser (`https://www.youtube.com/watch?v=VIDEO-ID`) and replace the video title and link in the line under `
`. -1. In YouTube, click **Share**, and then click **Embed**. +1. In YouTube, select **Share**, and then select **Embed**. 1. Copy the ` - - -When using the SAST template, Secret Detection is performed by a [specific analyzer](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml#L180) -during the `sast` job. It runs regardless of the programming -language of your app, and you don't need to change your -CI/CD configuration file to enable it. Results are available in the SAST report. - ### Customizing settings The Secret Detection scan settings can be changed through [environment variables](#available-variables) @@ -164,9 +139,52 @@ Secret Detection can be customized by defining available variables: |-------------------------|---------------|-------------| | `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | | `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | -| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories will also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | +| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | +### Custom rulesets + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211387) in GitLab 13.5. + +You can customize the default secret detection rules provided with GitLab. +Customization allows you to exclude rules and add new rules. + +To create a custom ruleset: + +1. Create a `.gitlab` directory at the root of your project, if one doesn't already exist. +1. Create a custom ruleset file named `secret-detection-ruleset.toml` in the `.gitlab` directory. +1. In the `secret-detection-ruleset.toml` file, do one of the following: + + - Define a custom ruleset: + + ```toml + [secrets] + description = 'secrets custom rules configuration' + + [[secrets.passthrough]] + type = "raw" + target = "gitleaks.toml" + value = """\ + title = "gitleaks config" + # add regexes to the regex table + [[rules]] + description = "Test for Raw Custom Rulesets" + regex = '''Custom Raw Ruleset T[est]{3}''' + """ + ``` + + - Provide the name of the file containing a custom ruleset: + + ```toml + [secrets] + description = 'secrets custom rules configuration' + + [[secrets.passthrough]] + type = "file" + target = "gitleaks.toml" + value = "config/gitleaks.toml" + ``` + ### Logging level To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. @@ -197,3 +215,35 @@ We have created a [short video walkthrough](https://youtu.be/wDtc_K00Y0A) showca
+ +### Make GitLab Secret Detection analyzer image available inside your Docker registry + +Import the following default Secret Detection analyzer images from `registry.gitlab.com` into your +[local Docker container registry](../../packages/container_registry/index.md): + +```plaintext +registry.gitlab.com/gitlab-org/security-products/analyzers/secrets:3 +``` + +The process for importing Docker images into a local offline Docker registry depends on +**your network security policy**. Please consult your IT staff to find an accepted and approved +process by which external resources can be imported or temporarily accessed. Note that these scanners are [updated periodically](../index.md#maintenance-and-update-of-the-vulnerabilities-database) +with new definitions, so consider if you're able to make periodic updates yourself. + +For details on saving and transporting Docker images as a file, see Docker's documentation on +[`docker save`](https://docs.docker.com/engine/reference/commandline/save/), [`docker load`](https://docs.docker.com/engine/reference/commandline/load/), +[`docker export`](https://docs.docker.com/engine/reference/commandline/export/), and [`docker import`](https://docs.docker.com/engine/reference/commandline/import/). + +#### If support for Custom Certificate Authorities are needed + +Support for custom certificate authorities was introduced in the following versions. + +| Analyzer | Version | +| -------- | ------- | +| secrets | [v3.0.0](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/releases/v3.0.0) | + +## Troubleshooting + +### Getting warning message `gl-secret-detection-report.json: no matching files` + +For information on this, see the [general Application Security troubleshooting section](../../../ci/pipelines/job_artifacts.md#error-message-no-files-to-upload). diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png index 67a7bb5f368..0310ef3ea0a 100644 Binary files a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png and b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_4.png differ diff --git a/doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png new file mode 100644 index 00000000000..4223494c294 Binary files /dev/null and b/doc/user/application_security/security_dashboard/img/instance_security_center_settings_v13_4.png differ diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png index 3c618090be8..5edceb32e5c 100644 Binary files a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png and b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_empty_v13_4.png differ diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png index d010adcc90c..5379b5c6e5d 100644 Binary files a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png and b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_v13_4.png differ diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png new file mode 100644 index 00000000000..eb1dfe6c6f4 Binary files /dev/null and b/doc/user/application_security/security_dashboard/img/project_security_dashboard_dismissal_v13_4.png differ diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png deleted file mode 100644 index 878bb83c2a2..00000000000 Binary files a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_0.png and /dev/null differ diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_2.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_2.png deleted file mode 100644 index 7cab7b0a61f..00000000000 Binary files a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_2.png and /dev/null differ diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png deleted file mode 100644 index 34c64f830ba..00000000000 Binary files a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_3.png and /dev/null differ diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png new file mode 100644 index 00000000000..c46a8295a53 Binary files /dev/null and b/doc/user/application_security/security_dashboard/img/project_security_dashboard_v13_5.png differ diff --git a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png index eb91cfc47ad..760942c3239 100644 Binary files a/doc/user/application_security/security_dashboard/img/vulnerability_list_table_v13_4.png and b/doc/user/application_security/security_dashboard/img/vulnerability_list_table_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 51d9b4f45cd..5fa8ebb80e0 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -5,21 +5,26 @@ group: Threat Insights info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab Security Dashboard **(ULTIMATE)** +# GitLab Security Dashboard, Security Center, and Vulnerability Reports **(ULTIMATE)** -The Security Dashboard is a good place to get an overview of all the security -vulnerabilities in your groups, projects, and pipelines. +GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: + +- Security dashboards: An overview of the security status in your instance, groups, and projects. +- Vulnerability reports: Detailed lists of all vulnerabilities for the instance, group, project, or + pipeline. This is where you triage and manage vulnerabilities. +- Security Center: A dedicated area for vulnerability management at the instance level. This + includes a security dashboard, vulnerability report, and settings. You can also drill down into a vulnerability and get extra information. This includes the project it comes from, any related file(s), and metadata that helps you analyze the risk it poses. You can also dismiss a vulnerability or create an issue for it. -To benefit from the Security Dashboard you must first configure one of the +To benefit from these features, you must first configure one of the [security scanners](../index.md). ## Supported reports -The Security Dashboard displays vulnerabilities detected by scanners such as: +The vulnerability report displays vulnerabilities detected by scanners such as: - [Container Scanning](../container_scanning/index.md) - [Dynamic Application Security Testing](../dast/index.md) @@ -29,7 +34,7 @@ The Security Dashboard displays vulnerabilities detected by scanners such as: ## Requirements -To use the instance, group, project, or pipeline security dashboard: +To use the security dashboards and vulnerability reports: 1. At least one project inside a group must be configured with at least one of the [supported reports](#supported-reports). @@ -41,15 +46,19 @@ To use the instance, group, project, or pipeline security dashboard: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. -At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline was run against. +At the pipeline level, the Security section displays the vulnerabilities present in the branch of +the project the pipeline ran against. ![Pipeline Security Dashboard](img/pipeline_security_dashboard_v13_3.png) Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view the pipeline's security findings, select the **Security** tab when viewing the pipeline. -NOTE: **Note:** -A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard will not show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure. +A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish +for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST +job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, +the analyzer outputs an +[exit code](../../../development/integrations/secure.md#exit-code). ## Project Security Dashboard @@ -60,12 +69,15 @@ At the project level, the Security Dashboard displays the vulnerabilities merged to **Security & Compliance > Security Dashboard**. By default, the Security Dashboard displays all detected and confirmed vulnerabilities. -The Security Dashboard first displays the total number of vulnerabilities by severity (for example, +The Security Dashboard first displays the time at which the last pipeline completed on the project's +default branch. There's also a link to view this in more detail. + +The Security Dashboard next displays the total number of vulnerabilities by severity (for example, Critical, High, Medium, Low, Info, Unknown). Below this, a table shows each vulnerability's status, severity, and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) page to view more information about that vulnerability. -![Project Security Dashboard](img/project_security_dashboard_v13_3.png) +![Project Security Dashboard](img/project_security_dashboard_v13_5.png) You can filter the vulnerabilities by one or more of the following: @@ -78,7 +90,7 @@ You can also dismiss vulnerabilities in the table: 1. Select the checkbox for each vulnerability you want to dismiss. 1. In the menu that appears, select the reason for dismissal and click **Dismiss Selected**. -![Project Security Dashboard](img/project_security_dashboard_v13_2.png) +![Project Security Dashboard](img/project_security_dashboard_dismissal_v13_4.png) ## Group Security Dashboard @@ -86,79 +98,99 @@ You can also dismiss vulnerabilities in the table: The group Security Dashboard gives an overview of the vulnerabilities in the default branches of the projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** -for your group. By default, the Security Dashboard displays all detected and confirmed -vulnerabilities. +after selecting your group. By default, the Security Dashboard displays all detected and confirmed +vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you +have not selected a group. -NOTE: **Note:** -The Security Dashboard only shows projects with [security reports](#supported-reports) enabled in a -group. +Note that the Security Dashboard only shows projects with +[security reports](#supported-reports) +enabled in a group. ![Dashboard with action buttons and metrics](img/group_security_dashboard_v13_3.png) There is a timeline chart that shows how many open -vulnerabilities your projects had at various points in time. You can filter among 30, 60, and -90 days, with the default being 90. Hover over the chart to get more details about -the open vulnerabilities at a specific time. +vulnerabilities your projects had at various points in time. You can display the vulnerability +trends over a 30, 60, or 90-day time frame (the default is 90 days). Hover over the chart to get +more details about the open vulnerabilities at a specific time. Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: -- F: 1 or more "critical" -- D: 1 or more "high" or "unknown" -- C: 1 or more "medium" -- B: 1 or more "low" -- A: 0 vulnerabilities +- F: One or more "critical" +- D: One or more "high" or "unknown" +- C: One or more "medium" +- B: One or more "low" +- A: Zero vulnerabilities Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed -vulnerabilities are not included either. +vulnerabilities are excluded. -Navigate to the group's [Vulnerability Report](#vulnerability-list) to view the vulnerabilities found. +Navigate to the group's [vulnerability report](#vulnerability-report) to view the vulnerabilities found. -## Instance Security Dashboard +## Instance Security Center -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6953) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.8. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.4. -At the instance level, the Security Dashboard displays the vulnerabilities present in the default -branches of all the projects you configure to display on the dashboard. It includes all the -[group Security Dashboard's](#group-security-dashboard) -features. +The Security Center is where you manage vulnerabilities for your instance. It displays the +vulnerabilities present in the default branches of all the projects you configure. It includes the +following: + +- The [group security dashboard's](#group-security-dashboard) features. +- A [vulnerability report](#vulnerability-report). +- A dedicated settings area to configure which projects to display. ![Instance Security Dashboard with projects](img/instance_security_dashboard_v13_4.png) -You can access the Instance Security Dashboard from the menu +You can access the Instance Security Center from the menu bar at the top of the page. Under **More**, select **Security**. -![Instance Security Dashboard navigation link](img/instance_security_dashboard_link_v12_4.png) +![Instance Security Center navigation link](img/instance_security_dashboard_link_v12_4.png) -The dashboard is empty before you add projects to it. +The dashboard and vulnerability report are empty before you add projects. -![Uninitialized Instance Security Dashboard](img/instance_security_dashboard_empty_v13_4.png) +![Uninitialized Instance Security Center](img/instance_security_dashboard_empty_v13_4.png) -### Adding projects to the dashboard +### Adding projects to the Security Center -To add projects to the dashboard: +To add projects to the Security Center: 1. Click **Settings** in the left navigation bar or click the **Add projects** button. 1. Search for and add one or more projects using the **Search your projects** field. 1. Click the **Add projects** button. -After you add projects, the Security Dashboard displays the vulnerabilities found in those projects' -default branches. +![Adding projects to Instance Security Center](img/instance_security_center_settings_v13_4.png) + +After you add projects, the security dashboard and vulnerability report display the vulnerabilities +found in those projects' default branches. ## Export vulnerabilities > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213014) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -You can export all your vulnerabilities in CSV format by clicking the **{upload}** **Export** -button located at top right of the **Security Dashboard**. After the report -is built, the CSV report downloads to your local machine. The report contains all -vulnerabilities for the projects defined in the **Security Dashboard**, -as filters don't apply to the export function. - -![Export vulnerabilities](img/instance_security_dashboard_export_csv_v13_4.png) +You can export all your vulnerabilities in CSV (comma separated values) format by clicking the +**{upload}** **Export** button located at top right of the Security Dashboard. When the report is +ready, the CSV report downloads to your local machine. The report contains all vulnerabilities for +the projects defined in the Security Dashboard, as filters don't apply to the export function. NOTE: **Note:** It may take several minutes for the download to start if your project contains -thousands of vulnerabilities. Do not close the page until the download finishes. +thousands of vulnerabilities. Don't close the page until the download finishes. + +The fields in the export include: + +- Group Name +- Project Name +- Scanner Type +- Scanner Name +- Status +- Vulnerability +- Details +- Additional Info +- Severity +- [CVE](https://cve.mitre.org/) (Common Vulnerabilities and Exposures) +- [CWE](https://cwe.mitre.org/) (Common Weakness Enumeration) +- Other Identifiers + +![Export vulnerabilities](img/instance_security_dashboard_export_csv_v13_4.png) ## Keeping the dashboards up to date @@ -191,14 +223,14 @@ When using [Auto DevOps](../../../topics/autodevops/index.md), use [special environment variables](../../../topics/autodevops/customize.md#environment-variables) to configure daily security scans. -## Vulnerability list +## Vulnerability report -Each dashboard's vulnerability list contains vulnerabilities from the latest scans that were merged +Each vulnerability report contains vulnerabilities from the latest scans that were merged into the default branch. ![Vulnerability Report](img/group_vulnerability_report_v13_4.png) -You can filter which vulnerabilities the Security Dashboard displays by: +You can filter which vulnerabilities the vulnerability report displays by: - Status - Severity @@ -211,8 +243,10 @@ To create an issue associated with the vulnerability, click the **Create Issue** ![Create an issue for the vulnerability](img/vulnerability_page_v13_1.png) -Once you create the issue, the vulnerability list contains a link to the issue and an icon whose -color indicates the issue's status (green for open issues, blue for closed issues). +Once you create the issue, the linked issue icon in the vulnerability list: + +- Indicates that an issue has been created for that vulnerability. +- Shows a tooltip that contains a link to the issue. ![Display attached issues](img/vulnerability_list_table_v13_4.png) diff --git a/doc/user/application_security/terminology/index.md b/doc/user/application_security/terminology/index.md index 8006a49ba35..f975de213ef 100644 --- a/doc/user/application_security/terminology/index.md +++ b/doc/user/application_security/terminology/index.md @@ -13,7 +13,6 @@ This terminology list for GitLab Secure and Defend aims to: - Improve the effectiveness of communication regarding GitLab's application security features. - Get new contributors up to speed faster. -NOTE: **Note:** This document defines application security terms in the specific context of GitLab's Secure and Defend products. Terms may therefore have different meanings outside of GitLab Secure and Defend. diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index 5414800b290..391666a077e 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -105,11 +105,10 @@ disabled state. Once enabled,a predefined policy deploys to the selected environment's deployment platform and you can manage it like the regular policies. -NOTE: **Note:** -If you're using [Auto DevOps](../../../topics/autodevops/index.md) and -change a policy in this section, your `auto-deploy-values.yaml` file -doesn't update. Auto DevOps users must make changes by following -the [Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). +Note that if you're using [Auto DevOps](../../../topics/autodevops/index.md) +and change a policy in this section, your `auto-deploy-values.yaml` file doesn't update. Auto DevOps +users must make changes by following the +[Container Network Policy documentation](../../../topics/autodevops/stages.md#network-policy). ### Changing enforcement status @@ -119,12 +118,9 @@ To change a network policy's enforcement status: - Click the **Enforcement status** toggle to update the selected policy. - Click the **Apply changes** button to deploy network policy changes. -NOTE: **Note:** -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 any pods. The policy itself is still deployed -to the corresponding deployment namespace. +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 +any pods. The policy itself is still deployed to the corresponding deployment namespace. ### Container Network Policy editor @@ -135,10 +131,8 @@ create a new policy click the **New policy** button located in the **Policy** tab's header. To edit an existing policy, click**Edit policy** in the selected policy drawer. -NOTE: **Note:** -The policy editor only supports the -[CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/)specification. Regular -Kubernetes +Note that the policy editor only supports the +[CiliumNetworkPolicy](https://docs.cilium.io/en/v1.8/policy/)specification. Regular Kubernetes [NetworkPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#networkpolicy-v1-networking-k8s-io) resources aren't supported. diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index ff383fdf553..ee3fd6c4dd4 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -14,6 +14,7 @@ Each security vulnerability in a project's [Security Dashboard](../security_dash - Details of the vulnerability. - The status of the vulnerability within the project. - Available actions for the vulnerability. +- Issues related to the vulnerability. On the vulnerability page, you can interact with the vulnerability in several different ways: @@ -23,6 +24,7 @@ several different ways: - [Create issue](#creating-an-issue-for-a-vulnerability) - Create a new issue with the title and description pre-populated with information from the vulnerability report. By default, such issues are [confidential](../../project/issues/confidential_issues.md). +- [Link issues](#link-issues-to-the-vulnerability) - Link existing issues to vulnerability. - [Solution](#automatic-remediation-for-vulnerabilities) - For some vulnerabilities, a solution is provided for how to fix the vulnerability. @@ -38,6 +40,9 @@ the following values: | Dismissed | A user has seen this vulnerability and dismissed it | | Resolved | The vulnerability has been fixed and is no longer in the codebase | +A timeline shows you when the vulnerability status has changed, +and allows you to comment on a change. + ## Creating an issue for a vulnerability You can create an issue for a vulnerability by selecting the **Create issue** button. @@ -47,6 +52,12 @@ project the vulnerability came from, and pre-populates it with useful informatio the vulnerability report. After the issue is created, GitLab redirects you to the issue page so you can edit, assign, or comment on the issue. +## Link issues to the vulnerability + +You can link one or more existing 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. + ## Automatic remediation for vulnerabilities You can fix some vulnerabilities by applying the solution that GitLab automatically diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 6521b71e9e6..196c3e9fb43 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -6,18 +6,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Kubernetes Agent **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). -## Goals +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. -The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) is an active in-cluster component for solving GitLab and Kubernetes integration tasks in a secure and cloud native way. +The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) +is an active in-cluster component for solving GitLab and Kubernetes integration +tasks in a secure and cloud-native way. It enables: -Features: +- Integrating GitLab with a Kubernetes cluster behind a firewall or NAT + (network address translation). +- Pull-based GitOps deployments by leveraging the + [GitOps Engine](https://github.com/argoproj/gitops-engine). +- Real-time access to API endpoints within a cluster. -1. Makes it possible to integrate GitLab with a Kubernetes cluster behind a firewall or NAT -1. Enables pull-based GitOps deployments by leveraging the [GitOps Engine](https://github.com/argoproj/gitops-engine) -1. Allows for real-time access to API endpoints within a cluster. -1. Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). +Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). ## Architecture @@ -39,34 +44,52 @@ sequenceDiagram end ``` -Please refer to our [full architecture documentation in the Agent project](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). +Please refer to our [full architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) +in the Agent project. -## Getting started with GitOps using the GitLab Agent and the GitLab Cloud Native Helm chart +## Get started with GitOps and the GitLab Agent There are several components that work in concert for the Agent to accomplish GitOps deployments: -1. A Kubernetes cluster that is properly configured -1. A configuration repository that contains a `config.yaml` file. This `config.yaml` tells the Agent which repositories to synchronize with. -1. A manifest repository that contains a `manifest.yaml`. This `manifest.yaml` (which can be autogenerated) is tracked by the Agent and any changes to the file are automatically applied to the cluster. +- A properly-configured Kubernetes cluster. +- A configuration repository that contains a `config.yaml` file, which tells the + Agent which repositories to synchronize with. +- A manifest repository that contains a `manifest.yaml`, which is tracked by the + Agent and can be auto-generated. Any changes to `manifest.yaml` are applied to the cluster. -The setup process involves a few steps that, once completed, will enable GitOps deployments to work +The setup process involves a few steps to enable GitOps deployments: -1. Installing the Agent server via GitLab Helm chart -1. Defining a configuration directory -1. Creating an Agent record in GitLab -1. Generating and copying a Secret token used to connect to the Agent -1. Installing the Agent into the cluster -1. Creating a `manifest.yaml` +1. Installing the Agent server. +1. Defining a configuration directory. +1. Creating an Agent record in GitLab. +1. Generating and copying a Secret token used to connect to the Agent. +1. Installing the Agent into the cluster. +1. Creating a `manifest.yaml`. -### Installing the Agent server via Helm +### Install the Agent server -Currently the GitLab Kubernetes Agent can only be deployed via our [Helm chart](https://gitlab.com/gitlab-org/charts/gitlab). +The GitLab Kubernetes Agent can be deployed using [Omnibus +GitLab](https://docs.gitlab.com/omnibus/) or the [GitLab +chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already have +GitLab installed, please refer to our [installation +documentation](https://docs.gitlab.com/ee/install/README.html). -NOTE: We are working quickly to [include the Agent in Official Linux Package](https://gitlab.com/gitlab-org/gitlab/-/issues/223060). +NOTE: **Note:** +GitLab plans to include the Agent on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). -If you don't already have GitLab installed via Helm please refer to our [installation documentation](https://docs.gitlab.com/charts/installation/) +When using the [Omnibus GitLab](https://docs.gitlab.com/omnibus/) package: -When installing/upgrading the GitLab Helm chart please consider the following Helm 2 example (if using Helm 3 please modify): +1. Edit `/etc/gitlab/gitlab.rb`: + +```plaintext +gitlab_kas['enable'] = true +``` + +1. [Reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + +When installing or upgrading the GitLab Helm chart, consider the following Helm 2 example. +(If you're using Helm 3, you must modify this example.) You must set `global.kas.enabled=true` +for the Agent to be properly installed and configured: ```shell helm repo update @@ -79,15 +102,14 @@ helm upgrade --force --install gitlab gitlab/gitlab \ --set global.kas.enabled=true ``` -`global.kas.enabled=true` must be set in order for the Agent to be properly installed and configured. - -### Defining a configuration repository +### Define a configuration repository -Next you will need a GitLab repository that will contain your Agent configuration. +Next, you need a GitLab repository to contain your Agent configuration. The minimal +repository layout looks like this: -The minimal repository layout looks like this: - -`.gitlab/agents//config.yaml` +```plaintext +.gitlab/agents//config.yaml +``` The `config.yaml` file contents should look like this: @@ -97,31 +119,24 @@ gitops: - id: "path-to/your-awesome-project" ``` -### Creating an Agent record in GitLab - -Next you will need to create an GitLab Rails Agent record so that your GitLab project so that the Agent itself can associate with a GitLab project. This process will also yield a Secret that you will use to configure the Agent in subsequent steps. +### Create an Agent record in GitLab -There are two ways to accomplish this: +Next, create an GitLab Rails Agent record so the Agent can associate itself with +the configuration repository project. Creating this record also creates a Secret needed to configure +the Agent in subsequent steps. You can create an Agent record either: -1. Via the Rails console -1. Via GraphQL +- Through the Rails console, by running `rails c`: -To do this you could either run `rails c` or via GraphQL. From `rails c`: - -```ruby + ```ruby project = ::Project.find_by_full_path("path-to/your-awesome-project") agent = ::Clusters::Agent.create(name: "", project: project) token = ::Clusters::AgentToken.create(agent: agent) token.token # this will print out the token you need to use on the next step -``` + ``` -or using GraphQL: +- Through GraphQL: **(PREMIUM ONLY)** -with this approach, you'll need a premium license to use this feature. - -If you are new to using the GitLab GraphQL API please refer to the [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md) or check out the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer). - -```json + ```graphql mutation createAgent { createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "" }) { clusterAgent { @@ -142,37 +157,77 @@ If you are new to using the GitLab GraphQL API please refer to the [Getting star errors } } -``` + ``` -Note that GraphQL will only show you the token once, after you've created it. + NOTE: **Note:** + GraphQL only displays the token once, after creating it. -### Creating the Kubernetes secret + If you are new to using the GitLab GraphQL API, refer to the + [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md), + or the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer). -Once the token has been generated it needs to be applied to the Kubernetes cluster. +### Create the Kubernetes secret -If you didn't previously define or create a namespace you need to do that first: +After generating the token, you must apply it to the Kubernetes cluster. -```shell -kubectl create namespace -``` +1. If you haven't previous defined or created a namespace, run the following command: + + ```shell + kubectl create namespace + ``` + +1. Run the following command to create your Secret: + + ```shell + kubectl create secret generic -n gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' + ``` -Run the following command to create your Secret: +### Install the Agent into the cluster + +Next, install the in-cluster component of the Agent. This example file contains the +Kubernetes resources required for the Agent to be installed. You can modify this +example [`resources.yml` file](#example-resourcesyml-file) in the following ways: + +- You can replace `gitlab-agent` with ``. +- For the `kas-address` (Kubernetes Agent Server), the agent can use the WebSockets + or gRPC protocols to connect to the Agent Server. Depending on your cluster + configuration and GitLab architecture, you may need to use one or the other. + For the `gitlab-kas` Helm chart, an Ingress is created for the Agent Server using + the `/-/kubernetes-agent` endpoint. This can be used for the WebSockets protocol connection. + - Specify the `grpc` scheme (such as `grpc://gitlab-kas:5005`) to use gRPC directly. + Encrypted gRPC is not supported yet. Follow the + [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) + for progress updates. + - Specify the `ws` scheme (such as `ws://gitlab-kas-ingress:80/-/kubernetes-agent`) + to use an unencrypted WebSockets connection. + - Specify the `wss` scheme (such as `wss://gitlab-kas-ingress:443/-/kubernetes-agent`) + to use an encrypted WebSockets connection. This is the recommended option if + installing the Agent into a separate cluster from your Agent Server. +- If you defined your own secret name, replace `gitlab-agent-token` with your secret name. + +To apply this file, run the following command: ```shell -kubectl create secret generic -n gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' +kubectl apply -n gitlab-agent -f ./resources.yml ``` -### Installing the Agent into the cluster +To review your configuration, run the following command: -Next you are now ready to install the in-cluster component of the Agent. The below is an example YAML file of the Kubernetes resources required for the Agent to be installed. - -Let's highlight a few of the details in the example below: +```shell +$ kubectl get pods --all-namespaces -1. You can replace `gitlab-agent` with -1. For the `kas-address` (Kubernetes Agent Server), you can replace `grpc://host.docker.internal:5005` with the address of the kas agent that was initialized via your Helm install. -1. If you defined your own secret name, then replace `gitlab-agent-token` with your secret name. +NAMESPACE NAME READY STATUS RESTARTS AGE +gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s +kube-system coredns-f9fd979d6-n6wcw 1/1 Running 0 14m +kube-system etcd-minikube 1/1 Running 0 14m +kube-system kube-apiserver-minikube 1/1 Running 0 14m +kube-system kube-controller-manager-minikube 1/1 Running 0 14m +kube-system kube-proxy-j6zdh 1/1 Running 0 14m +kube-system kube-scheduler-minikube 1/1 Running 0 14m +kube-system storage-provisioner 1/1 Running 0 14m +``` -`./resources.yml` +#### Example `resources.yml` file ```yaml apiVersion: v1 @@ -201,7 +256,7 @@ spec: args: - --token-file=/config/token - --kas-address - - grpc://host.docker.internal:5005 # {"$openapi":"kas-address"} + - grpc://host.docker.internal:5005 # {"$openapi":"kas-address"} volumeMounts: - name: token-volume mountPath: /config @@ -269,31 +324,24 @@ subjects: - name: gitlab-agent kind: ServiceAccount namespace: gitlab-agent - ``` -```shell -kubectl apply -n gitlab-agent -f ./resources.yml -``` +### Create a `manifest.yaml` + +In a previous step, you configured a `config.yaml` to point to the GitLab projects +the Agent should synchronize. In each of those projects, you must create a `manifest.yaml` +file for the Agent to monitor. You can auto-generate this `manifest.yaml` with a +templating engine or other means. + +Each time you commit and push a change to this file, the Agent logs the change: ```plaintext -$ kubectl get pods --all-namespaces -NAMESPACE NAME READY STATUS RESTARTS AGE -gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s -kube-system coredns-f9fd979d6-n6wcw 1/1 Running 0 14m -kube-system etcd-minikube 1/1 Running 0 14m -kube-system kube-apiserver-minikube 1/1 Running 0 14m -kube-system kube-controller-manager-minikube 1/1 Running 0 14m -kube-system kube-proxy-j6zdh 1/1 Running 0 14m -kube-system kube-scheduler-minikube 1/1 Running 0 14m -kube-system storage-provisioner 1/1 Running 0 14m +2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea ``` -### Creating a `manifest.yaml` - -In the above step, you configured a `config.yaml` to point to which GitLab projects the Agent should synchronize. Within each one of those projects, you need to create a `manifest.yaml` file which the Agent will monitor. This `manifest.yaml` can be autogenerated by a templating engine or other means. +#### Example `manifest.yaml` file -Example `manifest.yaml`: +This file creates a simple NGINX deployment. ```yaml apiVersion: apps/v1 @@ -318,14 +366,9 @@ spec: - containerPort: 80 ``` -The above file creates a simple NGINX deployment. - -Each time you commit and push a change to the `manifest.yaml` the Agent will observe the change. Example log: - -```plaintext -2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea -``` - ## Example projects -Basic GitOps example deploying NGINX: [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent), [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +This basic GitOps example deploys NGINX: + +- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) +- [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 2243ffa0cb1..4e0e2991acb 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -6,37 +6,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Managed Apps -GitLab provides **GitLab Managed Apps**, a one-click install for various applications which can -be added directly to your configured cluster. +GitLab provides **GitLab Managed Apps** for various +applications which can be added directly to your configured cluster. These +applications are needed for [Review Apps](../../ci/review_apps/index.md) and +[deployments](../../ci/environments/index.md) when using [Auto DevOps](../../topics/autodevops/index.md). +You can install them after you [create a cluster](../project/clusters/add_remove_clusters.md). GitLab provides +GitLab Managed Apps that can installed with [one-click](#install-with-one-click) or [using CI/CD](#install-using-gitlab-cicd-alpha). -These applications are needed for [Review Apps](../../ci/review_apps/index.md) -and [deployments](../../ci/environments/index.md) when using [Auto DevOps](../../topics/autodevops/index.md). +## Install with one click -You can install them after you -[create a cluster](../project/clusters/add_remove_clusters.md). - -## Installing applications - -Applications managed by GitLab will be installed onto the `gitlab-managed-apps` namespace. - -This namespace: +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 see a list of available applications to install. For a: +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. -NOTE: **Note:** -As of GitLab 11.6, Helm will be upgraded to the latest version supported -by GitLab before installing any of the applications. - -The following applications can be installed: +You can install the following applications with one click: - [Helm](#helm) - [Ingress](#ingress) @@ -49,27 +42,28 @@ The following applications can be installed: - [Elastic Stack](#elastic-stack) - [Fluentd](#fluentd) -With the exception of Knative, the applications will be installed in a dedicated +With the exception of Knative, the applications are installed in a dedicated namespace called `gitlab-managed-apps`. -NOTE: **Note:** 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). +For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411). CAUTION: **Caution:** If you have an existing Kubernetes cluster with Helm already installed, you should be careful as GitLab cannot detect it. In this case, installing -Helm via the applications will result in the cluster having it twice, which +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) since GitLab 13.2. +> - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 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 @@ -81,7 +75,6 @@ applications. Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issu GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` namespace. This server can now be safely removed. -NOTE: **Note:** GitLab's Helm integration does not support installing applications behind a proxy, but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) is available. @@ -90,26 +83,25 @@ is available. > 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 will issue a -certificate by [Let's Encrypt](https://letsencrypt.org/) and ensure that -certificates are valid and up-to-date. +[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) +- 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) +- GitLab 12.2 and older, the [`stable/cert-manager`](https://gi2wthub.com/helm/charts/tree/master/stable/cert-manager) chart was used. -If you have installed cert-manager prior to GitLab 12.3, Let's Encrypt will -[block requests from older versions of cert-manager](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753). - -To resolve this: +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. Uninstall cert-manager (consider [backing up any additional configuration](https://cert-manager.io/docs/tutorials/backup/)). +1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). +1. Uninstall cert-manager. 1. Install cert-manager again. ### GitLab Runner @@ -117,52 +109,52 @@ To resolve this: > - 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 is 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 are available -(the first 2000 minutes are free, you can -[buy more later](../../subscriptions/gitlab_com/index.md#purchase-additional-ci-minutes)) -and you do not have to deploy one if they are enough for your needs. If a -project-specific runner is desired, or there are no shared runners, it is easy -to deploy one. - -Note that the deployed runner will be set as **privileged**, which means it will essentially -have root access to the underlying machine. This is required to build Docker images, -so it is the default. Make sure you read the -[security implications](../project/clusters/index.md#security-implications) +[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. -NOTE: **Note:** 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. +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 +[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/), +The Ingress Controller installed is +[Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/), which is supported by the Kubernetes community. -NOTE: **Note:** 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. -In order to publish your web application, you first need to find the endpoint which will be either an IP +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 will attempt +To install it, click on the **Install** button for Ingress. GitLab attempts to determine the external endpoint and it should be available within a few minutes. #### Determining the external endpoint automatically @@ -178,22 +170,25 @@ using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: -1. Check your [Kubernetes cluster on Google Kubernetes Engine](https://console.cloud.google.com/kubernetes) 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. Check [Google Cloud's Status](https://status.cloud.google.com/) to ensure they are not having any disruptions. +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. -Once installed, 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). - -NOTE: **Note:** The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) chart is used to install this application with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) file. +After installing, you may see a `?` for **Ingress IP Address** depending on the +cloud provider. For EKS specifically, this is because the ELB is created +with a DNS name, not an IP address. If GitLab is still unable to +determine the endpoint of your Ingress or Knative application, you can +[determine it manually](#determining-the-external-endpoint-manually). + #### Determining the external endpoint manually If the cluster is on GKE, click the **Google Kubernetes Engine** link in the @@ -204,62 +199,62 @@ the `gcloud` command in a local terminal or using the **Cloud Shell**. If the cluster is not on GKE, follow the specific instructions for your Kubernetes provider to configure `kubectl` with the right credentials. -The output of the following examples will show the external endpoint of your +The output of the following examples show the external endpoint of your cluster. This information can then be used to set up DNS entries and forwarding rules that allow external access to your deployed applications. -If you installed Ingress via the **Applications**, run the following command: +- If you installed Ingress using the **Applications**, run the following + command: -```shell -kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' -``` + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' + ``` -Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: +- Some Kubernetes clusters return a hostname instead, like + [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: -```shell -kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' -``` + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' + ``` -For Istio/Knative, the command will be different: + If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) + is also created, which will incur additional AWS costs. -```shell -kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' -``` +- For Istio/Knative, the command is different: -Otherwise, you can list the IP addresses of all load balancers: + ```shell + kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` -```shell -kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' -``` +- Otherwise, you can list the IP addresses of all load balancers: -NOTE: **Note:** -If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) -will also be created, which will incur additional AWS costs. + ```shell + kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' + ``` -NOTE: **Note:** -You may see a trailing `%` on some Kubernetes versions, **do not include it**. +You may see a trailing `%` on some Kubernetes versions. Do not include it. -The Ingress is now available at this address and will route incoming requests to -the proper service based on the DNS name in the request. To support this, a -wildcard DNS CNAME record should be created for the desired domain name. For example, +The Ingress is now available at this address, and routes incoming requests to +the proper service based on the DNS name in the request. To support this, create +a wildcard DNS CNAME record for the desired domain name. For example, `*.myekscluster.com` would point to the Ingress hostname obtained earlier. #### Using a static IP By default, an ephemeral external IP address is associated to the cluster's load balancer. If you associate the ephemeral IP with your DNS and the IP changes, -your apps will not be able to be reached, and you'd have to change the DNS -record again. In order to avoid that, you should change it into a static -reserved IP. +your apps won't be reachable, and you'd have to change the DNS record again. +To avoid that, change it into a static reserved IP. Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). #### Pointing your DNS at the external endpoint -Once you've set up the external endpoint, you should associate it with a [wildcard DNS -record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) such as `*.example.com.` -in order to be able 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. +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) @@ -269,16 +264,15 @@ 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 +- 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. -Out of the box, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/). - -ModSecurity is a toolkit for real-time web application monitoring, logging, -and access control. With GitLab's offering, the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), -which provides generic attack detection capabilities, is automatically applied. +By default, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/), +which is a toolkit for real-time web application monitoring, logging, and access +control. GitLab's offering applies the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), +which provides generic attack detection capabilities. This feature: @@ -299,57 +293,61 @@ 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. Setting [the deployment variable](../../topics/autodevops/index.md) -`AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off`. This will prevent ModSecurity -from processing any requests for the given application or environment. - -1. Switching its respective toggle to the disabled position and applying changes through the **Save changes** button. This will reinstall -Ingress with the recent changes. +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](../../topics/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* 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. +- *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. [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md) if you have not already done so. +1. If you haven't already done so, [install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). 1. Navigate to **Operations > Kubernetes**. 1. In **Applications**, scroll to **Ingress**. 1. Under **Global default**, select your desired mode. -1. Click **Save changes**. +1. Select **Save changes**. ##### WAF version updates -Enabling, disabling, or changing the logging mode for **ModSecurity** is only allowed within same version of [Ingress](#ingress) due to limitations in [Helm](https://helm.sh/) which might be overcome in future releases. +Enabling, disabling, or changing the logging mode for **ModSecurity** is only +allowed within same version of [Ingress](#ingress) due to limitations in +[Helm](https://helm.sh/) which might be overcome in future releases. -**ModSecurity** UI controls are disabled if the version deployed differs from the one available in GitLab, while actions at the [Ingress](#ingress) level, such as uninstalling, can still be performed: +**ModSecurity** user interface controls are disabled if the version deployed +differs from the one available in GitLab, while actions at the [Ingress](#ingress) +level, such as uninstalling, can still be performed: ![WAF settings disabled](../../topics/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png) -Updating [Ingress](#ingress) to the most recent version enables you to take advantage of bug fixes, security fixes, and performance improvements. To update [Ingress application](#ingress), you must first uninstall it, and then re-install it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). +Update [Ingress](#ingress) to the most recent version to take advantage of bug +fixes, security fixes, and performance improvements. To update the +[Ingress application](#ingress), you must first uninstall it, and then re-install +it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). ##### Viewing Web Application Firewall traffic > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. You can view Web Application Firewall traffic by navigating to your project's -**Security & Compliance > Threat Monitoring** page. - -From there, you can see tracked over time: +**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 is considered anomalous by the Web Application +- The proportion of traffic that's considered anomalous by the Web Application Firewall's default [OWASP ruleset](https://www.modsecurity.org/CRS/Documentation/). -If a significant percentage of traffic is anomalous, it should be investigated -for potential threats, which can be done by -[examining the Web Application Firewall logs](#web-application-firewall-modsecurity). +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) @@ -358,55 +356,52 @@ for potential threats, which can be done by > - 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, +[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. -Authentication will be 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. - -We use a [custom Jupyter -image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) -that installs additional useful packages on top of the base Jupyter. You -will also see ready-to-use DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix). - -More information on -creating executable runbooks can be found in [our Runbooks -documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). Note that -Ingress must be installed and have an IP address assigned before -JupyterHub can be installed. - -NOTE: **Note:** The [`jupyter/jupyterhub`](https://jupyterhub.github.io/helm-chart/) chart is used to install this application with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/jupyter/values.yaml) file. +Authentication is enabled only for [project members](../project/members/index.md) +for project-level clusters and group members for group-level clusters with +[Developer or higher](../permissions.md) access to the associated project or group. + +GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) +that installs additional useful packages on top of the base Jupyter. Ready-to-use +DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix) +are also available. + +More information on creating executable runbooks can be found in +[our Runbooks documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). +Ingress must be installed and have an IP address assigned before +JupyterHub can be installed. + #### Jupyter Git Integration > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28783) in GitLab 12.0 for project-level clusters. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/32512) in GitLab 12.3 for group and instance-level clusters. -When installing JupyterHub onto your Kubernetes cluster, [JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) -is automatically provisioned and configured using the authenticated user's: +When installing JupyterHub onto your Kubernetes cluster, +[JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) +is provisioned and configured using the authenticated user's: - Name. - Email. - Newly created access token. -JupyterLab's Git extension enables full version control of your notebooks as well as issuance of Git commands within Jupyter. -Git commands can be issued via the **Git** tab on the left panel or via Jupyter's command line prompt. +JupyterLab's Git extension enables full version control of your notebooks, and +issuance of Git commands within Jupyter. You can issue Git commands through the +**Git** tab on the left panel, or through Jupyter's command-line prompt. -NOTE: **Note:** -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. This is 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. +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) @@ -421,22 +416,20 @@ You can clone repositories from the files tab in Jupyter: [Knative](https://cloud.google.com/knative/) provides a platform to create, deploy, and manage serverless workloads from a Kubernetes -cluster. It is used in conjunction with, and includes +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. -You will be prompted to enter a wildcard -domain where your applications will be exposed. Configure your DNS -server to use the external IP address for that domain. For any -application created and installed, they will be accessible as -`..`. This will require -your Kubernetes cluster to have [RBAC -enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). - -NOTE: **Note:** The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) chart is used to install this application. +During installation, you must enter a wildcard domain where your applications +will be exposed. Configure your DNS server to use the external IP address for that +domain. Applications created and installed are accessible as +`..`, 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. @@ -446,20 +439,19 @@ chart is used to install this application. open-source monitoring and alerting system useful to supervise your deployed applications. -GitLab is able to monitor applications automatically, using the +GitLab is able to monitor applications by using the [Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and -memory metrics are automatically collected, and response metrics are retrieved -from NGINX Ingress as well. +memory metrics are collected, and response metrics are also retrieved +from NGINX Ingress. -To enable monitoring, simply install Prometheus into the cluster with the -**Install** button. - -NOTE: **Note:** 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. @@ -481,17 +473,16 @@ The Crossplane GitLab-managed application: 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 via the Auto DevOps pipeline. + required by the application with the Auto DevOps pipeline. -For information on configuring Crossplane installed on the cluster, see -[Crossplane configuration](crossplane.md). - -NOTE: **Note:** [`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. @@ -500,37 +491,32 @@ file. log analysis solution which helps in deep searching, analyzing and visualizing the logs generated from different machines. -GitLab is able to gather logs from pods in your cluster automatically. -Filebeat will run as a DaemonSet on each node in your cluster, and it will ship container logs to Elasticsearch for querying. -GitLab will then connect to Elasticsearch for logs instead of the Kubernetes API, -and you will have access to more advanced querying capabilities. +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). -Log data is automatically deleted after 30 days using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). +The Elastic Stack cluster application is intended as a log aggregation solution +and is not related to our [Advanced Search](../search/advanced_global_search.md) +functionality, which uses a separate Elasticsearch cluster. To enable log shipping: -1. Ensure your cluster contains at least 3 nodes of instance types larger than - `f1-micro`, `g1-small`, or `n1-standard-1`. +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 click **Install**. +1. In the **Applications** section, find **Elastic Stack**, and then select + **Install**. -NOTE: **Note:** 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. - -NOTE: **Note:** -The chart deploys 3 identical Elasticsearch pods which can't be colocated, and each -requires 1 CPU and 2 GB of RAM, making them incompatible with clusters containing -fewer than 3 nodes or consisting of `f1-micro`, `g1-small`, `n1-standard-1`, or -`*-highcpu-2` instance types. - -NOTE: **Note:** -The Elastic Stack cluster application is intended as a log aggregation solution and is not related to our -[Advanced Search](../search/advanced_global_search.md) functionality, which uses a separate -Elasticsearch cluster. +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 @@ -578,8 +564,8 @@ your data. Fluentd sends logs in syslog format. To enable Fluentd: 1. Navigate to **Operations > Kubernetes** and click - **Applications**. You will be prompted to enter a host, port and protocol - where the WAF logs will be sent to via syslog. + **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**. @@ -599,7 +585,7 @@ to get started. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. CAUTION: **Warning:** -This is an _alpha_ feature, and it is subject to change at any time without +This is an _alpha_ feature, and is subject to change at any time without prior notice. This alternative method allows users to install GitLab-managed @@ -639,7 +625,6 @@ To install applications using GitLab CI/CD: - template: Managed-Cluster-Applications.gitlab-ci.yml ``` - NOTE: **Note:** The job provided by this template connects to the cluster using tools provided in a custom Docker image. It requires that you have a runner registered with the Docker, Kubernetes, or Docker Machine executor. @@ -657,11 +642,10 @@ To install applications using GitLab CI/CD: 1. Optionally, define `.gitlab/managed-apps//values.yaml` file to customize values for the installed application. -A GitLab CI/CD pipeline will then run on the `master` branch to install the +A GitLab CI/CD pipeline runs on the `master` branch to install the applications you have configured. In case of pipeline failure, the -output of the [Helm -Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary -will be saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). +output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary +is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). ### Important notes @@ -669,10 +653,10 @@ Note the following: - We recommend using the cluster management project exclusively for managing deployments to a cluster. Do not add your application's source code to such projects. -- When you set the value for `installed` key back to `false`, the application will be +- When you set the value for `installed` key back to `false`, the application is unprovisioned from the cluster. - If you update `.gitlab/managed-apps//values.yaml` with new values, the - application will be redeployed. + application is redeployed. ### Install Ingress using GitLab CI/CD @@ -684,7 +668,7 @@ ingress: installed: true ``` -Ingress will then be installed into the `gitlab-managed-apps` namespace +Ingress is installed into the `gitlab-managed-apps` namespace of your cluster. You can customize the installation of Ingress by defining a @@ -693,9 +677,10 @@ management project. Refer to the [chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress) for the available configuration options. -NOTE: **Note:** Support for installing the Ingress managed application is provided by the GitLab Configure group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), +and ping at least 2 people from the +[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). ### Install cert-manager using GitLab CI/CD @@ -705,7 +690,8 @@ cert-manager is installed using GitLab CI/CD by defining configuration in cert-manager: - Is installed into the `gitlab-managed-apps` namespace of your cluster. -- Can be installed with or without a default [Let's Encrypt `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/), which requires an +- Can be installed with or without a default + [Let's Encrypt `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/), which requires an email address to be specified. The email address is used by Let's Encrypt to contact you about expiring certificates and issues related to your account. @@ -734,14 +720,16 @@ management project. Refer to the [chart](https://hub.helm.sh/charts/jetstack/cert-manager) for the available configuration options. -NOTE: **Note:** -Support for installing the Cert Manager managed application is provided by the GitLab Configure group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +Support for installing the Cert Manager managed application is provided by the +GitLab Configure group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). ### Install Sentry using GitLab CI/CD -NOTE: **Note:** -The Sentry Helm chart [recommends](https://github.com/helm/charts/blob/f6e5784f265dd459c5a77430185d0302ed372665/stable/sentry/values.yaml#L284-L285) at least 3GB of available RAM for database migrations. +The Sentry Helm chart [recommends](https://github.com/helm/charts/blob/f6e5784f265dd459c5a77430185d0302ed372665/stable/sentry/values.yaml#L284-L285) +at least 3 GB of available RAM for database migrations. To install Sentry, define the `.gitlab/managed-apps/config.yaml` file with: @@ -751,7 +739,7 @@ sentry: installed: true ``` -Sentry will then be installed into the `gitlab-managed-apps` namespace +Sentry is installed into the `gitlab-managed-apps` namespace of your cluster. You can customize the installation of Sentry by defining @@ -766,8 +754,10 @@ We recommend you pay close attention to the following configuration options: - `user`. Where you can set the login credentials for the default admin user. - `postgresql`. For a PostgreSQL password that can be used when running future updates. -NOTE: **Note:** -When upgrading it is important to provide the existing PostgreSQL password (given using the `postgresql.postgresqlPassword` key) or you will receive authentication errors. See the [PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade) for more information. +When upgrading, it's important to provide the existing PostgreSQL password (given +using the `postgresql.postgresqlPassword` key) to avoid authentication errors. +Read the [PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade) +for more information. Here is an example configuration for Sentry: @@ -799,9 +789,11 @@ postgresql: postgresqlPassword: example-postgresql-password ``` -NOTE: **Note:** -Support for installing the Sentry managed application is provided by the GitLab Health group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Health group](https://about.gitlab.com/handbook/product/product-categories/#health-group). +Support for installing the Sentry managed application is provided by the +GitLab Health group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Health group](https://about.gitlab.com/handbook/product/product-categories/#health-group). ### Install PostHog using GitLab CI/CD @@ -816,13 +808,14 @@ posthog: ``` You can customize the installation of PostHog by defining `.gitlab/managed-apps/posthog/values.yaml` -in your cluster management project. Refer to the [Configuration section of the PostHog chart's README](https://github.com/PostHog/charts/tree/master/charts/posthog) +in your cluster management project. Refer to the +[Configuration section of the PostHog chart's README](https://github.com/PostHog/charts/tree/master/charts/posthog) for the available configuration options. -NOTE: **Note:** You must provide a PostgreSQL password in `postgresql.postgresqlPassword` -or you will receive authentication errors. -See the [PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade) for more information. +to avoid authentication errors. Read the +[PostgreSQL chart documentation](https://github.com/helm/charts/tree/master/stable/postgresql#upgrade) +for more information. Redis pods are restarted between upgrades. To prevent downtime, provide a Redis password using the `redis.password` key. This prevents a new password from @@ -848,9 +841,9 @@ redis: password: example-redis-password ``` -NOTE: **Note:** Support for the PostHog managed application is provided by the PostHog team. -If you run into issues, please [open a support ticket](https://github.com/PostHog/posthog/issues/new/choose) directly. +If you run into issues, +[open a support ticket](https://github.com/PostHog/posthog/issues/new/choose) directly. ### Install Prometheus using GitLab CI/CD @@ -874,9 +867,10 @@ project. Refer to the [Configuration section of the Prometheus chart's README](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) for the available configuration options. -NOTE: **Note:** -Support for installing the Prometheus managed application is provided by the GitLab APM group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). +Support for installing the Prometheus managed application is provided by the +GitLab APM group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). ### Install GitLab Runner using GitLab CI/CD @@ -892,16 +886,17 @@ gitlabRunner: GitLab Runner is installed into the `gitlab-managed-apps` namespace of your cluster. -In order for GitLab Runner to function, you **must** specify the following: +For GitLab Runner to function, you _must_ specify the following: -- `gitlabUrl` - the GitLab server full URL (for example, `https://gitlab.example.com`) to register the Runner against. -- `runnerRegistrationToken` - The registration token for adding new runners to GitLab. This must be - [retrieved from your GitLab instance](../../ci/runners/README.md). +- `gitlabUrl`: The GitLab server full URL (for example, `https://gitlab.example.com`) + to register the Runner against. +- `runnerRegistrationToken`: The registration token for adding new runners to GitLab. + This must be [retrieved from your GitLab instance](../../ci/runners/README.md). These values can be specified using [CI variables](../../ci/variables/README.md): -- `GITLAB_RUNNER_GITLAB_URL` will be used for `gitlabUrl`. -- `GITLAB_RUNNER_REGISTRATION_TOKEN` will be used for `runnerRegistrationToken` +- `GITLAB_RUNNER_GITLAB_URL` is used for `gitlabUrl`. +- `GITLAB_RUNNER_REGISTRATION_TOKEN` is used for `runnerRegistrationToken` You can customize the installation of GitLab Runner by defining `.gitlab/managed-apps/gitlab-runner/values.yaml` file in your cluster @@ -909,9 +904,11 @@ management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/gitlab-runner) for the available configuration options. -NOTE: **Note:** -Support for installing the GitLab Runner managed application is provided by the GitLab Runner group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Runner group](https://about.gitlab.com/handbook/product/product-categories/#runner-group). +Support for installing the GitLab Runner managed application is provided by the +GitLab Runner group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Runner group](https://about.gitlab.com/handbook/product/product-categories/#runner-group). ### Install Cilium using GitLab CI/CD @@ -948,8 +945,10 @@ 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. -- [Group-level cluster](../group/clusters/index.md): Navigate to your group's **Kubernetes** page. +- [Project-level cluster](../project/clusters/index.md): Navigate to your project's + **Operations > Kubernetes** page. +- [Group-level cluster](../group/clusters/index.md): Navigate to your group's + **Kubernetes** page. CAUTION: **Caution:** Installation and removal of the Cilium requires a **manual** @@ -959,12 +958,11 @@ of all affected pods in all namespaces to ensure that they are by the correct networking plugin. NOTE: **Note:** -Major upgrades might require additional setup steps, please consult -the official [upgrade guide](https://docs.cilium.io/en/stable/install/upgrade/) for more -information. +Major upgrades might require additional setup steps. For more information, see +the official [upgrade guide](https://docs.cilium.io/en/stable/install/upgrade/). -By default, Cilium's [audit -mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/?highlight=policy-audit#enable-policy-audit-mode) +By default, Cilium's +[audit mode](https://docs.cilium.io/en/v1.8/gettingstarted/policy-creation/?highlight=policy-audit#enable-policy-audit-mode) is enabled. In audit mode, Cilium doesn't drop disallowed packets. You can use `policy-verdict` log to observe policy-related decisions. You can disable audit mode by adding the following to @@ -1006,7 +1004,7 @@ global: enabled: false ``` -You can also adjust Helm values for Hubble via +You can also adjust Helm values for Hubble by using `.gitlab/managed-apps/cilium/values.yaml`: ```yaml @@ -1018,9 +1016,11 @@ global: - 'flow:sourceContext=namespace;destinationContext=namespace' ``` -NOTE: **Note:** -Support for installing the Cilium managed application is provided by the GitLab Container Security group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +Support for installing the Cilium managed application is provided by the +GitLab Container Security group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). ### Install Falco using GitLab CI/CD @@ -1046,17 +1046,20 @@ management project. Refer to the for the available configuration options. CAUTION: **Caution:** -By default eBPF support is enabled and Falco will use an [eBPF probe](https://falco.org/docs/event-sources/drivers/#using-the-ebpf-probe) to pass system calls to userspace. -If your cluster doesn't support this, you can configure it to use Falco kernel module instead by adding the following to `.gitlab/managed-apps/falco/values.yaml`: +By default eBPF support is enabled and Falco uses an +[eBPF probe](https://falco.org/docs/event-sources/drivers/#using-the-ebpf-probe) +to pass system calls to user space. If your cluster doesn't support this, you can +configure it to use Falco kernel module instead by adding the following to +`.gitlab/managed-apps/falco/values.yaml`: ```yaml ebpf: enabled: false ``` -In rare cases where automatic probe installation on your cluster isn't possible and the kernel/probe -isn't precompiled, you may need to manually prepare the kernel module or eBPF probe with -[driverkit](https://github.com/falcosecurity/driverkit#against-a-kubernetes-cluster) +In rare cases where probe installation on your cluster isn't possible and the kernel/probe +isn't pre-compiled, you may need to manually prepare the kernel module or eBPF probe with +[`driverkit`](https://github.com/falcosecurity/driverkit#against-a-kubernetes-cluster) and install it on each cluster node. By default, Falco is deployed with a limited set of rules. To add more rules, add the following to @@ -1109,22 +1112,27 @@ You can check these logs with the following command: kubectl -n gitlab-managed-apps logs -l app=falco ``` -NOTE: **Note:** -Support for installing the Falco managed application is provided by the GitLab Container Security group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +Support for installing the Falco managed application is provided by the +GitLab Container Security group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). ### Install Vault using GitLab CI/CD > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9982) in GitLab 12.9. -[Hashicorp Vault](https://www.vaultproject.io/) is a secrets management solution which -can be used to safely manage and store passwords, credentials, certificates and more. A Vault +[HashiCorp Vault](https://www.vaultproject.io/) is a secrets management solution which +can be used to safely manage and store passwords, credentials, certificates, and more. A Vault installation could be leveraged to provide a single secure data store for credentials used in your applications, GitLab CI/CD jobs, and more. It could also serve as a way of providing SSL/TLS certificates to systems and deployments in your infrastructure. Leveraging Vault as a single source for all these credentials allows greater security by having a single source of access, control, and auditability around all your sensitive -credentials and certificates. +credentials and certificates. This feature requires giving GitLab the highest level of access and +control. Therefore, if GitLab is compromised, the security of this Vault instance is as well. To +avoid this security risk, GitLab recommends using your own HashiCorp Vault to leverage +[external secrets with CI](../../ci/secrets/index.md). To install Vault, enable it in the `.gitlab/managed-apps/config.yaml` file: @@ -1133,24 +1141,25 @@ vault: installed: true ``` -By default you will get a basic Vault setup with no scalable -storage backend. This is enough for simple testing and small-scale deployments, though has limits -to how much it can scale, and as it is a single instance deployment, you will experience downtime -when upgrading the Vault application. +By default you receive a basic Vault setup with no scalable storage backend. This +is enough for simple testing and small-scale deployments, though has limits +to how much it can scale, and as it's a single instance deployment, upgrading the +Vault application causes downtime. To optimally use Vault in a production environment, it's ideal to have a good understanding -of the internals of Vault and how to configure it. This can be done by reading the -[the Vault documentation](https://www.vaultproject.io/docs/internals) as well as +of the internals of Vault and how to configure it. This can be done by reading +the [Vault Configuration guide](../../ci/secrets/#configure-your-vault-server), +the [Vault documentation](https://www.vaultproject.io/docs/internals) and the Vault Helm chart [`values.yaml` file](https://github.com/hashicorp/vault-helm/blob/v0.3.3/values.yaml). -At a minimum you will likely set up: +At a minimum, most users set up: - A [seal](https://www.vaultproject.io/docs/configuration/seal) for extra encryption - of the master key. -- A [storage backend](https://www.vaultproject.io/docs/configuration/storage) that is + of the main key. +- A [storage backend](https://www.vaultproject.io/docs/configuration/storage) that's suitable for environment and storage security requirements. - [HA Mode](https://www.vaultproject.io/docs/concepts/ha). -- [The Vault UI](https://www.vaultproject.io/docs/configuration/ui). +- The [Vault UI](https://www.vaultproject.io/docs/configuration/ui). The following is an example values file (`.gitlab/managed-apps/vault/values.yaml`) that configures Google Key Management Service for auto-unseal, using a Google Cloud Storage backend, enabling @@ -1180,7 +1189,7 @@ server: path = "gcs://my-vault-storage/vault-bucket" ha_enabled = "true" } - # Configure Vault to automatically unseal storage using a GKMS key + # Configure Vault to unseal storage using a GKMS key seal "gcpckms" { project = "vault-helm-dev-246514" region = "global" @@ -1189,10 +1198,13 @@ server: } ``` -Once you have successfully installed Vault, you will need to [initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault) -and obtain the initial root token. You will need access to your Kubernetes cluster that Vault has been deployed into in order to do this. -To initialize the Vault, get a shell to one of the Vault pods running inside Kubernetes (typically this is done by using the `kubectl` command line tool). -Once you have a shell into the pod, run the `vault operator init` command: +Once you have successfully installed Vault, you must +[initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault) +and obtain the initial root token. You need access to your Kubernetes cluster that +Vault has been deployed into in order to do this. To initialize the Vault, get a +shell to one of the Vault pods running inside Kubernetes (typically this is done +by using the `kubectl` command line tool). Once you have a shell into the pod, +run the `vault operator init` command: ```shell kubectl -n gitlab-managed-apps exec -it vault-0 sh @@ -1200,11 +1212,13 @@ kubectl -n gitlab-managed-apps exec -it vault-0 sh ``` This should give you your unseal keys and initial root token. Make sure to note these down -and keep these safe as you will need them to unseal the Vault throughout its lifecycle. +and keep these safe, as they're required to unseal the Vault throughout its lifecycle. -NOTE: **Note:** -Support for installing the Vault managed application is provided by the GitLab Release Management group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Release Management group](https://about.gitlab.com/handbook/product/product-categories/#release-management-group). +Support for installing the Vault managed application is provided by the +GitLab Release Management group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Release Management group](https://about.gitlab.com/handbook/product/product-categories/#release-management-group). ### Install JupyterHub using GitLab CI/CD @@ -1224,7 +1238,7 @@ In the configuration: - `gitlabProjectIdWhitelist` restricts GitLab authentication to only members of the specified projects. - `gitlabGroupWhitelist` restricts GitLab authentication to only members of the specified groups. -- Specifying an empty array for both will allow any user on the GitLab instance to sign in. +- Specifying an empty array for both allows any user on the GitLab instance to sign in. JupyterHub is installed into the `gitlab-managed-apps` namespace of your cluster. @@ -1236,17 +1250,19 @@ Set: In addition, the following variables must be specified using [CI variables](../../ci/variables/README.md): -| CI Variable | Description | -|:---------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `JUPYTERHUB_PROXY_SECRET_TOKEN` | Secure string used for signing communications from the hub. See[`proxy.secretToken`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#proxy-secrettoken). | -| `JUPYTERHUB_COOKIE_SECRET` | Secure string used for signing secure cookies. See [`hub.cookieSecret`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#hub-cookiesecret). | -| `JUPYTERHUB_HOST` | Hostname used for the installation. For example, `jupyter.gitlab.example.com`. | -| `JUPYTERHUB_GITLAB_HOST` | Hostname of the GitLab instance used for authentication. For example, `gitlab.example.com`. | -| `JUPYTERHUB_AUTH_CRYPTO_KEY` | A 32-byte encryption key used to set [`auth.state.cryptoKey`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#auth-state-cryptokey). | -| `JUPYTERHUB_AUTH_GITLAB_CLIENT_ID` | "Application ID" for the OAuth Application. | -| `JUPYTERHUB_AUTH_GITLAB_CLIENT_SECRET` | "Secret" for the OAuth Application. | - -By default, JupyterHub will be installed using a +- `JUPYTERHUB_PROXY_SECRET_TOKEN` - Secure string used for signing communications + from the hub. Read [`proxy.secretToken`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#proxy-secrettoken). +- `JUPYTERHUB_COOKIE_SECRET` - Secure string used for signing secure cookies. Read + [`hub.cookieSecret`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#hub-cookiesecret). +- `JUPYTERHUB_HOST` - Hostname used for the installation. For example, `jupyter.gitlab.example.com`. +- `JUPYTERHUB_GITLAB_HOST` - Hostname of the GitLab instance used for authentication. + For example, `gitlab.example.com`. +- `JUPYTERHUB_AUTH_CRYPTO_KEY` - A 32-byte encryption key used to set + [`auth.state.cryptoKey`](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html#auth-state-cryptokey). +- `JUPYTERHUB_AUTH_GITLAB_CLIENT_ID` - "Application ID" for the OAuth Application. +- `JUPYTERHUB_AUTH_GITLAB_CLIENT_SECRET` - "Secret" for the OAuth Application. + +By default, JupyterHub is installed using a [default values file](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/blob/master/src/default-data/jupyterhub/values.yaml.gotmpl). You can customize the installation of JupyterHub by defining a `.gitlab/managed-apps/jupyterhub/values.yaml` file in your cluster management project. @@ -1255,9 +1271,11 @@ Refer to the [chart reference](https://zero-to-jupyterhub.readthedocs.io/en/stable/reference/reference.html) for the available configuration options. -NOTE: **Note:** Support for installing the JupyterHub managed application is provided by the GitLab Configure group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). ### Install Elastic Stack using GitLab CI/CD @@ -1275,20 +1293,25 @@ elasticStack: Elastic Stack is installed into the `gitlab-managed-apps` namespace of your cluster. -You can check the default [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/elastic_stack/values.yaml) we set for this chart. +You can check the default +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/vendor/elastic_stack/values.yaml) +we set for this chart. You can customize the installation of Elastic Stack by defining `.gitlab/managed-apps/elastic-stack/values.yaml` file in your cluster management project. Refer to the -[chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for the +[chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all available configuration options. NOTE: **Note:** -In this alpha implementation of installing Elastic Stack through CI, reading the environment logs through Elasticsearch is unsupported. This is supported if [installed via the UI](#elastic-stack). +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). -NOTE: **Note:** -Support for installing the Elastic Stack managed application is provided by the GitLab APM group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). +Support for installing the Elastic Stack managed application is provided by the +GitLab APM group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). ### Install Crossplane using GitLab CI/CD @@ -1316,37 +1339,40 @@ management project. Refer to the [chart](https://github.com/crossplane/crossplane/tree/master/cluster/charts/crossplane#configuration) for the available configuration options. Note that this link points to the documentation for the current development release, which may differ from the version you have installed. -NOTE: **Note:** Support for the Crossplane managed application is provided by the Crossplane team. -If you run into issues, please [open a support ticket](https://github.com/crossplane/crossplane/issues/new/choose) directly. +If you run into issues, +[open a support ticket](https://github.com/crossplane/crossplane/issues/new/choose) directly. ### Install Fluentd using GitLab CI/CD > [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/76) in GitLab 12.10. -To install Fluentd into the `gitlab-managed-apps` namespace of your cluster using GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`: +To install Fluentd into the `gitlab-managed-apps` namespace of your cluster using +GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`: ```yaml Fluentd: installed: true ``` -You can also review the default values set for this chart in the [`values.yaml`](https://github.com/helm/charts/blob/master/stable/fluentd/values.yaml) file. +You can also review the default values set for this chart in the +[`values.yaml`](https://github.com/helm/charts/blob/master/stable/fluentd/values.yaml) file. You can customize the installation of Fluentd by defining `.gitlab/managed-apps/fluentd/values.yaml` file in your cluster management project. Refer to the [configuration chart for the current development release of Fluentd](https://github.com/helm/charts/tree/master/stable/fluentd#configuration) -for the available configuration options. +for all available configuration options. -NOTE: **Note:** The configuration chart link points to the current development release, which may differ from the version you have installed. To ensure compatibility, switch to the specific branch or tag you are using. -NOTE: **Note:** -Support for installing the Fluentd managed application is provided by the GitLab Container Security group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +Support for installing the Fluentd managed application is provided by the +GitLab Container Security group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). ### Install Knative using GitLab CI/CD @@ -1360,7 +1386,7 @@ knative: You can customize the installation of Knative by defining `.gitlab/managed-apps/knative/values.yaml` file in your cluster management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/knative) -for the available configuration options. +for all available configuration options. Here is an example configuration for Knative: @@ -1368,11 +1394,14 @@ Here is an example configuration for Knative: domain: 'my.wildcard.A.record.dns' ``` -If you plan to use GitLab Serverless capabilities, be sure to set an A record wildcard domain on your custom configuration. +If you plan to use GitLab Serverless capabilities, be sure to set an `A record` +wildcard domain on your custom configuration. -NOTE: **Note:** -Support for installing the Knative managed application is provided by the GitLab Configure group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +Support for installing the Knative managed application is provided by the +GitLab Configure group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at +least 2 people from the +[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). #### Knative Metrics @@ -1398,14 +1427,16 @@ kubectl delete -f https://gitlab.com/gitlab-org/cluster-integration/cluster-appl > [Introduced](https://gitlab.com/gitlab-org/cluster-integration/cluster-applications/-/merge_requests/100) in GitLab 13.1. -To install AppArmor into the `gitlab-managed-apps` namespace of your cluster using GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`: +To install AppArmor into the `gitlab-managed-apps` namespace of your cluster using +GitLab CI/CD, define the following configuration in `.gitlab/managed-apps/config.yaml`: ```yaml apparmor: installed: true ``` -You can define one or more AppArmor profiles by adding them into `.gitlab/managed-apps/apparmor/values.yaml` as the following: +You can define one or more AppArmor profiles by adding them into +`.gitlab/managed-apps/apparmor/values.yaml` as the following: ```yaml profiles: @@ -1419,25 +1450,27 @@ Refer to the [AppArmor chart](https://gitlab.com/gitlab-org/charts/apparmor) for #### Using AppArmor profiles in your deployments -After installing AppAmor, you can use profiles by adding Pod Annotations. If you're using Auto -DevOps, you can [customize `auto-deploy-values.yaml`](../../topics/autodevops/customize.md#customize-values-for-helm-chart) -to annotate your pods. Although it's helpful to be aware of the [list of custom attributes](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app#gitlabs-auto-deploy-helm-chart), you're only required to set -`podAnnotations` as follows: +After installing AppAmor, you can use profiles by adding Pod Annotations. If you're using +Auto DevOps, you can [customize `auto-deploy-values.yaml`](../../topics/autodevops/customize.md#customize-values-for-helm-chart) +to annotate your pods. Although it's helpful to be aware of the +[list of custom attributes](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app#gitlabs-auto-deploy-helm-chart), +you're only required to set `podAnnotations` as follows: ```yaml podAnnotations: container.apparmor.security.beta.kubernetes.io/auto-deploy-app: localhost/profile-one ``` -The only information to be changed here is the profile name which is `profile-one` in this example. Refer to the [AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) for more information on how AppArmor is integrated in Kubernetes. +The only information to be changed here is the profile name which is `profile-one` +in this example. Refer to the [AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) +for more information on how AppArmor is integrated in Kubernetes. #### Using PodSecurityPolicy in your deployments -NOTE: **Note:** To enable AppArmor annotations on a Pod Security Policy you must first -load the correspondingAppArmor profile. +load the corresponding AppArmor profile. -[Pod Security Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/)are +[Pod Security Policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) are resources at the cluster level that control security-related properties of deployed pods. You can use such a policy to enable loaded AppArmor profiles and apply necessary pod restrictions across a @@ -1465,14 +1498,14 @@ securityPolicies: - '*' ``` -This example creates a single policy named `example` with the provided -specification, and enables [AppArmor -annotations](https://kubernetes.io/docs/tutorials/clusters/apparmor/#podsecuritypolicy-annotations)on -it. +This example creates a single policy named `example` with the provided specification, +and enables [AppArmor annotations](https://kubernetes.io/docs/tutorials/clusters/apparmor/#podsecuritypolicy-annotations) on it. -NOTE: **Note:** -Support for installing the AppArmor managed application is provided by the GitLab Container Security group. -If you run into unknown issues, please [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) and ping at least 2 people from the [Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +Support for installing the AppArmor managed application is provided by the +GitLab Container Security group. If you run into unknown issues, +[open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping +at least 2 people from the +[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). ## Browse applications logs @@ -1500,9 +1533,7 @@ To upgrade an application: 1. Select your cluster. 1. If an upgrade is available, the **Upgrade** button is displayed. Click the button to upgrade. -NOTE: **Note:** -Upgrades will reset values back to the values built into the `runner` -chart plus the values set by +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 @@ -1513,16 +1544,16 @@ The applications below can be uninstalled. | Application | GitLab version | Notes | | ----------- | -------------- | ----- | -| cert-manager | 12.2+ | The associated private key will be deleted and cannot be restored. Deployed applications will continue to use HTTPS, but certificates will not be renewed. Before uninstalling, you may wish 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 will be canceled. | -| Helm | 12.2+ | The associated Tiller pod, the `gitlab-managed-apps` namespace, and all of its resources will be deleted and cannot be restored. | -| Ingress | 12.1+ | The associated load balancer and IP will be 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 will be deleted and cannot be restored. | -| Knative | 12.1+ | The associated IP will be deleted and cannot be restored. | -| Prometheus | 11.11+ | All data will be deleted and cannot be restored. | -| Crossplane | 12.5+ | All data will be deleted and cannot be restored. | -| Elastic Stack | 12.7+ | All data will be deleted and cannot be restored. | -| Sentry | 12.6+ | The PostgreSQL persistent volume will remain and should be manually removed for complete uninstall. | +| 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: @@ -1535,8 +1566,7 @@ To uninstall an application: 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). +To follow progress, see the [relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/1201). ## Troubleshooting applications @@ -1550,9 +1580,10 @@ 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. +- 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 via `kubectl`: + You can confirm that the certificates match by using `kubectl`: ```shell kubectl get configmaps/values-content-configuration-ingress -n gitlab-managed-apps -o \ @@ -1590,5 +1621,5 @@ Installing Prometheus is failing with the following error: 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, you'll need -to make sure that [`cert-manager`](#cert-manager) is installed successfully prior to installing Prometheus. +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. diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md new file mode 100644 index 00000000000..f13be15c6bc --- /dev/null +++ b/doc/user/clusters/cost_management.md @@ -0,0 +1,74 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Cluster cost management **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216737) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.5. + +Cluster cost management provides insights into cluster resource usage. GitLab provides an example +[`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) +project that uses GitLab's Prometheus integration and +[Kubecost's `cost-model`](https://github.com/kubecost/cost-model) to provide cluster cost +insights within GitLab: + +![Example dashboard](img/kubecost_v13_5.png) + +## Configure cluster cost management + +To get started with cluster cost management, you need [Maintainer](../permissions.md) +permissions in a project or group. + +1. Clone the [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) + example repository, which contains minor modifications to the upstream Kubecost + `cost-model` project: + - Configures your Prometheus endpoint to the GitLab-managed Prometheus. You may + need to change this value if you use a non-managed Prometheus. + - Adds the necessary annotations to the deployment manifest to be scraped by + GitLab-managed Prometheus. + - Changes the Google Pricing API access key to GitLab's access key. + - Contains definitions for a custom GitLab Metrics dashboard to show the cost insights. +1. Connect GitLab with Prometheus, depending on your configuration: + - *If Prometheus is already configured,* navigate to **Settings > Integrations > Prometheus** + 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. +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. + - *To deploy it manually*, use the following commands: + + ```shell + kubectl create namespace cost-model + kubectl apply -f kubernetes/ --namespace cost-model + ``` + +To access the cost insights, navigate to **Operations > Metrics** and select +the `default_costs.yml` dashboard. You can [customize](#customize-the-cost-dashboard) +this dashboard. + +### Customize the cost dashboard + +You can customize the cost dashboard by editing the `.gitlab/dashboards/default_costs.yml` +file or creating similar dashboard configuration files. To learn more, read about +[customizing dashboards in our documentation](/ee/operations/metrics/dashboards/). + +#### Available metrics + +Metrics contain both instance and node labels. The instance label will be deprecated in a future version. + +- `node_cpu_hourly_cost` - Hourly cost per vCPU on this node. +- `node_gpu_hourly_cost` - Hourly cost per GPU on this node. +- `node_ram_hourly_cost` - Hourly cost per gigabyte of memory on this node. +- `node_total_hourly_cost` - Total node cost per hour. +- `container_cpu_allocation` - Average number of CPUs requested/used over the previous minute. +- `container_gpu_allocation` - Average number of GPUs requested over the previous minute. +- `container_memory_allocation_bytes` - Average bytes of RAM requested/used over the previous minute. +- `pod_pvc_allocation` - Bytes provisioned for a PVC attached to a pod. +- `pv_hourly_cost` - Hourly cost per GB on a persistent volume. + +Some examples are provided in the +[`kubecost-cost-model` repository](https://gitlab.com/gitlab-examples/kubecost-cost-model/-/blob/master/PROMETHEUS.md#example-queries). diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index b30ebc57338..8463917f2f3 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -78,7 +78,6 @@ provided can manage resources in the `database.crossplane.io` API group: See [Configure Your Cloud Provider Account](https://crossplane.github.io/docs/v0.4/cloud-providers.html) to configure the installed cloud provider stack with a user account. -NOTE: **Note:** The Secret, and the Provider resource referencing the Secret, must be applied to the `gitlab-managed-apps` namespace in the guide. Make sure you change that while following the process. diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 2b342ceb06d..3ab20c5466e 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -43,6 +43,5 @@ Once you have successful deployments to your group-level or instance-level clust 1. Navigate to your group's **Kubernetes** page. 1. Click on the **Environments** tab. -NOTE: **Note:** -Only successful deployments to the cluster is included in this page. -Non-cluster environments will not be included. +Only successful deployments to the cluster are included in this page. +Non-cluster environments aren't included. diff --git a/doc/user/clusters/img/kubecost_v13_5.png b/doc/user/clusters/img/kubecost_v13_5.png new file mode 100644 index 00000000000..a93e2531b16 Binary files /dev/null and b/doc/user/clusters/img/kubecost_v13_5.png differ diff --git a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png index a06f8812b41..89f4e917567 100644 Binary files a/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png and b/doc/user/compliance/compliance_dashboard/img/compliance_dashboard_v13_3_1.png differ diff --git a/doc/user/compliance/license_compliance/img/license-check_v13_4.png b/doc/user/compliance/license_compliance/img/license-check_v13_4.png index d3658cbaa18..bc80f938395 100644 Binary files a/doc/user/compliance/license_compliance/img/license-check_v13_4.png and b/doc/user/compliance/license_compliance/img/license-check_v13_4.png differ diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md index 79c2d97b972..894c0e14862 100644 --- a/doc/user/compliance/license_compliance/index.md +++ b/doc/user/compliance/license_compliance/index.md @@ -121,12 +121,17 @@ The results will be saved as a [License Compliance report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportslicense_scanning) that you can later download and analyze. Due to implementation limitations, we always take the latest License Compliance artifact available. Behind the scenes, the -[GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/license-management) +[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 [environment variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. +### When License Compliance runs + +When using the GitLab `License-Scanning.gitlab-ci.yml` template, the License Compliance job doesn't +wait for other stages to complete. + ### Available variables License Compliance can be configured using environment variables. @@ -446,7 +451,7 @@ package manager. For a comprehensive list, consult [the Conan documentation](htt The default [Conan](https://conan.io/) configuration sets [`CONAN_LOGIN_USERNAME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) to `ci_user`, and binds [`CONAN_PASSWORD`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-password-conan-password-remote-name) to the [`CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md) -for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/#fetching-conan-package-information-from-the-gitlab-package-registry) +for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/#fetch-conan-package-information-from-the-package-registry) if a GitLab remote is specified in the `.conan/remotes.json` file. To override the default credentials specify a [`CONAN_LOGIN_USERNAME_{REMOTE_NAME}`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name) @@ -629,7 +634,7 @@ import the following default License Compliance analyzer images from `registry.g offline [local Docker container registry](../../packages/container_registry/index.md): ```plaintext -registry.gitlab.com/gitlab-org/security-products/license-management:latest +registry.gitlab.com/gitlab-org/security-products/analyzers/license-finder:latest ``` The process for importing Docker images into a local offline Docker registry depends on diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 67dd31efe2c..ec0c207e190 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -38,6 +38,14 @@ The IP address for `mg.gitlab.com` is subject to change at any time. [See our backup strategy](https://about.gitlab.com/handbook/engineering/infrastructure/production/#backups). +There are several ways to perform backups of your content on GitLab.com. + +Projects can be backed up in their entirety by exporting them either [through the UI](../project/settings/import_export.md) or [API](../../api/project_import_export.md#schedule-an-export), the latter of which can be used to programmatically upload exports to a storage platform such as AWS S3. + +With exports, be sure to take note of [what is and is not](../project/settings/import_export.md#exported-contents), included in a project export. + +Since GitLab is built on Git, you can back up **just** the repository of a project by [cloning](../../gitlab-basics/start-using-git.md#clone-a-repository) it to another machine. Similarly, if you need to back up just the wiki of a repository it can also be cloned and all files uploaded to that wiki will come with it [if they were uploaded after 2020-08-22](../project/wiki/index.md#creating-a-new-wiki-page). + ## Alternative SSH port GitLab.com can be reached via a [different SSH port](https://about.gitlab.com/blog/2016/02/18/gitlab-dot-com-now-supports-an-alternate-git-plus-ssh-port/) for `git+ssh`. @@ -88,6 +96,7 @@ Below are the current settings regarding [GitLab CI/CD](../../ci/README.md). | [Max pipeline schedules in projects](../../administration/instance_limits.md#number-of-pipeline-schedules) | `10` for Free tier, `50` for all paid tiers | Unlimited | | [Max number of instance level variables](../../administration/instance_limits.md#number-of-instance-level-variables) | `25` | `25` | | [Scheduled Job Archival](../../user/admin_area/settings/continuous_integration.md#archive-jobs) | 3 months | Never | +| Max test cases per [unit test report](../../ci/unit_test_reports.md) | `500_000` | Unlimited | ## Account and limit settings @@ -474,6 +483,10 @@ More information on this particular change can be found at 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. @@ -529,9 +542,9 @@ Source: For performance reasons, if a query returns more than 10,000 records, GitLab doesn't return the following headers: -- `X-Total`. -- `X-Total-Pages`. -- `rel="last"` `Link`. +- `x-total`. +- `x-total-pages`. +- `rel="last"` `link`. ### Rack Attack initializer @@ -596,6 +609,11 @@ dropped and users get To help avoid abuse, project and group imports, exports, and export downloads are rate limited. See [Project import/export rate limits](../../user/project/settings/import_export.md#rate-limits) and [Group import/export rate limits](../../user/group/settings/import_export.md#rate-limits) for details. +### Non-configurable limits + +See [non-configurable limits](../../security/rate_limits.md#non-configurable-limits) for information on +rate limits that are not configurable, and therefore also used on GitLab.com. + ## GitLab.com Logging We use [Fluentd](https://gitlab.com/gitlab-com/runbooks/tree/master/logging/doc#fluentd) to parse our logs. Fluentd sends our logs to diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index ebf38aef4a6..1a62d67e468 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -14,6 +14,9 @@ Similar to [project-level](../../project/clusters/index.md) and group-level Kubernetes clusters allow you to connect a Kubernetes cluster to 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 GitLab can install and manage some applications in your group-level @@ -69,9 +72,8 @@ 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. -NOTE: **Note:** 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. +the resources required to run them, even if you choose to manage your own cluster. ### Clearing the cluster cache diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index bcc6d958427..a689b7c380b 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -9,8 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3090) for subgroups in GitLab 12.2. -## Overview - With Contribution Analytics you can get an overview of the following activity in your group: diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index e8bcb7219fc..f380b36cc00 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -10,9 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.2. > - Single-level Epics [were moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8. -Epics let you manage your portfolio of projects more efficiently and with less -effort by tracking groups of issues that share a theme, across projects and -milestones. +Epics let you manage your portfolio of projects more efficiently by tracking groups of issues that +share a theme across projects and milestones. An epic's page contains the following tabs: @@ -22,7 +21,7 @@ An epic's page contains the following tabs: - Hover over the total counts to see a breakdown of open and closed items. NOTE: **Note:** - The number provided here includes all epics associated with this project. The number includes epics for which users may not currently have permission. + The number provided here includes all epics associated with this project. The number includes epics for which users may not yet have permission. - **Roadmap**: a roadmap view of child epics which have start and due dates. @@ -65,16 +64,19 @@ graph TD ``` See [Manage issues assigned to an epic](manage_epics.md#manage-issues-assigned-to-an-epic) for steps -to add an issue to an epic, reorder issues, move issues between epics, or promote an issue to an epic. +to: + +- Add an issue to an epic +- Reorder issues +- Move an issue between epics +- Promote an issue to an epic ## Issue health status in Epic tree **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199184) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. -> - The health status of a closed issue [will be hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later. +> - The health status of a closed issue [is hidden](https://gitlab.com/gitlab-org/gitlab/-/issues/220867) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3 or later. -You can report on and quickly respond to the health of individual issues and epics by setting a -red, amber, or green [health status on an issue](../../project/issues/index.md#health-status), -which will appear on your Epic tree. +Report or respond to the health of issues and epics by setting a red, amber, or green [health status](../../project/issues/index.md#health-status), which then appears on your Epic tree. ### Disable Issue health status in Epic tree @@ -100,7 +102,7 @@ steps to create, move, reorder, or delete child epics. To set a **Start date** and **Due date** for an epic, select one of the following: - **Fixed**: Enter a fixed value. -- **From milestones**: Inherit a dynamic value from the milestones currently assigned to the epic's issues. +- **From milestones**: Inherit a dynamic value from the milestones that are assigned to the epic's issues. Note that GitLab 12.5 replaced this option with **Inherited**. - **Inherited**: Inherit a dynamic value from the epic's issues, child epics, and milestones ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 to replace **From milestones**). @@ -108,10 +110,10 @@ To set a **Start date** and **Due date** for an epic, select one of the followin > [Replaced](https://gitlab.com/gitlab-org/gitlab/-/issues/7332) in GitLab 12.5 by **Inherited**. -If you select **From milestones** for the start date, GitLab will automatically set the date to be earliest -start date across all milestones that are currently assigned to the issues that are added to the epic. -Similarly, if you select **From milestones** for the due date, GitLab will set it to be the latest due date across -all milestones that are currently assigned to those issues. +If you select **From milestones** for the start date, GitLab automatically sets the date to be earliest +start date across all milestones that are assigned to the issues that belong to the epic. +If you select **From milestones** for the due date, GitLab sets the date to be the latest due date across +all milestones that are assigned to those issues. These are dynamic dates which are recalculated if any of the following occur: @@ -138,8 +140,8 @@ These are dynamic dates and recalculated if any of the following occur: - Issues are added to, or removed from, the epic. Because the epic's dates can inherit dates from its children, the start date and due date propagate from the bottom to the top. -If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic, -then the parent epic's start date will reflect the change and this will propagate upwards to the top epic. +If the start date of a child epic on the lowest level changes, that becomes the earliest possible start date for its parent epic. +The parent epic's start date then reflects this change and propagates upwards to the top epic. ## Roadmap in epics @@ -153,11 +155,11 @@ have a [start or due date](#start-date-and-due-date), a ## Permissions -If you have access to view an epic and have access to view an issue already -added to that epic, then you can view the issue in the epic issue list. +If you have access to view an epic and an issue added to that epic, you can view the issue in the +epic's issue list. -If you have access to edit an epic and have access to edit an issue, then you -can add the issue to or remove it from the epic. +If you have access to edit an epic and an issue added to that epic, you can add the issue to or +remove it from the epic. Note that for a given group, the visibility of all projects must be the same as the group, or less restrictive. That means if you have access to a group's epic, @@ -175,8 +177,8 @@ You can also consult the [group permissions table](../../permissions.md#group-me Once you write your comment, you can either: -- Click **Comment**, and your comment will be published. -- Click **Start thread**, and you will start a thread within that epic's discussion. +- Click **Comment** to publish your comment. +- Click **Start thread** to start a thread within that epic's discussion. ### Activity sort order diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 32b76cf9280..2c838724cb3 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -371,7 +371,7 @@ To create group links via filter: ### Overriding user permissions **(STARTER ONLY)** -Since GitLab [v8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) LDAP user permissions can now be manually overridden by an admin user. To override a user's permissions: +In GitLab [8.15](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/822) and later, LDAP user permissions can now be manually overridden by an admin user. To override a user's permissions: 1. Go to your group's **Members** page. 1. Select the pencil icon in the row for the user you are editing. @@ -391,11 +391,56 @@ milestones. [Learn more about Epics.](epics/index.md) +## Group wikis **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13195) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> - It's [deployed behind a feature flag](../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-group-wikis). + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +Group wikis work the same way as [project wikis](../project/wiki/index.md), please refer to those docs for details on usage. + +Group wikis can be edited by members with [Developer permissions](../../user/permissions.md#group-members-permissions) +and above. + +### Group wikis limitations + +There are a few limitations compared to project wikis: + +- Local Git access is not supported yet. +- Group wikis are not included in global search, group exports, backups, and Geo replication. +- Changes to group wikis don't show up in the group's activity feed. + +You can follow [this epic](https://gitlab.com/groups/gitlab-org/-/epics/2782) for updates. + +### Enable or disable group wikis **(CORE ONLY)** + +Group wikis are under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can opt to disable it for your instance. + +To enable it: + +```ruby +Feature.enable(:group_wikis) +``` + +To disable it: + +```ruby +Feature.disable(:group_wikis) +``` + ## Group Security Dashboard **(ULTIMATE)** Get an overview of the vulnerabilities of all the projects in a group and its subgroups. -[Learn more about the Group Security Dashboard.](security_dashboard/index.md) +[Learn more about the Group Security Dashboard.](../application_security/security_dashboard/index.md) ## Insights **(ULTIMATE)** diff --git a/doc/user/group/iterations/index.md b/doc/user/group/iterations/index.md index 20cbc043d83..2eb50f07de3 100644 --- a/doc/user/group/iterations/index.md +++ b/doc/user/group/iterations/index.md @@ -64,6 +64,15 @@ To edit an iteration, click the three-dot menu (**{ellipsis_v}**) > **Edit itera To learn how to add an issue to an iteration, see the steps in [Managing issues](../../project/issues/managing_issues.md#add-an-issue-to-an-iteration). +## View an iteration report + +> Viewing iteration reports in projects [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222763) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.5. + +You can track the progress of an iteration by reviewing iteration reports. +An iteration report displays a list of all the issues assigned to an iteration and their status. + +To view an iteration report, go to the iterations list page and click an iteration's title. + ## Disable Iterations **(CORE ONLY)** GitLab Iterations feature is deployed with a feature flag that is **enabled by default**. diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index b013e371ed2..c9a10146440 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -1,17 +1,13 @@ --- type: reference stage: Verify -group: Analytics +group: Testing info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- # Repositories Analytics **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-repositories-analytics). **(CORE ONLY)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215104) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. CAUTION: **Warning:** This feature might not be available to you. Check the **version history** note above for details. @@ -35,25 +31,6 @@ For each day that a coverage report was generated by a job in a project's pipeli If the project's code coverage was calculated more than once in a day, we will take the last value from that day. -## Enable or disable Repositories Analytics **(CORE ONLY)** - -Repositories Analytics 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(:group_coverage_reports) -``` - -To disable it: - -```ruby -Feature.disable(:group_coverage_reports) -``` - + | Username | Name | | :-------------- | :--- | | alessandra | Rosy Grant | @@ -43,6 +45,8 @@ Assume your GitLab instance includes the following users: | logan_gutkowski | Lee Wuckert | | shelba | Josefine Haley | + + In an Issue comment, entering `@l` results in the following popup list appearing. Note that user `shelba` is not included, because the list includes only the 5 users most relevant to the Issue. diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index ed6e2460554..fd0287fb5fb 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -10,7 +10,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41174) in GitLab 10.7. Badges are a unified way to present condensed pieces of information about your -projects. They consist of a small image and additionally a URL that the image +projects. They consist of a small image and a URL that the image points to. Examples for badges can be the [pipeline status](../../ci/pipelines/settings.md#pipeline-status-badge), [test coverage](../../ci/pipelines/settings.md#test-coverage-report-badge), or ways to contact the project maintainers. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index b3b1b51a543..65416d73f06 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -43,7 +43,7 @@ For example, the following policy document allows assuming a role whose name sta Generate an access key for the IAM user, and configure GitLab with the credentials: -1. Navigate to **Admin Area > Settings > Integrations** and expand the **Amazon EKS** section. +1. Navigate to **Admin Area > Settings > General** and expand the **Amazon EKS** section. 1. Check **Enable Amazon EKS integration**. 1. Enter the account ID and access key credentials into the respective `Account ID`, `Access key ID` and `Secret access key` fields. @@ -61,22 +61,13 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **Admin Area > Kubernetes**, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an - `Account ID` and `External ID` to use in the next step. -1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role. - To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions - to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf. - In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` - policy for this role in order for GitLab to manage the EKS cluster correctly. -1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: - 1. From the left panel, select **Roles**. - 1. Click **Create role**. - 1. Under `Select type of trusted entity`, select **Another AWS account**. - 1. Enter the Account ID from GitLab into the `Account ID` field. - 1. Check **Require external ID**. - 1. Enter the External ID from GitLab into the `External ID` field. - 1. Click **Next: Permissions**. - 1. Click **Create Policy**, which will open a new window. - 1. Select the **JSON** tab, and paste in the following snippet in place of the existing content: + `Account ID` and `External ID` needed for later steps. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM policy: + 1. From the left panel, select **Policies**. + 1. Click **Create Policy**, which opens a new window. + 1. Select the **JSON** tab, and paste the following snippet in place of the + existing content. These permissions give GitLab the ability to create + resources, but not delete them: ```json { @@ -123,15 +114,26 @@ To create and add a new Kubernetes cluster to your project, group, or instance: } ``` - NOTE: **Note:** - These permissions give GitLab the ability to create resources, but not delete them. - This means that if an error is encountered during the creation process, changes will + If an error is encountered during the creation process, changes will not be rolled back and you must remove resources manually. You can do this by deleting the relevant [CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html) 1. Click **Review policy**. 1. Enter a suitable name for this policy, and click **Create Policy**. You can now close this window. - 1. Switch back to the "Create role" window, and select the policy you just created. + +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role. + To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions + to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf. + In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` + policy for this role in order for GitLab to manage the EKS cluster correctly. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: + 1. From the left panel, select **Roles**. + 1. Click **Create role**. + 1. Under `Select type of trusted entity`, select **Another AWS account**. + 1. Enter the Account ID from GitLab into the `Account ID` field. + 1. Check **Require external ID**. + 1. Enter the External ID from GitLab into the `External ID` field. + 1. Click **Next: Permissions**, and select the policy you just created. 1. Click **Next: Tags**, and optionally enter any tags you wish to associate with this role. 1. Click **Next: Review**. 1. Enter a role name and optional description into the fields provided. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 18d9fa67ee1..094f4bcf6ba 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -19,9 +19,12 @@ and learn how to spin up a Kubernetes cluster managed by Google Cloud Platform ( in a few clicks. TIP: **Tip:** -Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial), -and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's -Google Kubernetes Engine Integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit. +Every new Google Cloud Platform (GCP) account receives +[$300 in credit upon sign up](https://console.cloud.google.com/freetrial). +In partnership with Google, GitLab is able to offer an additional $200 for new GCP +accounts to get started with GitLab's Google Kubernetes Engine Integration. +[Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) +to apply for credit. ## Before you begin @@ -30,7 +33,7 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need - GitLab itself. Either: - A [GitLab.com account](https://about.gitlab.com/pricing/#gitlab-com). - A [self-managed installation](https://about.gitlab.com/pricing/#self-managed) with GitLab version - 12.5 or later. This will ensure the GitLab UI can be used for cluster creation. + 12.5 or later. This ensures the GitLab UI can be used for cluster creation. - The following GitLab access: - [Maintainer access to a project](../../permissions.md#project-members-permissions) for a project-level cluster. @@ -41,28 +44,25 @@ Before [adding a Kubernetes cluster](#create-new-cluster) using GitLab, you need ## Access controls -When creating a cluster in GitLab, you will be asked if you would like to create either: +> - Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. -- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) cluster. -- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. +When creating a cluster in GitLab, you are asked if you would like to create either: -NOTE: **Note:** -[RBAC](#rbac-cluster-resources) is recommended and the GitLab default. +- A [Role-based access control (RBAC)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) + cluster, which is the GitLab default and recommended option. +- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/reference/access-authn-authz/abac/) cluster. GitLab creates the necessary service accounts and privileges to install and run [GitLab managed applications](index.md#installing-applications). When GitLab creates the cluster, a `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace to manage the newly created cluster. -NOTE: **Note:** -Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/51716) in GitLab 11.5. - The first time you install an application into your cluster, the `tiller` service account is created with `cluster-admin` privileges in the -`gitlab-managed-apps` namespace. This service account will be used by Helm to +`gitlab-managed-apps` namespace. This service account is used by Helm to install and run [GitLab managed applications](index.md#installing-applications). -Helm will also create additional service accounts and other resources for each +Helm also creates additional service accounts and other resources for each installed application. Consult the documentation of the Helm charts for each application for details. @@ -77,7 +77,7 @@ Note the following about access controls: - Environment-specific resources are only created if your cluster is [managed by GitLab](index.md#gitlab-managed-clusters). -- If your cluster was created before GitLab 12.2, it will use a single namespace for all project +- If your cluster was created before GitLab 12.2, it uses a single namespace for all project environments. ### RBAC cluster resources @@ -151,11 +151,12 @@ Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level ## Add existing cluster -If you have an existing Kubernetes cluster, you can add it to a project, group, or instance. +If you have an existing Kubernetes cluster, you can add it to a project, group, +or instance. -NOTE: **Note:** -Kubernetes integration is not supported for arm64 clusters. See the issue -[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838) for details. +Kubernetes integration isn't supported for arm64 clusters. See the issue +[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab/-/issues/29838) +for details. ### Existing Kubernetes cluster @@ -181,7 +182,7 @@ To add a Kubernetes cluster to your project, group, or instance: kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' ``` - 1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. + 1. **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We use the certificate created by default. 1. List the secrets with `kubectl get secrets`, and one should be named similar to `default-token-xxxxx`. Copy that token name for use below. 1. Get the certificate by running this command: @@ -190,9 +191,20 @@ To add a Kubernetes cluster to your project, group, or instance: kubectl get secret -o jsonpath="{['data']['ca\.crt']}" | base64 --decode ``` - NOTE: **Note:** - If the command returns the entire certificate chain, you need copy the *root ca* - certificate at the bottom of the chain. + If the command returns the entire certificate chain, you must copy the Root CA + certificate and any intermediate certificates at the bottom of the chain. + A chain file has following structure: + + ```plaintext + -----BEGIN MY CERTIFICATE----- + -----END MY CERTIFICATE----- + -----BEGIN INTERMEDIATE CERTIFICATE----- + -----END INTERMEDIATE CERTIFICATE----- + -----BEGIN INTERMEDIATE CERTIFICATE----- + -----END INTERMEDIATE CERTIFICATE----- + -----BEGIN ROOT CERTIFICATE----- + -----END ROOT CERTIFICATE----- + ``` 1. **Token** - GitLab authenticates against Kubernetes using service tokens, which are @@ -229,10 +241,10 @@ To add a Kubernetes cluster to your project, group, or instance: kubectl apply -f gitlab-admin-service-account.yaml ``` - You will need the `container.clusterRoleBindings.create` permission + You need the `container.clusterRoleBindings.create` permission to create cluster-level roles. If you do not have this permission, you can alternatively enable Basic Authentication and then run the - `kubectl apply` command as an admin: + `kubectl apply` command as an administrator: ```shell kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password= @@ -257,7 +269,7 @@ To add a Kubernetes cluster to your project, group, or instance: Copy the `` value from the output: - ```yaml + ```plaintext Name: gitlab-token-b5zv4 Namespace: kube-system Labels: @@ -274,7 +286,7 @@ To add a Kubernetes cluster to your project, group, or instance: ``` NOTE: **Note:** - For GKE clusters, you will need the + For GKE clusters, you need the `container.clusterRoleBindings.create` permission to create a cluster role binding. You can follow the [Google Cloud documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) @@ -283,7 +295,7 @@ To add a Kubernetes cluster to your project, group, or instance: 1. **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](index.md#gitlab-managed-clusters) for more information. 1. **Project namespace** (optional) - You don't have to fill it in; by leaving - it blank, GitLab will create one for you. Also: + it blank, GitLab creates one for you. Also: - Each project should have a unique namespace. - The project namespace is not necessarily the namespace of the secret, if you're using a secret with broader permissions, like the secret from `default`. @@ -294,21 +306,21 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Finally, click the **Create Kubernetes cluster** button. -After a couple of minutes, your cluster will be ready to go. You can now proceed +After a couple of minutes, your cluster is ready. You can now proceed to install some [pre-defined applications](index.md#installing-applications). #### Disable Role-Based Access Control (RBAC) (optional) When connecting a cluster via GitLab integration, you may specify whether the -cluster is RBAC-enabled or not. This will affect how GitLab interacts with the +cluster is RBAC-enabled or not. This affects how GitLab interacts with the cluster for certain operations. If you did *not* check the **RBAC-enabled cluster** -checkbox at creation time, GitLab will assume RBAC is disabled for your cluster +checkbox at creation time, GitLab assumes RBAC is disabled for your cluster when interacting with it. If so, you must disable RBAC on your cluster for the integration to work properly. -![rbac](img/rbac_v13_1.png) +![RBAC](img/rbac_v13_1.png) -NOTE: **Note:** +CAUTION: **Caution:** Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a [security concern](index.md#security-implications), and may not be desirable. @@ -356,3 +368,12 @@ When removing the cluster integration, note: To learn more on automatically deploying your applications, read about [Auto DevOps](../../../topics/autodevops/index.md). + +## Troubleshooting + +### There was a problem authenticating with your cluster. Please ensure your CA Certificate and Token are valid + +If you encounter this error while adding a Kubernetes cluster, ensure you're +properly pasting the service token. Some shells may add a line break to the +service token, making it invalid. Ensure that there are no line breaks by +pasting your token into an editor and removing any additional spaces. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 8d188f00ceb..459ba144186 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -12,8 +12,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in > GitLab 11.11 for [instances](../../instance/clusters/index.md). -## Overview - Using the GitLab project Kubernetes integration, you can: - Use [Review Apps](../../../ci/review_apps/index.md). @@ -31,6 +29,11 @@ Besides integration at the project level, Kubernetes clusters can also be integrated at the [group level](../../group/clusters/index.md) or [GitLab instance level](../../instance/clusters/index.md). +To view your project level Kubernetes clusters, navigate to **Operations > Kubernetes** +from your project. On this page, you can [add a new cluster](#adding-and-removing-clusters) +and view information about your existing clusters, such as nodes count and rough estimates +of memory and CPU usage. + ## Setting up ### Supported cluster versions @@ -49,10 +52,9 @@ Currently, GitLab supports the following Kubernetes versions: - 1.17 - 1.16 - 1.15 -- 1.14 +- 1.14 (deprecated, support ends on December 22, 2020) - 1.13 (deprecated, support ends on November 22, 2020) -NOTE: **Note:** Some GitLab features may support versions outside the range provided here. ### Adding and removing clusters @@ -192,7 +194,6 @@ To clear the cache: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. -NOTE: **Note:** You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case will be specified as part of the Knative installation. See [Installing Applications](#installing-applications). @@ -220,13 +221,11 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) you will need the Kubernetes project integration enabled. +Auto Monitoring) you will need the Kubernetes project integration enabled, but +Kubernetes clusters can be used without Auto DevOps. [Read more about Auto DevOps](../../../topics/autodevops/index.md) -NOTE: **Note:** -Kubernetes clusters can be used without Auto DevOps. - ## Deploying to a Kubernetes cluster A Kubernetes cluster can be the destination for a deployment job. If @@ -249,36 +248,51 @@ GitLab CI/CD build environment. | Variable | Description | | -------- | ----------- | | `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). | -| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `--`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | +| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `--`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `-`. | | `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | | `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | -| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | +| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | -NOTE: **Note:** -Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main -service account of the cluster integration. - -NOTE: **Note:** -If your cluster was created before GitLab 12.2, default `KUBE_NAMESPACE` will be set to `-`. - ### Custom namespace -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. - -The Kubernetes integration defaults to project-environment-specific namespaces -of the form `--` (see [Deployment -variables](#deployment-variables)). - -For **non**-GitLab-managed clusters, the namespace can be customized using -[`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments) -in `.gitlab-ci.yml`. - -NOTE: **Note:** -When using a [GitLab-managed cluster](#gitlab-managed-clusters), the -namespaces are created automatically prior to deployment and [can not be -customized](https://gitlab.com/gitlab-org/gitlab/-/issues/38054). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. +> - An option to use project-wide namespaces [was added](https://gitlab.com/gitlab-org/gitlab/-/issues/38054) in GitLab 13.5. + +The Kubernetes integration provides a `KUBECONFIG` with an auto-generated namespace +to deployment jobs. It defaults to using project-environment specific namespaces +of the form `-`, where `` is of the form +`-`. To learn more, read [Deployment variables](#deployment-variables). + +You can customize the deployment namespace in a few ways: + +- You can choose between a **namespace per [environment](../../../ci/environments/index.md)** + or a **namespace per project**. A namespace per environment is the default and recommended + setting, as it prevents the mixing of resources between production and non-production environments. +- When using a project-level cluster, you can additionally customize the namespace prefix. + When using namespace-per-environment, the deployment namespace is `-`, + but otherwise just ``. +- For **non-managed** clusters, the auto-generated namespace is set in the `KUBECONFIG`, + but the user is responsible for ensuring its existence. You can fully customize + this value using + [`environment:kubernetes:namespace`](../../../ci/environments/index.md#configuring-kubernetes-deployments) + in `.gitlab-ci.yml`. + +When you customize the namespace, existing environments remain linked to their current +namespaces until you [clear the cluster cache](#clearing-the-cluster-cache). + +CAUTION: **Warning:** +By default, anyone who can create a deployment job can access any CI variable within +an environment's deployment job. This includes `KUBECONFIG`, which gives access to +any secret available to the associated service account in your cluster. +To keep your production credentials safe, consider using +[Protected Environments](../../../ci/environments/protected_environments.md), +combined with either + +- a GitLab-managed cluster and namespace per environment, +- *or*, an environment-scoped cluster per protected environment. The same cluster + can be added multiple times with multiple restricted service accounts. ### Integrations diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index afb6d016f45..2e224208eb8 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -28,7 +28,6 @@ above the log file data, depending on your configuration: To learn more about the Log Explorer, see [APM - Log Explorer](https://www.youtube.com/watch?v=hWclZHA7Dgw). -NOTE: **Note:** [Learn more about Kubernetes + GitLab](https://about.gitlab.com/solutions/kubernetes/). Everything you need to build, test, deploy, and run your application at scale. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 360b02efb69..c1e4e821efd 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -115,9 +115,7 @@ the components outlined above and the pre-loaded demo runbook. VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value ``` -1. To configure the operation of a runbook, create and configure variables: - - NOTE: **Note:** +1. To configure the operation of a runbook, create and configure variables. For this example, we are using the **Run SQL queries in Notebook** section in the sample runbook to query a PostgreSQL database. The first four lines of the following code block define the variables that are required for this query to function: diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index a15660051f7..bed01ff4d58 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -85,7 +85,7 @@ Host Security (Falco) are deployed with this model. To deploy GitLab Managed Apps to your cluster, you must first [add your cluster](add_remove_clusters.md) -to GitLab. Then [install](../../clusters/applications.md#installing-applications) +to GitLab. Then [install](../../clusters/applications.md#install-with-one-click) the Web Application Firewall from the project or group Kubernetes page. Note that your project doesn't have to be hosted or deployed through GitLab. You can manage a diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 543ffdbce8f..db91f78fc20 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -136,8 +136,8 @@ This example code does the following: In order to interact with your AWS account, the GitLab CI/CD pipelines require both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to be defined in your GitLab settings under **Settings > CI/CD > Variables**. For more information please see [Create a custom variable in the UI](../../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). -NOTE: **Note:** - The AWS credentials you provide must include IAM policies that provision correct access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources. + The AWS credentials you provide must include IAM policies that provision correct + access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources. #### Deploying your function @@ -154,9 +154,7 @@ endpoints: #### Manually testing your function Running the following `curl` command should trigger your function. - -NOTE: **Note:** -Your URL should be the one retrieved from the GitLab deploy stage log. +Your URL should be the one retrieved from the GitLab deploy stage log: ```shell curl https://u768nzby1j.execute-api.us-east-1.amazonaws.com/production/hello @@ -222,7 +220,8 @@ the environment of the deployed function: ```yaml provider: - ... + # Other configuration omitted + # ... environment: A_VARIABLE: ${env:A_VARIABLE} ``` @@ -245,10 +244,10 @@ functions: hello: handler: src/handler.hello events: - - http: # Rewrite this part to enable CORS + - http: # Rewrite this part to enable CORS path: hello method: get - cors: true # <-- CORS here + cors: true # <-- CORS here ``` You also need to return CORS specific headers in your function response: @@ -378,7 +377,6 @@ To set these: `AWS_SECRET_ACCESS_KEY`. 1. Mask the credentials so they do not show in logs using the **Masked** toggle. -NOTE: **Note:** The AWS credentials you provide must include IAM policies that provision correct access control to AWS Lambda, API Gateway, CloudFormation, and IAM resources. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 1157c2c5632..603c4bd73b1 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -75,8 +75,8 @@ To run Knative on GitLab, you will need: ## Installing Knative via GitLab's Kubernetes integration -NOTE: **Note:** -The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. **RBAC must be enabled.** +The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB +memory. **RBAC must be enabled.** 1. [Add a Kubernetes cluster](../add_remove_clusters.md). 1. Select the **Applications** tab and scroll down to the Knative app section. Enter the domain to be used with @@ -99,22 +99,19 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22. ![DNS entry](img/dns-entry.png) -NOTE: **Note:** You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) -on a given project but not both. The current implementation makes use of a `serverless.yml` file to signal a FaaS project. +on a given project, but not both. The current implementation makes use of a +`serverless.yml` file to signal a FaaS project. ## Using an existing installation of Knative > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/58941) in GitLab 12.0. -NOTE: **Note:** -The "invocations" monitoring feature of GitLab serverless will not work when +The _invocations_ monitoring feature of GitLab serverless won't work when adding an existing installation of Knative. -It is also possible to use GitLab Serverless with an existing Kubernetes -cluster which already has Knative installed. - -You must do the following: +It's also possible to use GitLab Serverless with an existing Kubernetes cluster +which already has Knative installed. You must do the following: 1. Follow the steps to [add an existing Kubernetes @@ -453,16 +450,16 @@ To run a function locally: > Introduced in GitLab 11.5. +12345678901234567890123456789012345678901234567890123456789012345678901234567890 Serverless applications are an alternative to [serverless functions](#deploying-functions). -They are useful in scenarios where an existing runtime does not meet the needs of an application, -such as one written in a language that has no runtime available. Note though that serverless -applications should be stateless! - -NOTE: **Note:** -You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. +They're useful in scenarios where an existing runtime does not meet the needs of +an application, such as one written in a language that has no runtime available. +Note though that serverless applications should be stateless. -Add the following `.gitlab-ci.yml` to the root of your repository -(you may skip this step if you've previously cloned the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned above): +You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) +to get started. Add the following `.gitlab-ci.yml` to the root of your repository +(you may skip this step if you've previously cloned the previously mentioned, +sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app)): ```yaml include: @@ -561,14 +558,18 @@ Or: ## Enabling TLS for Knative services -By default, a GitLab serverless deployment will be served over `http`. In order to serve over `https` you -must manually obtain and install TLS certificates. +By default, a GitLab serverless deployment will be served over `http`. To serve +over `https`, you must manually obtain and install TLS certificates. -The simplest way to accomplish this is to -use [Certbot to manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). Certbot is a free, open source software tool for automatically using Let’s Encrypt certificates on manually-administrated websites to enable HTTPS. +12345678901234567890123456789012345678901234567890123456789012345678901234567890 +The simplest way to accomplish this is to use Certbot to +[manually obtain Let's Encrypt certificates](https://knative.dev/docs/serving/using-a-tls-cert/#using-certbot-to-manually-obtain-let-s-encrypt-certificates). +Certbot is a free, open source software tool for automatically using Let’s Encrypt +certificates on manually-administered websites to enable HTTPS. -NOTE: **Note:** -The instructions below relate to installing and running Certbot on a Linux server that has Python 3 installed and may not work on other operating systems or with other versions of Python. +The following instructions relate to installing and running Certbot on a Linux +server that has Python 3 installed, and may not work on other operating systems +or with other versions of Python. 1. Install Certbot by running the [`certbot-auto` wrapper script](https://certbot.eff.org/docs/install.html#certbot-auto). @@ -788,7 +789,7 @@ The instructions below relate to installing and running Certbot on a Linux serve kubectl edit gateway knative-ingress-gateway --namespace knative-serving ``` - Update the gateway to include the following tls: section and configuration: + Update the gateway to include the following `tls:` section and configuration: ```shell tls: diff --git a/doc/user/project/code_intelligence.md b/doc/user/project/code_intelligence.md index f56673e69b7..d0c5a24826a 100644 --- a/doc/user/project/code_intelligence.md +++ b/doc/user/project/code_intelligence.md @@ -58,9 +58,9 @@ relevant language. | Language | Implementation | |---|---| -| Go | [sourcegraph/lsif-go](https://github.com/sourcegraph/lsif-go) | -| JavaScript | [sourcegraph/lsif-node](https://github.com/sourcegraph/lsif-node) | -| TypeScript | [sourcegraph/lsif-node](https://github.com/sourcegraph/lsif-node) | +| Go | [`sourcegraph/lsif-go`](https://github.com/sourcegraph/lsif-go) | +| JavaScript | [`sourcegraph/lsif-node`](https://github.com/sourcegraph/lsif-node) | +| TypeScript | [`sourcegraph/lsif-node`](https://github.com/sourcegraph/lsif-node) | View a complete list of [available LSIF indexers](https://lsif.dev/#implementations-server) on their website and refer to their documentation to see how to generate an LSIF file for your specific language. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 730a9ada428..4ae3d5ec032 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -75,7 +75,6 @@ be used for merge request approvals: - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers). - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)** -NOTE: **Note:** Developer or higher [permissions](../permissions.md) are required in order to approve a merge request. @@ -93,12 +92,14 @@ to specify the actual owners and granular permissions. Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners) will prevent any user who is not specified in the `CODEOWNERS` file from pushing -changes for the specified files/paths, even if their role is included in the +changes for the specified files/paths, except those included in the **Allowed to push** column. This allows for a more inclusive push strategy, as administrators don't have to restrict developers from pushing directly to the protected branch, but can restrict pushing to certain files where a review by Code Owners is required. +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, users and groups who are allowed to push to protected branches do not require a merge request to merge their feature branches. Thus, they can skip merge request approval rules, Code Owners included. + ## The syntax of Code Owners files Files can be specified using the same kind of patterns you would use @@ -158,7 +159,7 @@ file.md @group-x @group-x/subgroup-y ### Code Owners Sections **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2 behind a feature flag, enabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Code Owner rules can be grouped into named sections. This allows for better organization of broader categories of Code Owner rules to be applied. diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 8146f39ef87..3c6494d5f1a 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -85,7 +85,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ [`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor. 1. Configure the [Kubernetes integration](clusters/index.md) in your project for the cluster. The Kubernetes namespace is of particular note as you will need it - for your deployment scripts (exposed by the `KUBE_NAMESPACE` env variable). + for your deployment scripts (exposed by the `KUBE_NAMESPACE` environment variable). 1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG` and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` and @@ -106,7 +106,7 @@ To display the Deploy Boards for a specific [environment](../../ci/environments/ be done automatically and no action is necessary. If you are using GCP to manage clusters, you can see the deployment details in GCP itself by going to **Workloads > deployment name > Details**: - + ![Deploy Boards Kubernetes Label](img/deploy_boards_kubernetes_label.png) Once all of the above are set up and the pipeline has run at least once, diff --git a/doc/user/project/deploy_keys/index.md b/doc/user/project/deploy_keys/index.md index 81c9008c5b3..4f344554016 100644 --- a/doc/user/project/deploy_keys/index.md +++ b/doc/user/project/deploy_keys/index.md @@ -12,7 +12,7 @@ more repositories, by importing an SSH public key to your GitLab instance. This is useful for cloning repositories to your Continuous Integration (CI) server. By using deploy keys, you don't have to set up a -dummy user account. +fake user account. There are two types of deploy keys: diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index aa5987bf5f9..e0c4097d1c5 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -49,8 +49,8 @@ To create a Markdown file: 1. Click the `+` button next to `master` and click **New file**. 1. Add the name of your issue template to the **File name** text field next to `master`. - Make sure words are separated with underscores and that your file has the `.md` extension, for - example `feature_request.md`. + Make sure that your file has the `.md` extension, for + example `feature_request.md` or `Feature Request.md`. 1. Commit and push to your default branch. If you don't have a `.gitlab/issue_templates` directory in your repository, you'll need to create it. @@ -79,6 +79,9 @@ This will enable the `Bug` dropdown option when creating or editing issues. When to the issue description field. The 'Reset template' button will discard any changes you made after picking the template and return it to its initial status. +TIP: **Tip:** +You can create short-cut links to create an issue using a designated template. For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. + ![Description templates](img/description_templates.png) ## Setting a default template for merge requests and issues **(STARTER)** diff --git a/doc/user/project/file_lock.md b/doc/user/project/file_lock.md index 6fd33901621..46c2e211d57 100644 --- a/doc/user/project/file_lock.md +++ b/doc/user/project/file_lock.md @@ -69,7 +69,7 @@ brew install git-lfs ``` Once installed, **open your local repository in a terminal window** and -install Git LFS in your repo. If you're sure that LFS is already installed, +install Git LFS in your repository. If you're sure that LFS is already installed, you can skip this step. If you're unsure, re-installing it won't do any harm: ```shell @@ -159,7 +159,7 @@ command line interface, file locks can be created for any file. ### View exclusively-locked files To list all the files locked with LFS locally, open a terminal window in your -repo and run: +repository and run: ```shell git lfs locks @@ -189,7 +189,7 @@ Suggested workflow for shared projects: 1. Lock the file. 1. Edit the file. 1. Commit your changes. -1. Push to the repo. +1. Push to the repository. 1. Get your changes reviewed, approved, and merged. 1. Unlock the file. diff --git a/doc/user/project/img/issue_board_default_lists_v13_4.png b/doc/user/project/img/issue_board_default_lists_v13_4.png new file mode 100644 index 00000000000..23cdc9b4e22 Binary files /dev/null and b/doc/user/project/img/issue_board_default_lists_v13_4.png differ diff --git a/doc/user/project/img/issue_board_welcome_message.png b/doc/user/project/img/issue_board_welcome_message.png deleted file mode 100644 index 357dff42488..00000000000 Binary files a/doc/user/project/img/issue_board_welcome_message.png and /dev/null differ diff --git a/doc/user/project/img/labels_key_value_v12_1.png b/doc/user/project/img/labels_key_value_v12_1.png deleted file mode 100644 index ccda944a647..00000000000 Binary files a/doc/user/project/img/labels_key_value_v12_1.png and /dev/null differ diff --git a/doc/user/project/img/labels_key_value_v13_5.png b/doc/user/project/img/labels_key_value_v13_5.png new file mode 100644 index 00000000000..4264eb3211e Binary files /dev/null and b/doc/user/project/img/labels_key_value_v13_5.png differ diff --git a/doc/user/project/img/labels_prioritized_v12_1.png b/doc/user/project/img/labels_prioritized_v12_1.png deleted file mode 100644 index 512c5d59a5a..00000000000 Binary files a/doc/user/project/img/labels_prioritized_v12_1.png and /dev/null differ diff --git a/doc/user/project/img/labels_prioritized_v13_5.png b/doc/user/project/img/labels_prioritized_v13_5.png new file mode 100644 index 00000000000..04ffd67a59f Binary files /dev/null and b/doc/user/project/img/labels_prioritized_v13_5.png differ diff --git a/doc/user/project/img/labels_subscriptions_v12_1.png b/doc/user/project/img/labels_subscriptions_v12_1.png deleted file mode 100644 index fa83b7db414..00000000000 Binary files a/doc/user/project/img/labels_subscriptions_v12_1.png and /dev/null differ diff --git a/doc/user/project/img/labels_subscriptions_v13_5.png b/doc/user/project/img/labels_subscriptions_v13_5.png new file mode 100644 index 00000000000..a2a4e9e50cc Binary files /dev/null and b/doc/user/project/img/labels_subscriptions_v13_5.png differ diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 89130d5822f..56266718d12 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -76,6 +76,3 @@ If you've accidentally started the import process with the wrong account, follow 1. Revoke GitLab access to your Bitbucket account, essentially reversing the process in the following procedure: [Import your Bitbucket repositories](#import-your-bitbucket-repositories). 1. Sign out of the Bitbucket account. Follow the procedure linked from the previous step. - -NOTE: **Note:** -To import a repository including LFS objects from a Bitbucket server repository, use the [Repo by URL](../import/repo_by_url.md) importer. diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index d0499730bfe..ac5be2b46a4 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -37,12 +37,7 @@ Import your projects from Bitbucket Server to GitLab with minimal effort. empty changes. 1. Attachments in Markdown are currently not imported. 1. Task lists are not imported. -1. Emoji reactions are not imported. -1. [LFS objects](../../../topics/git/lfs/index.md) are not imported. - - NOTE: **Note:** - To import a repository including LFS objects from a Bitbucket server repository, use the [Repo by URL](../import/repo_by_url.md) importer. - +1. Emoji reactions are not imported 1. Project filtering does not support fuzzy search (only `starts with` or `full match strings` are currently supported) @@ -69,20 +64,43 @@ namespace that started the import process. #### User assignment by username -Alternatively, user assignment by username is available behind a `bitbucket_server_user_mapping_by_username` feature flag. -The importer will try to find a user in the GitLab user database using author's `username` or `slug` or `displayName`. -Falls back to author's `email` if user is not found by username. -Similarly to user assignment by email, if no such user is available, the project creator is set as the author. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218609) in GitLab 13.4. +> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +If you've enabled this feature, the importer tries to find a user in the GitLab user database with +the author's: + +- `username` +- `slug` +- `displayName` + +If the user is not found by any of these properties, the search falls back to the author's +`email` address. -To enable or disable user assignment by username: +Alternatively, if there is also no email address, the project creator is set as the author. -Start a [Rails console](../../../administration/troubleshooting/debug.md#starting-a-rails-console-session). +##### Enable or disable User assignment by username + +User assignment by username 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 -# Enable Feature.enable(:bitbucket_server_user_mapping_by_username) +``` -# Disable +To disable it: + +```ruby Feature.disable(:bitbucket_server_user_mapping_by_username) ``` diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index f21ec26bdef..2d0caa7d46e 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -96,7 +96,7 @@ back to both GitLab and GitHub when completed. The mirroring is pull-only by default, so you may create or update the file on GitHub: - ![Edit gitlab-ci.yml file](img/gemnasium/edit_gitlab-ci.png) + ![Edit YAML file](img/gemnasium/edit_gitlab-ci.png) 1. Once your file has been committed, a new pipeline will be automatically triggered if your file is valid: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index 4cd0c9e02c7..6c0105aaded 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -35,25 +35,20 @@ The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `git This process does not migrate or import any types of groups or organizations from GitHub to GitLab. -### If you're using GitLab.com +### Use cases -If you're using GitLab.com, you can alternatively import -GitHub repositories using a [personal access token](#using-a-github-token), -but we don't recommend this method because it can't associate all user activity -(such as issues and pull requests) with matching GitLab users. +The steps you take depend on whether you are importing from GitHub.com or GitHub Enterprise, as well as whether you are importing to GitLab.com or self-managed GitLab instance. -### If you're importing from GitLab Enterprise - -If you're importing from GitHub Enterprise, you must enable [GitHub integration][gh-import]. - -### If you're using a self-managed GitLab instance - -If you're an administrator of a self-managed GitLab instance, you must enable -[GitHub integration][gh-import]. - -If you're an administrator of a self-managed GitLab instance, you can also use the -[GitHub Rake task](../../../administration/raketasks/github_import.md) to import projects from -GitHub without the constraints of a Sidekiq worker. +- If you're importing to GitLab.com, you can alternatively import GitHub repositories + using a [personal access token](#using-a-github-token). We do not recommend + this method, as it does not associate all user activity (such as issues and + pull requests) with matching GitLab users. +- If you're importing to a self-managed GitLab instance, you can alternatively use the + [GitHub Rake task](../../../administration/raketasks/github_import.md) to import + projects without the constraints of a [Sidekiq](../../../development/sidekiq_style_guide.md) worker. +- If you're importing from GitHub Enterprise to your self-managed GitLab instance, you must first enable + [GitHub integration](../../../integration/github.md). However, you cannot import projects from GitHub Enterprise to GitLab.com. +- If you're importing from GitHub.com to your self-managed GitLab instance, you do not need to set up GitHub integration. ## How it works @@ -106,7 +101,7 @@ If you are using a self-managed GitLab instance or if you are importing from Git 1. From the top navigation bar, click **+** and select **New project**. 1. Select the **Import project** tab and then select **GitHub**. 1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application. -1. Click **Authorize gitlabhq**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. +1. Click **Authorize GitlabHQ**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. 1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). ### Using a GitHub token @@ -124,7 +119,7 @@ If you are not using the GitHub integration, you can still perform an authorizat 1. Go to 1. Enter a token description. -1. Select the repo scope. +1. Select the repository scope. 1. Click **Generate token**. 1. Copy the token hash. 1. Go back to GitLab and provide the token to the GitHub importer. @@ -141,10 +136,10 @@ your GitHub repositories are listed. 1. Select the **Import** button next to any number of repositories, or select **Import all repositories**. Additionally, you can filter projects by name. If filter is applied, **Import all repositories** only imports matched repositories. 1. The **Status** column shows the import status of each repository. You can choose to leave the page open and it will - update in realtime or you can return to it later. + update in real-time or you can return to it later. 1. Once a repository has been imported, click its GitLab path to open its GitLab URL. -![Github importer page](img/import_projects_from_github_importer_v12_3.png) +![GitHub importer page](img/import_projects_from_github_importer_v12_3.png) ## Mirroring and pipeline status sharing @@ -154,7 +149,7 @@ your imported repository in sync with its GitHub copy. Additionally, you can configure GitLab to send pipeline status updates back GitHub with the [GitHub Project Integration](../integrations/github.md). **(PREMIUM)** -If you import your project using [CI/CD for external repo](../../../ci/ci_cd_for_external_repos/index.md), then both +If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/index.md), then both of the above are automatically configured. **(PREMIUM)** ## Improving the speed of imports on self-managed instances diff --git a/doc/user/project/import/img/manifest_status_v13_3.png b/doc/user/project/import/img/manifest_status_v13_3.png index 3f0063e6715..c1a55ba1f50 100644 Binary files a/doc/user/project/import/img/manifest_status_v13_3.png and b/doc/user/project/import/img/manifest_status_v13_3.png differ diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 86b671c8371..a1c28cfa2b7 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -18,7 +18,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w 1. [From Perforce](perforce.md) 1. [From SVN](svn.md) 1. [From TFVC](tfvc.md) -1. [From repo by URL](repo_by_url.md) +1. [From repository by URL](repo_by_url.md) 1. [By uploading a manifest file (AOSP)](manifest.md) 1. [From Gemnasium](gemnasium.md) 1. [From Phabricator](phabricator.md) @@ -32,7 +32,7 @@ There is also the option of [connecting your external repository to get CI/CD be ## Migrating from self-managed GitLab to GitLab.com -If you only need to migrate Git repos, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported. +If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported. If you want to retain all metadata like issues and merge requests, you can use the [import/export feature](../settings/import_export.md) to export projects from self-managed GitLab and import those projects into GitLab.com. diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 60524f3cc69..ba1e2011d08 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -56,7 +56,7 @@ You can start the import with: 1. From your GitLab dashboard click **New project** 1. Switch to the **Import project** tab 1. Click on the **Manifest file** button -1. Provide GitLab with a manifest xml file +1. Provide GitLab with a manifest XML file 1. Select a group you want to import to (you need to create a group first if you don't have one) 1. Click **List available repositories**. At this point, you will be redirected to the import status page with projects list based on the manifest file. diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index dbc1c491493..4ccc34efe30 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -20,7 +20,7 @@ Git: it creates an integration record in their proprietary database for every file in the branch, regardless how many were actually changed. Whereas Git was implemented with a different architecture so that a single SHA acts as a pointer - to the state of the whole repo after the changes, making it very easy to branch. + to the state of the whole repository after the changes, making it very easy to branch. This is what made feature branching workflows so easy to adopt with Git. 1. Also, context switching between branches is much easier in Git. If your manager said 'You need to stop work on that new feature and fix this security diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 9b5e43aae79..5c53b6eaf06 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -5,7 +5,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/#designated-technical-writers --- -# Import project from repo by URL +# Import project from repository by URL You can import your existing repositories by providing the Git URL: @@ -16,4 +16,4 @@ You can import your existing repositories by providing the Git URL: 1. Click **Create project** to begin the import process 1. Once complete, you will be redirected to your newly created project -![Import project by repo URL](img/import_projects_from_repo_url.png) +![Import project by repository URL](img/import_projects_from_repo_url.png) diff --git a/doc/user/project/index.md b/doc/user/project/index.md index c79f2be1d3f..a00f93bac9c 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -34,7 +34,7 @@ When you create a project in GitLab, you'll have access to a large number of - [Protected tags](protected_tags.md): Control over who has permission to create tags, and prevent accidental update or deletion - [Repository mirroring](repository/repository_mirroring.md) - - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits + - [Signing commits](repository/gpg_signed_commits/index.md): use GPG to sign your commits - [Deploy tokens](deploy_tokens/index.md): Manage project-based deploy tokens that allow permanent access to the repository and Container Registry. - [Web IDE](web_ide/index.md) - [CVE ID Requests](../application_security/cve_id_request.md): Request a CVE identifier to track a @@ -96,9 +96,9 @@ When you create a project in GitLab, you'll have access to a large number of - [Wiki](wiki/index.md): document your GitLab project in an integrated Wiki. - [Snippets](../snippets.md): store, share and collaborate on code snippets. -- [Value Stream Analytics](cycle_analytics.md): review your development lifecycle. +- [Value Stream Analytics](../analytics/value_stream_analytics.md): review your development lifecycle. - [Insights](insights/index.md): configure the Insights that matter for your projects. **(ULTIMATE)** -- [Security Dashboard](security_dashboard.md): Security Dashboard. **(ULTIMATE)** +- [Security Dashboard](../application_security/security_dashboard/index.md): Security Dashboard. **(ULTIMATE)** - [Syntax highlighting](highlighting.md): an alternative to customize your code blocks, overriding GitLab's default choice of language. - [Badges](badges.md): badges for the project overview. diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 443ca11be27..bb4a5b2b97f 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -14,8 +14,8 @@ See the project homepage for further information: ## Needed setup -You will first need an Irker daemon. You can download the Irker code from its -repository on : +You will first need an Irker daemon. You can download the Irker code +[from its repository](https://gitlab.com/esr/irker): ```shell git clone https://gitlab.com/esr/irker.git @@ -55,6 +55,6 @@ case, `Aorimn` is treated as a nick and no more as a channel name. Irker can also join password-protected channels. Users need to append `?key=thesecretpassword` to the channel name. When using this feature remember to **not** put the `#` sign in front of the channel name; failing to do so will -result on irker joining a channel literally named `#chan?key=password` henceforth +result on Irker joining a channel literally named `#chan?key=password` henceforth leaking the channel key through the `/whois` IRC command (depending on IRC server -configuration). This is due to a long standing irker bug. +configuration). This is due to a long standing Irker bug. diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 3e0b6492477..b4e02bbd5f3 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -23,7 +23,7 @@ Features include: - **View a list of Jira issues directly in GitLab** **(PREMIUM)** For additional features, you can install the -[Jira Development Panel integration](../../../integration/jira_development_panel.md) **(PREMIUM)**. +[Jira Development Panel integration](../../../integration/jira_development_panel.md). This enables you to: - In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. @@ -122,6 +122,8 @@ By now you should have [configured Jira](#configuring-jira) and enabled the you should be able to reference and close Jira issues by just mentioning their ID in GitLab commits and merge requests. +Jira issue IDs must be formatted in uppercase for the integration to work. + ### Reference Jira issues When GitLab project has Jira issue tracker configured and enabled, mentioning diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 7a1f757c138..a502dfbf320 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -50,7 +50,7 @@ Click on the service links to see further configuration instructions and details | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | No | | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | No | | [Microsoft teams](microsoft_teams.md) | Receive notifications for actions that happen on GitLab into a room on Microsoft Teams using Office 365 Connectors | No | -| Packagist | Update your project on Packagist, the main Composer repository | Yes | +| Packagist | Update your projects on Packagist, the main Composer repository | Yes | | Pipelines emails | Email the pipeline status to a list of recipients | No | | [Slack Notifications](slack.md) | Send GitLab events (for example, an issue was created) to Slack as notifications | No | | [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab | No | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index a19b819c823..28a9afa5bb0 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -58,6 +58,43 @@ CPU and Memory consumption is monitored, but requires [naming conventions](prome 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} +``` + ### Manual configuration of Prometheus #### Requirements @@ -136,10 +173,7 @@ one of them will be used: > - GitLab 9.3 added the [numeric comparison](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/27439) of the 30 minute averages. Developers can view the performance impact of their changes within the merge -request workflow. - -NOTE: **Note:** -Requires [Kubernetes](prometheus_library/kubernetes.md) metrics. +request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. When a source branch has been deployed to an environment, a sparkline and numeric comparison of the average memory consumption will appear. On the diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index e278c7eb664..70f8a55bb07 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 712805b75f2..0fbc49ddad7 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 6f2c2477eee..35b111ab2b2 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 29efe08e53d..43c2d305437 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -12,7 +12,7 @@ GitLab has support for automatically detecting and monitoring Kubernetes metrics ## Requirements -The [Prometheus](../prometheus.md) and [Kubernetes](../kubernetes.md) +The [Prometheus](../prometheus.md) and [Kubernetes](../../clusters/index.md) integration services must be enabled. ## Metrics supported diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 0d3042463c9..1757378fb70 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index 7bebe7b1e65..fdea800c410 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -8,11 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22133) in GitLab 11.7. +GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. + NOTE: **Note:** NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics exporter](nginx_ingress_vts.md), which exports metrics different than the built-in metrics. -GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. - ## Requirements [Prometheus integration](../prometheus.md) must be active. 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 326931e9790..ec7b1ee6d10 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: APM +group: Health info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 688643a85a7..abb072c9a0a 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -6,20 +6,52 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Service templates -Using a service template, GitLab administrators can provide default values for configuring integrations at the project level. +Using a service template, GitLab administrators can: -When you enable a service template, the defaults are applied to **all** projects that do not -already have the integration enabled or do not otherwise have custom values saved. -The values are pre-filled on each project's configuration page for the applicable integration. +- Provide default values for configuring integrations when creating new projects. +- Bulk configure all existing projects in one step. -If you disable the template, these values no longer appear as defaults, while -any values already saved for an integration remain unchanged. +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 will 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. + +[Read more about setting up project integration management](../../admin_area/settings/project_integration_management.md) +(introduced in GitLab 13.3) and [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 will be 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. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 03ff5f845b6..e6f12c2532f 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -64,7 +64,7 @@ The following triggers are available for Slack notifications: - **Tag push**: Triggered when a new tag is pushed to the repository. - **Pipeline**: Triggered when a pipeline status changes. - **Wiki page**: Triggered when a wiki page is created or updated. -- **Deployment**: Triggered when a deployment finishes. +- **Deployment**: Triggered when a deployment starts or finishes. - **Alert**: Triggered when a new, unique alert is recorded. ## Troubleshooting diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 800eb1d3359..7adea5ebcd6 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1303,7 +1303,12 @@ Note that `commit.id` is the ID of the pipeline, not the ID of the commit. ### Deployment events -Triggered when deployment is finished/failed/canceled. +Triggered when a deployment: + +- Starts ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5.) +- Succeeds +- Fails +- Is cancelled **Request Header**: diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index f8172a0f988..bce40e9a838 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -8,14 +8,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5554) in [GitLab 8.11](https://about.gitlab.com/releases/2016/08/22/gitlab-8-11-released/#issue-board). -## Overview - The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board. -It pairs issue tracking and project management, keeping everything in the same place, +It pairs issue tracking and project management, keeping everything together, so that you don't need to jump between different platforms to organize your workflow. Issue boards build on the existing [issue tracking functionality](issues/index.md#issues-list) and @@ -26,8 +24,8 @@ Issue boards help you to visualize and manage your entire process in GitLab. You add your labels, and then create the corresponding list for your existing issues. When you're ready, you can drag your issue cards from one step to another one. -An issue board can show you what issues your team is working on, who is assigned to each, -and where in the workflow those issues are. +An issue board can show you the issues your team is working on, who is assigned to each, +and where the issues are in the workflow. To let your team members organize their own workflows, use [multiple issue boards](#use-cases-for-multiple-issue-boards). This allows creating multiple issue @@ -60,8 +58,8 @@ Here are some common use cases for issue boards. ### Use cases for a single issue board -With the GitLab Workflow you can discuss proposals in issues, categorize them -with labels, and from there, organize and prioritize them with issue boards. +With the GitLab Workflow you can discuss proposals in issues, label +them, and organize and prioritize them with issue boards. For example, let's consider this simplified development workflow: @@ -155,7 +153,7 @@ card includes: ## Permissions Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the -Issue Board feature to create or delete lists and drag issues from one list to another. +Issue Board feature to create or delete lists. They can also drag issues from one list to another. ## How GitLab orders issues in a list @@ -164,20 +162,19 @@ that order by dragging the issues. The changed order is saved, so that anybody w 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 -loads a board containing that issue), it is ordered in relation to other issues in that list -according to [label priority](labels.md#label-priority). +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). At this point, that issue is assigned a relative order value by the system, -representing its relative order with respect to the other issues in the list. Any time -you reorder that issue by dragging, its relative order value changes accordingly. +with respect to the other issues in the list. Any time +you drag and reorder the issue, its relative order value changes accordingly. -Also, any time that issue appears in any board when it's loaded by a user, -the updated relative order value is used for the ordering. It's only the first -time an issue appears that it takes from the priority order mentioned above. This means that -if issue `A` is reordered by dragging to be above issue `B` by any user in -a given board inside your GitLab instance, any time those two issues are subsequently -loaded in any board in the same instance (could be a different project board or a different group -board, for example), that ordering is maintained. +Also, any time that issue appears in any board, the ordering is done according to +the updated relative order value. It's only the first +time an issue appears that it takes from the priority order mentioned above. If a user in your GitLab instance +drags issue `A` above issue `B`, the ordering is maintained when these two issues are subsequently +loaded in any board in the same instance. This could be a different project board or a different group +board, for example. 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, @@ -195,8 +192,7 @@ advanced functionality is present in [higher tiers only](https://about.gitlab.co > - Multiple issue boards per group are available in [GitLab Premium](https://about.gitlab.com/pricing/). Multiple issue boards allow for more than one issue board for a given project or group. -This is great for large projects with more than one team or in situations where a repository is used -to host the code of multiple products. +This is great for large projects with more than one team or when a repository hosts the code of multiple products. Using the search box at the top of the menu, you can filter the listed boards. @@ -230,13 +226,13 @@ To delete the currently active issue board: An issue board can be associated with a GitLab [Milestone](milestones/index.md#milestones), [Labels](labels.md), Assignee and Weight -which will automatically filter the Board issues according to these fields. +which automatically filter the board issues accordingly. This allows you to create unique boards according to your team's need. ![Create scoped board](img/issue_board_creation.png) You can define the scope of your board when creating it or by clicking the "Edit board" button. -Once a milestone, assignee or weight is assigned to an issue board, you will no longer be able to +Once a milestone, assignee or weight is assigned to an issue board, you can no longer filter through these in the search bar. In order to do that, you need to remove the desired scope (for example, milestone, assignee, or weight) from the issue board. @@ -274,24 +270,22 @@ especially in combination with [assignee lists](#assignee-lists). ### Group issue boards **(PREMIUM)** -> [Introduced](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. +> - One group issue board per group introduced in GitLab 10.6. +> - Multiple group issue boards [introduced](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0. -Accessible at the group navigation level, a group issue board offers the same features as a project-level board, -but it can display issues from all projects in that +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. -NOTE: **Note:** -Multiple group issue boards were originally [introduced](https://about.gitlab.com/releases/2017/09/22/gitlab-10-0-released/#group-issue-boards) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0, and one group issue board per group was made available in GitLab Core 10.6. - ![Group issue board](img/group_issue_board.png) ### Assignee lists **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5784) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. -Like in a regular list that shows all issues with a chosen label, you can add +As in a regular list showing all issues with a chosen label, you can add an assignee list that shows all issues assigned to a user. You can have a board with both label lists and assignee lists. To add an assignee list: @@ -317,7 +311,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. -Similar to the assignee lists, you're now able to [drag issues](#drag-issues-between-lists) +Like the assignee lists, you're able to [drag issues](#drag-issues-between-lists) to and from a milestone list to manipulate the milestone of the dragged issues. As in other list types, click the trash icon to remove a list. @@ -333,7 +327,7 @@ You cannot set a WIP limit on the default lists (**Open** and **Closed**). Examples: -- You have a list with four issues, and a limit of five, the header will show **4/5**. +- When you have a list with four issues and a limit of five, the header shows **4/5**. If you exceed the limit, the current number of issues is shown in red. - You have a list with five issues with a limit of five. When you move another issue to that list, the list's header displays **6/5**, with the six shown in red. @@ -374,29 +368,24 @@ If you're not able to do some of the things above, make sure you have the right ### First time using an issue board -The first time you open an issue board, you are presented with -the default lists (**Open** and **Closed**) and a welcome message that gives -you two options. You can either: +> The automatic creation of the **To Do** and **Doing** lists was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202144) in GitLab 13.5. -- Create a predefined set of labels (by default: **To Do** and **Doing**) and create their - corresponding lists to the issue board. -- Opt-out and use your own lists. +The first time you open an issue board, you are presented with the default lists +(**Open**, **To Do**, **Doing**, and **Closed**). -![issue board welcome message](img/issue_board_welcome_message.png) +If the **To Do** and **Doing** labels don't exist in the project or group, they are created, and +their lists appear as empty. If any of them already exists, the list is filled with the issues that +have that label. -If you choose to use and create the predefined lists, they will appear as empty -because the labels associated to them will not exist up until that moment, -which means the system has no way of populating them automatically. That's of -course if the predefined labels don't already exist. If any of them does exist, -the list will be created and filled with the issues that have that label. +![issue board default lists](img/issue_board_default_lists_v13_4.png) ### Create a new list Create a new list by clicking the **Add list** button in the upper right corner of the issue board. -![issue board welcome message](img/issue_board_add_list.png) +![creating a new list in an issue board](img/issue_board_add_list.png) -Then, choose the label or user to create the list from. The new list will be inserted +Then, choose the label or user to create the list from. The new list is inserted at the end of the lists, before **Done**. Moving and reordering lists is as easy as dragging them around. @@ -407,15 +396,15 @@ You can now choose it to create a list. ### Delete a list To delete a list from the issue board, use the small trash icon present -in the list's heading. A confirmation dialog will appear for you to confirm. +in the list's heading. A confirmation dialog appears for you to confirm. -Deleting a list doesn't have any effect in issues and labels, it's just the -list view that is removed. You can always add it back later if you need. +Deleting 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. ### Add issues to a list You can add issues to a list by clicking the **Add issues** button -present in the upper right corner of the issue board. This will open up a modal +present in the upper right corner of the issue board. This opens up a modal window where you can see all the issues that do not belong to any list. Select one or more issues by clicking the cards and then click **Add issues** @@ -435,7 +424,7 @@ respective label is removed. ### Filter issues You should be able to use the filters on top of your issue board to show only -the results you want. This is similar to the filtering used in the issue tracker +the results you want. It's similar to the filtering used in the issue tracker since the metadata from the issues and labels are re-used in the issue board. You can filter by author, assignee, milestone, and label. @@ -469,12 +458,12 @@ For example, you can create a list based on the label of **Frontend** and one fo worked on by the designers. Then, once they're done, all they have to do is -drag it to the next list, **Backend**, where a backend developer can +drag it to the next list, **Backend**. Then, a backend developer can eventually pick it up. Once they’re done, they move it to **Done**, to close the issue. -This process can be seen clearly when visiting an issue since with every move -to another list the label changes and a system note is recorded. +This process can be seen clearly when visiting an issue. With every move +to another list, the label changes and a system note is recorded. ![issue board system notes](img/issue_board_system_notes.png) diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index c721bef8f4d..2a75f8ad837 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -33,7 +33,7 @@ Of course, you can replace `gitlab.com` with the URL of your own GitLab instance NOTE: **Note:** Linking your first commit to your issue is going to be relevant -for tracking your process with [GitLab Cycle Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). +for tracking your process with [GitLab Value Stream Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). It will measure the time taken for planning the implementation of that issue, which is the time between creating an issue and making the first commit. diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 7c9278c8403..6f57487fccd 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -4,14 +4,12 @@ group: Knowledge info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" --- -# Design Management +# Design Management **(CORE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/660) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. > - Support for SVGs was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12771) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. > - Design Management was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212566) to GitLab Core in 13.0. -## Overview - Design Management allows you to upload design assets (wireframes, mockups, etc.) to GitLab issues and keep them stored in one single place, accessed by the Design Management's page within an issue, giving product designers, product managers, and engineers a @@ -58,8 +56,7 @@ Support for [PDF](https://gitlab.com/gitlab-org/gitlab/issues/32811) is planned - From GitLab 13.1, Design filenames are limited to 255 characters. - Design Management data [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/-/issues/13429) yet. -- Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab/-/issues/13426) - when an issue is moved, nor [deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) +- Design Management data [won't be deleted](https://gitlab.com/gitlab-org/gitlab/-/issues/13427) when an issue is deleted. - From GitLab 12.7, Design Management data [can be replicated](../../../administration/geo/replication/datatypes.md#limitations-on-replicationverification) by Geo but [not verified](https://gitlab.com/gitlab-org/gitlab/-/issues/32467). @@ -114,9 +111,6 @@ Designs with the same filename as an existing uploaded design will create a new of the design, and will replace the previous version. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34353) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9, dropping a design on an existing uploaded design will also create a new version, provided the filenames are the same. -Designs cannot be added if the issue has been moved, or its -[discussion is locked](../../discussions/#lock-discussions). - ### Skipped designs Designs with the same filename as an existing uploaded design _and_ whose content has not changed will be skipped. @@ -185,9 +179,7 @@ viewed by browsing previous versions. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34382) in GitLab 13.3. -You can change the order of designs by dragging them to a new position: - -![Reorder designs](img/designs_reordering_v13_3.gif) +You can change the order of designs by dragging them to a new position. ## Starting discussions on designs @@ -231,47 +223,19 @@ Note that your resolved comment pins will disappear from the Design to free up s However, if you need to revisit or find a resolved discussion, all of your resolved threads will be available in the **Resolved Comment** area at the bottom of the right sidebar. -## Add To-Do for Designs +## Add to dos for designs > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4. -> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-the-design-to-do-button). **(CORE ONLY)** - -CAUTION: **Warning:** -This feature might not be available to you. Check the **version history** note above for details. - -Add a to-do for a design by clicking **Add a To-Do** on the design sidebar: - -![To-Do button](img/design_todo_button_v13_4.png) - -### Enable or disable the design To-Do button **(CORE ONLY)** - -The **Add a To-Do** button for Designs is under development but ready for production use. It is -deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:design_management_todo_button) -``` +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5. -To disable it: +Add a to do for a design by clicking **Add a To Do** on the design sidebar: -```ruby -Feature.disable(:design_management_todo_button) -``` +![To-do button](img/design_todo_button_v13_5.png) ## Referring to designs in Markdown > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217160) in **GitLab 13.1**. -> - It is deployed behind a feature flag, disabled by default. -> - It is disabled on GitLab.com. -> - It is not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-design-references). **(CORE ONLY)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/258662) in **GitLab 13.5** We support referring to designs in [Markdown](../../markdown.md), which is available throughout the application, including in merge request and issue descriptions, in discussions and comments, and in wiki pages. @@ -287,25 +251,6 @@ This will be rendered as: > See [#123[homescreen.png]](https://gitlab.com/your-group/your-project/-/issues/123/designs/homescreen.png) -### Enable or disable design references **(CORE ONLY)** - -Design reference parsing 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 disable it for your instance. - -To disable it: - -```ruby -Feature.disable(:design_management_reference_filter_gfm_pipeline) -``` - -To re-enable it: - -```ruby -Feature.enable(:design_management_reference_filter_gfm_pipeline) -``` - ## Design activity records > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33051) in GitLab 13.1. diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 55b45bf9d3d..b3ebefadef0 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -46,7 +46,7 @@ the icon and the date colored red. You can sort issues by those that are Due dates also appear in your [to-do list](../../todos.md). -![Issues with due dates in the to-dos](img/due_dates_todos.png) +![Issues with due dates in the to dos](img/due_dates_todos.png) The day before an open issue is due, an email will be sent to all participants of the issue. Like the due date, the "day before the due date" is determined by the diff --git a/doc/user/project/issues/img/design_todo_button_v13_4.png b/doc/user/project/issues/img/design_todo_button_v13_4.png deleted file mode 100644 index 62bbecf4ed9..00000000000 Binary files a/doc/user/project/issues/img/design_todo_button_v13_4.png and /dev/null differ diff --git a/doc/user/project/issues/img/design_todo_button_v13_5.png b/doc/user/project/issues/img/design_todo_button_v13_5.png new file mode 100644 index 00000000000..970161a6097 Binary files /dev/null and b/doc/user/project/issues/img/design_todo_button_v13_5.png differ diff --git a/doc/user/project/issues/img/designs_reordering_v13_3.gif b/doc/user/project/issues/img/designs_reordering_v13_3.gif deleted file mode 100644 index 496eea532e2..00000000000 Binary files a/doc/user/project/issues/img/designs_reordering_v13_3.gif and /dev/null differ diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 060266a478f..434af3a4a49 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -156,12 +156,15 @@ collaborate with your team. efficiently and with less effort by tracking groups of issues that share a theme, across projects and milestones. -### Related issues **(STARTER)** +### Related issues You can mark two issues as related, so that when viewing one, the other is always listed in its [Related Issues](related_issues.md) section. This can help display important context, such as past work, dependencies, or duplicates. +Users on [GitLab Starter, GitLab Bronze, and higher tiers](https://about.gitlab.com/pricing/), can +also mark issues as blocking or blocked by another issue. + ### Crosslinking issues You can [cross-link issues](crosslinking_issues.md) by referencing an issue from another diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 5356e6aeb40..003444e0ed8 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -36,7 +36,7 @@ You can find all the information for that issue on one screen. - **15.** [Edit](#edit) - **16.** [Description](#description) - **17.** [Mentions](#mentions) -- **18.** [Related Issues **(STARTER)**](#related-issues) +- **18.** [Related Issues](#related-issues) - **19.** [Related Merge Requests](#related-merge-requests) - **20.** [Award emoji](#award-emoji) - **21.** [Show all activity](#show-all-activity) @@ -80,7 +80,7 @@ The button to do this has a different label depending on whether the issue is al List or not. If the issue is: - Already on your To-Do List: The button is labeled **Mark as done**. Click the button to remove the issue from your To-Do List. -- Not on your To-Do List: The button is labeled **Add a To Do**. Click the button to add the issue to your To-Do List. +- Not on your To-Do List: The button is labeled **Add a to do**. Click the button to add the issue to your To-Do List. ### Assignee @@ -191,7 +191,7 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. -> [Since GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103), changes to an issue's description are listed in the [issue history](#issue-history).**(STARTER)** +> [In GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/10103) and later, changes to an issue's description are listed in the [issue history](#issue-history).**(STARTER)** ### Mentions @@ -208,7 +208,7 @@ TIP: **Tip:** Avoid mentioning `@all` in issues and merge requests, as it sends an email notification to all the members of that project's group, which can be interpreted as spam. -### Related Issues **(STARTER)** +### Related Issues Issues that were mentioned as [related issues](related_issues.md) are listed here. You can also click the `+` to add more related issues. @@ -242,7 +242,7 @@ and selecting either: Also: - You can mention a user or a group present in your GitLab instance with - `@username` or `@groupname` and they will be notified via To-Do items + `@username` or `@groupname` and they will be notified via to-do items and email, unless they have [disabled all notifications](#notifications) in their profile settings. - Mentions for yourself (the current logged in user), will be highlighted diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 0e0731528be..b033dc79dcc 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -127,6 +127,7 @@ field). | title | `issue[title]` | | | description | `issue[description]` | | | description template | `issuable_template` | | +| issue type | `issue[issue_type]` | Either `incident` or `issue` | | confidential | `issue[confidential]` | Parameter value must be `true` to set to confidential | Follow these examples to form your new issue URL with prefilled fields. diff --git a/doc/user/project/issues/multiple_assignees_for_issues.md b/doc/user/project/issues/multiple_assignees_for_issues.md index c11977f5bee..b1806460c08 100644 --- a/doc/user/project/issues/multiple_assignees_for_issues.md +++ b/doc/user/project/issues/multiple_assignees_for_issues.md @@ -8,8 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1904) in [GitLab Starter 9.2](https://about.gitlab.com/releases/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). -## Overview - In large teams, where there is shared ownership of an issue, it can be difficult to track who is working on it, who already completed their contributions, who didn't even start yet. diff --git a/doc/user/project/issues/related_issues.md b/doc/user/project/issues/related_issues.md index 954e3771722..b040bcf3b03 100644 --- a/doc/user/project/issues/related_issues.md +++ b/doc/user/project/issues/related_issues.md @@ -4,33 +4,40 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Related issues **(STARTER)** +# Related issues **(CORE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1797) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.4. +> - The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4. Related issues are a bi-directional relationship between any two issues and appear in a block below the issue description. Issues can be across groups and projects. +You can set any issue as: + +- Related to another issue +- Blocking another issue **(STARTER)** +- Blocked by another issue **(STARTER)** + The relationship only shows up in the UI if the user can see both issues. When you try to close an issue that has open blockers, a warning is displayed. TIP: **Tip:** -To manage related issues through our API, see the [API documentation](../../../api/issue_links.md). +To manage related issues through our API, visit the [issue links API documentation](../../../api/issue_links.md). ## Adding a related issue > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2035) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/34239) to warn when attempting to close an issue that is blocked by others in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. -> When you try to close an issue with open blockers, you'll see a warning that you can dismiss. +> When you try to close an issue with open blockers, you see a warning that you can dismiss. 1. Relate one issue to another by clicking the related issues "+" button in the header of the related issue block. 1. Input the issue reference number or paste in the full URL of the issue. -1. Select whether the current issue relates to, blocks, or is blocked by the issues being entered. +1. **(STARTER)** Select whether the current issue relates to, blocks, or is blocked by the issues being entered. ![Adding a related issue](img/related_issues_add_v12_8.png) @@ -42,11 +49,11 @@ in the header of the related issue block. - same group: `project#44` - different group: `group/project#44` - Valid references will be added to a temporary list that you can review. + Valid references are added to a temporary list that you can review. 1. When you have added all the related issues, click **Add** to submit. -When you have finished adding all related issues, you will be able to see +When you have finished adding all related issues, you can see them categorized so their relationships can be better understood visually. ![Related issue block](img/related_issue_block_v12_8.png) @@ -56,7 +63,7 @@ them categorized so their relationships can be better understood visually. In the related issues block, click the "x" icon on the right-side of each issue token that you wish to remove. -Due to the bi-directional relationship, it will no longer appear in either issue. +Due to the bi-directional relationship, it no longer appears in either issue. ![Removing a related issue](img/related_issues_remove_v12_8.png) diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 0d02b89be7e..4f0354f86af 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Labels -## Overview - As your count of issues, merge requests, and epics grows in GitLab, it's more and more challenging to keep track of those items. Especially as your organization grows from just a few people to hundreds or thousands. This is where labels come in. They help you organize and tag your work @@ -32,18 +30,25 @@ There are two types of labels in GitLab: ## Assign and unassign labels -Every issue, merge request and epic can be assigned any number of labels. The labels are +> Unassigning labels with the **X** button [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216881) in GitLab 13.5. + +Every issue, merge request, and epic can be assigned any number of labels. The labels are managed in the right sidebar, where you can assign or unassign labels as needed. -To assign a label to an issue, merge request or epic: +To assign or unassign a label: -1. In the label section of the sidebar, click **Edit**, then: - - In the list, click the labels you want. Each label is flagged with a checkmark. - - Find labels by entering a search query and clicking search (**{search}**), then - click on them. You can search repeatedly and add more labels. -1. Click **X** or anywhere outside the label section and the labels are applied. +1. In the **Labels** section of the sidebar, click **Edit**. +1. In the **Assign labels** list, search for labels by typing their names. + You can search repeatedly to add more labels. + The selected labels are marked with a checkmark. +1. Click the labels you want to assign or unassign. +1. To apply your changes to labels, click **X** next to **Assign labels** or anywhere outside the + label section. -You can also assign a label with the [`/label ~label1 ~label2` quick action](quick_actions.md). +Alternatively, to unassign a label, click the **X** on the label you want to unassign. + +You can also assign a label with the `/label` [quick action](quick_actions.md), +remove labels with `/unlabel`, and reassign labels (remove all and assign new ones) with `/relabel`. ## Label management @@ -52,10 +57,13 @@ and edit labels. ### Project labels -View the project labels list by going to the project and clicking **Issues > Labels**. +> Showing all inherited labels [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241990) in 13.5. + +To view the project labels list, navigate to the project and click **Issues > Labels**. The list includes all labels that are defined at the project level, as well as all -labels inherited from the immediate parent group. You can filter the list by entering a search -query at the top and clicking search (**{search}**). +labels defined by its ancestor groups. +For each label, you can see the project or group path from where it was created. +You can filter the list by entering a search query at the top and clicking search (**{search}**). To create a new project label: @@ -83,19 +91,19 @@ a label by clicking the three dots (**{ellipsis_v}**) next to the **Subscribe** and selecting **Delete**. CAUTION: **Caution:** -If you delete a label, it is permanently deleted. You will not be able to undo the deletion, and all references to the label will be removed from the system. +If you delete a label, it is permanently deleted. All references to the label are removed from the system and you cannot undo the deletion. #### Promote a project label to a group label If you previously created a project label and now want to make it available for other projects within the same group, you can promote it to a group label. -If other projects in the same group have a label with the same title, they will all be -merged with the new group label. If a group label with the same title exists, it will -also be merged. +If other projects in the same group have a label with the same title, they are all +merged with the new group label. If a group label with the same title exists, it is +also merged. All issues, merge requests, issue board lists, issue board filters, and label subscriptions -with the old labels will be assigned to the new group label. +with the old labels are assigned to the new group label. CAUTION: **Caution:** Promoting a label is a permanent action, and cannot be reversed. @@ -108,7 +116,7 @@ To promote a project label to a group label: ### Group labels -View the group labels list by going to the group and clicking **Issues > Labels**. +To view the group labels list, navigate to the group and click **Issues > Labels**. The list includes all labels that are defined at the group level only. It does not list any labels that are defined in projects. You can filter the list by entering a search query at the top and clicking search (**{search}**). @@ -118,15 +126,15 @@ follow the same process as [creating a project label](#project-labels). #### Create group labels from epics **(ULTIMATE)** -You can create group labels from the Epic sidebar. The labels you create will +You can create group labels from the epic sidebar. The labels you create belong to the immediate group to which the epic belongs. The process is the same as creating a [project label from an issue or merge request](#project-labels). ### Generate default labels If a project or group has no labels, you can generate a default set of project or group -labels from the label list page. The page will show a **Generate a default set of labels** -button if the list is empty, and clicking it will add the following default labels +labels from the label list page. The page shows a **Generate a default set of labels** +button if the list is empty. Select the button to add the following default labels to the project: - `bug` @@ -149,13 +157,13 @@ by preventing certain labels from being used together. A label is scoped when it uses a special double-colon (`::`) syntax in the label’s title, for example: -![Sample scoped labels](img/labels_key_value_v12_1.png) +![Scoped labels](img/labels_key_value_v13_5.png) An issue, merge request or epic cannot have two scoped labels, of the form `key::value`, -with the same `key`. Adding a new label with the same `key`, but a different `value` will -cause the previous `key` label to be replaced with the new label. +with the same `key`. Adding a new label with the same `key`, but a different `value` +causes the previous `key` label to be replaced with the new label. -Example use case: +For example: 1. An issue is identified as being low priority, and a `priority::low` project label is added to it. @@ -188,7 +196,7 @@ This functionality is demonstrated in a video regarding ### Scoped labels with nested scopes You can create a label with a nested scope by using multiple double colons `::` when creating -it. In this case, everything before the last `::` will be the scope. +it. In this case, everything before the last `::` is the scope. For example, `workflow::backend::review` and `workflow::backend::development` are valid scoped labels, but they **can't** exist on the same issue at the same time, as they @@ -202,13 +210,13 @@ both have different scopes, `workflow::frontend` and `workflow::backend`. From the project label list page and the group label list page, you can click **Subscribe** to the right of any label to enable [notifications](../profile/notifications.md) for that -label. You will be notified whenever the label is assigned to an epic, +label. You are notified whenever the label is assigned to an epic, issue, or merge request. If you are subscribing to a group label from within a project, you can select to subscribe to label notifications for the project only, or the whole group. -![Labels subscriptions](img/labels_subscriptions_v12_1.png) +![Labels subscriptions](img/labels_subscriptions_v13_5.png) ## Label priority @@ -222,7 +230,7 @@ from the group label list. From the project label list page, star a label to indicate that it has a priority. -![Labels prioritized](img/labels_prioritized_v12_1.png) +![Labels prioritized](img/labels_prioritized_v13_5.png) Drag starred labels up and down the list to change their priority, where higher in the list means higher priority. diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index f3a0aac9ff4..a07a155745e 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -55,7 +55,7 @@ include: ``` creates an `a11y` job in your CI/CD pipeline, runs -Pa11y against the webpages defined in `a11y_urls`, and builds an HTML report for each. +Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each. The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#browsing-artifacts). diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index 60d247ccc19..4ba0b50a3cf 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -28,11 +28,12 @@ source project and only lasts while the merge request is open. Once enabled, upstream members will also be able to retry the pipelines and jobs of the merge request: -1. Enable the contribution while creating or editing a merge request. +1. While creating or editing a merge request, select the checkbox **Allow + commits from members who can merge to the target branch**. ![Enable contribution](img/allow_collaboration.png) -1. Once the merge request is created, you'll see that commits from members who +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) diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index a0be32e0708..462b8f68ece 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -111,6 +111,48 @@ It is also possible to manage multiple assignees: - When creating a merge request. - Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +## Reviewer + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216054) in GitLab 13.5. +> - It's [deployed behind a feature flag](../../../user/feature_flags.md), enabled by default. +> - It's disabled on GitLab.com. +> - It's not recommended for production use. +> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-merge-request-reviewers). **(CORE ONLY)** + +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. + +Requesting a code review is an important part of contributing code. However, deciding who should review +your code and asking for a review are no easy tasks. Using the "assignee" field for both authors and +reviewers makes it hard for others to determine who's doing what on a merge request. + +GitLab's Merge Request Reviewers easily allow authors to request a review as well as see the status of the +review. By selecting one or more users from the **Reviewers** field in the merge request's right-hand +sidebar, the assigned reviewers will receive a notification of the request to review the merge request. + +This makes it easy to determine the relevant roles for the users involved in the merge request, as well as formally requesting a review from a peer. + +To request it, open the **Reviewers** drop-down box to search for the user you wish to get a review from. + +### Enable or disable Merge Request Reviewers **(CORE ONLY)** + +Merge Request Reviewers 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(:merge_request_reviewers) +``` + +To disable it: + +```ruby +Feature.disable(:merge_request_reviewers) +``` + ### Merge requests to close issues If the merge request is being created to resolve an issue, you can diff --git a/doc/user/project/merge_requests/img/commit_nav_v13_4.png b/doc/user/project/merge_requests/img/commit_nav_v13_4.png new file mode 100644 index 00000000000..0ae6ce32693 Binary files /dev/null and b/doc/user/project/merge_requests/img/commit_nav_v13_4.png differ diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index daebd71e14f..2675f509eed 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -164,8 +164,8 @@ For example: 1. Capture the dynamic URL and save it into a `.env` file, e.g. `echo "ENVIRONMENT_URL=$CI_ENVIRONMENT_URL" >> review.env`. 1. Set the `.env` file to be a [job artifact](../../../ci/pipelines/job_artifacts.md#job-artifacts). 1. In the `load_performance` job: - 1. Set it to depend on the review job, so it inherits the env file. - 1. Set the `K6_DOCKER_OPTIONS` variable with the [Docker cli option for env files](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file), for example `--env-file review.env`. + 1. Set it to depend on the review job, so it inherits the environment file. + 1. Set the `K6_DOCKER_OPTIONS` variable with the [Docker CLI option for environment files](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file), for example `--env-file review.env`. 1. Configure the k6 test script to use the environment variable in it's steps. Your `.gitlab-ci.yml` file might be similar to: diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 185ab0e6298..4b4c930c7af 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -5,13 +5,16 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge Request Approvals +# Merge Request Approvals **(CORE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/580) in GitLab Enterprise Edition 7.2. Available in GitLab Core and higher tiers. +> - Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. Code review is an essential practice of every successful project, and giving your approval once a merge request is in good shape is an important part of the review process, as it clearly communicates the ability to merge the change. -## Optional Approvals **(CORE ONLY)** +## Optional Approvals > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27426) in GitLab 13.2. @@ -335,26 +338,6 @@ of your security team when a vulnerability would be introduced by a merge reques For more information, see [Security approvals in merge requests](../../application_security/index.md#security-approvals-in-merge-requests). -### Enabling the new approvals interface - -Since [GitLab v12.0](https://gitlab.com/gitlab-org/gitlab/-/issues/10685), an updated approvals -interface is available by default. In versions older than 12.0, the updated interface is not -available unless the `approval_rules` feature flag is enabled, which can be done from -the Rails console by instance administrators. - -Use these commands to start the Rails console: - -```shell -# Omnibus GitLab -gitlab-rails console - -# Installation from source -cd /home/git/gitlab -sudo -u git -H bin/rails console -e production -``` - -Then run `Feature.enable(:approval_rules)` to enable the updated interface. - diff --git a/doc/user/project/milestones/burndown_charts.md b/doc/user/project/milestones/burndown_charts.md index 0c8bba831a9..5aa5534dd37 100644 --- a/doc/user/project/milestones/burndown_charts.md +++ b/doc/user/project/milestones/burndown_charts.md @@ -1,89 +1,5 @@ --- -type: reference -stage: Plan -group: Project Management -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +redirect_to: './burndown_and_burnup_charts.md' --- -# Burndown Charts **(STARTER)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1540) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1 for project milestones. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5354) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.8 for group milestones. -> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6495) to [GitLab Starter](https://about.gitlab.com/pricing/) 11.2 for group milestones. -> - Closed or reopened issues prior to GitLab 9.1 won't have a `closed_at` -> value, so the burndown chart considers them as closed on the milestone -> `start_date`. In that case, a warning will be displayed. - -## Overview - -Burndown Charts are visual representations of the progress of completing a milestone. - -![burndown chart](img/burndown_chart.png) - -At a glance, you see the current state for the completion a given milestone. -Without them, you would have to organize the data from the milestone and plot it -yourself to have the same sense of progress. - -GitLab Starter plots it for you and presents it in a clear and beautiful chart. - - -For an overview, check the video demonstration on [Mapping work versus time with Burndown Charts](https://www.youtube.com/watch?v=zJU2MuRChzs). - -## Use cases - -Burndown Charts are generally used for tracking and analyzing the completion of -a milestone. Therefore, their use cases are tied to the -[use you are assigning your milestone to](index.md). - -For example, suppose you lead a team of developers in a large company, -and you follow this workflow: - -- Your company set the goal for the quarter to deliver 10 new features for your app - in the upcoming major release. -- You create a milestone, and remind your team to assign that milestone to every new issue - and merge request that's part of the launch of your app. -- Every week, you open the milestone, visualize the progress, identify the gaps, - and help your team to get their work done. -- Every month, you check in with your supervisor, and show the progress of that milestone - from the Burndown Chart. -- By the end of the quarter, your team successfully delivered 100% of that milestone, as - it was taken care of closely throughout the whole quarter. - -## How it works - -A Burndown Chart is available for every project or group milestone that has been attributed a **start -date** and a **due date**. - -Find your project's **Burndown Chart** under **Project > Issues > Milestones**, -and select a milestone from your current ones, while for group's, access the **Groups** dashboard, -select a group, and go through **Issues > Milestones** on the sidebar. - -NOTE: **Note:** -You're able to [promote project](index.md#promoting-project-milestones-to-group-milestones) to group milestones and still see the **Burndown Chart** for them, respecting license limitations. - -The chart indicates the project's progress throughout that milestone (for issues assigned to it). - -In particular, it shows how many issues were or are still open for a given day in the -milestone's corresponding period. - -The Burndown Chart tracks when issues were created and when they were last closed—not their full history. For each day, it takes the number of issues still open and issues created that day and subtracts the number of issues closed that day. -**Issues that were created and assigned a milestone before its start date—and remain open as of the start date—are considered as having been opened on the start date**. Therefore, when the milestone start date is changed the number of opened issues on each day may change. -Reopened issues are -considered as having been opened on the day after they were last closed. - -The Burndown Chart can also be toggled to display the cumulative open issue -weight for a given day. When using this feature, make sure issue weights have -been properly assigned, since an open issue with no weight adds zero to the -cumulative value. - - +This document was moved to [another location](./burndown_and_burnup_charts.md). diff --git a/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png b/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png new file mode 100644 index 00000000000..8d6ba1d4fa7 Binary files /dev/null and b/doc/user/project/milestones/img/burndown_and_burnup_charts_v13_5.png differ diff --git a/doc/user/project/milestones/img/burndown_chart.png b/doc/user/project/milestones/img/burndown_chart.png deleted file mode 100644 index e06b24f9907..00000000000 Binary files a/doc/user/project/milestones/img/burndown_chart.png and /dev/null differ diff --git a/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png b/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png new file mode 100644 index 00000000000..a532bfeeca0 Binary files /dev/null and b/doc/user/project/milestones/img/burndown_chart_fixed_v13_5.png differ diff --git a/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png b/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png new file mode 100644 index 00000000000..5824fc59ce5 Binary files /dev/null and b/doc/user/project/milestones/img/burndown_chart_legacy_v13_5.png differ diff --git a/doc/user/project/milestones/img/burndown_chart_v13_5.png b/doc/user/project/milestones/img/burndown_chart_v13_5.png new file mode 100644 index 00000000000..e06b24f9907 Binary files /dev/null and b/doc/user/project/milestones/img/burndown_chart_v13_5.png differ diff --git a/doc/user/project/milestones/img/burnup_chart_v13_5.png b/doc/user/project/milestones/img/burnup_chart_v13_5.png new file mode 100644 index 00000000000..a850caba348 Binary files /dev/null and b/doc/user/project/milestones/img/burnup_chart_v13_5.png differ diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 9d02a22f91e..8cbed3de1c6 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -7,8 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Milestones -## Overview - Milestones in GitLab are a way to track issues and merge requests created to achieve a broader goal in a certain period of time. Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date. @@ -152,7 +150,7 @@ There are also tabs below these that show the following: For project milestones in [GitLab Starter](https://about.gitlab.com/pricing/), a [burndown chart](burndown_charts.md) is in the milestone view, showing the progress of completing a milestone. -![burndown chart](img/burndown_chart.png) +![burndown chart](img/burndown_chart_v13_5.png) ### Group Burndown Charts **(STARTER)** diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index c3825371030..a7a72ca4d82 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -223,7 +223,7 @@ This is how an example usage can look like: ```yaml test: script: - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - docker pull $CI_REGISTRY/group/other-project:latest - docker run $CI_REGISTRY/group/other-project:latest ``` @@ -236,5 +236,4 @@ to projects and their project permissions. ### API -GitLab API cannot be used via `CI_JOB_TOKEN` but there is a [proposal](https://gitlab.com/gitlab-org/gitlab/-/issues/35067) -to support it. +GitLab API can be used via `CI_JOB_TOKEN`, see [the relevant documentation](../../api/README.md#gitlab-ci-job-token). diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 735d27ec04d..810538ab460 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -30,6 +30,8 @@ to do it for you. To help you out, we've gathered some instructions on how to do that for the most popular hosting services: + + - [Amazon](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) - [Bluehost](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) - [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) @@ -41,6 +43,8 @@ for the most popular hosting services: - [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain) - [Microsoft](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-2000-server/bb727018(v=technet.10)) + + If your hosting service is not listed above, you can just try to search the web for `how to add dns record on `. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index badafa478ef..9b43dd58afe 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -61,7 +61,6 @@ according to the type of domain you want to use with your Pages site: - [For subdomains](#for-subdomains), `subdomain.example.com`. - [For both](#for-both-root-and-subdomains). -NOTE: **Note:** You can [configure IPv6 on self-managed instances](../../../../administration/pages/index.md#advanced-configuration), but IPv6 is not currently configured for Pages on GitLab.com. Follow [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/214718) for details. @@ -250,8 +249,8 @@ You can use any certificate satisfying the following requirements: - **A private key**, it's an encrypted key which validates your PEM against your domain. -NOTE: **Note:** -[Cloudflare certificates](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), for example, meet these requirements. +For example, [Cloudflare certificates](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) +meet these requirements. #### Steps @@ -269,7 +268,6 @@ NOTE: **Note:** just jumping a line between them. 1. Copy your private key and paste it in the last field. -NOTE: **Note:** **Do not** open certificates or encryption keys in regular text editors. Always use code editors (such as Sublime Text, Atom, Dreamweaver, Brackets, etc). @@ -290,8 +288,8 @@ To enable this setting: 1. Navigate to your project's **Settings > Pages**. 1. Tick the checkbox **Force HTTPS (requires valid certificates)**. -NOTE: **Note:** -If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to `full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://support.cloudflare.com/hc/en-us/articles/200170416-End-to-end-HTTPS-with-Cloudflare-Part-3-SSL-options#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef). +If you use Cloudflare CDN in front of GitLab Pages, make sure to set the SSL connection setting to +`full` instead of `flexible`. For more details, see the [Cloudflare CDN directions](https://support.cloudflare.com/hc/en-us/articles/200170416-End-to-end-HTTPS-with-Cloudflare-Part-3-SSL-options#h_4e0d1a7c-eb71-4204-9e22-9d3ef9ef7fef).