From 0653e08efd039a5905f3fa4f6e9cef9f5d2f799c Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Mon, 20 Sep 2021 13:18:24 +0000 Subject: Add latest changes from gitlab-org/gitlab@14-3-stable-ee --- doc/.vale/gitlab/Acronyms.yml | 1 + doc/.vale/gitlab/BadgeCapitalization.yml | 3 +- doc/.vale/gitlab/CurlStringsQuoted.yml | 2 +- doc/.vale/gitlab/ElementDescriptors.yml | 14 + doc/.vale/gitlab/HeaderGerunds.yml | 14 - doc/.vale/gitlab/InternalLinkExtension.yml | 2 +- doc/.vale/gitlab/InternalLinkFormat.yml | 2 +- doc/.vale/gitlab/OutdatedVersions.yml | 2 + doc/.vale/gitlab/ReadingLevel.yml | 1 + doc/.vale/gitlab/SubstitutionSuggestions.yml | 2 + doc/.vale/gitlab/UnclearAntecedent.yml | 22 + doc/.vale/gitlab/VersionText.yml | 8 +- doc/.vale/gitlab/spelling-exceptions.txt | 10 + doc/administration/audit_events.md | 22 +- doc/administration/auditor_users.md | 2 +- doc/administration/auth/atlassian.md | 2 +- doc/administration/auth/ldap/google_secure_ldap.md | 4 +- doc/administration/auth/ldap/index.md | 64 +- .../auth/ldap/ldap-troubleshooting.md | 20 +- doc/administration/auth/smartcard.md | 6 +- doc/administration/cicd.md | 75 + doc/administration/clusters/kas.md | 22 + doc/administration/compliance.md | 1 + doc/administration/configure.md | 2 +- doc/administration/consul.md | 2 +- doc/administration/database_load_balancing.md | 8 +- doc/administration/encrypted_configuration.md | 6 +- .../disaster_recovery/background_verification.md | 10 +- .../geo/disaster_recovery/planned_failover.md | 10 +- .../runbooks/planned_failover_multi_node.md | 8 +- .../runbooks/planned_failover_single_node.md | 6 +- doc/administration/geo/index.md | 14 +- .../geo/replication/configuration.md | 8 +- doc/administration/geo/replication/datatypes.md | 16 +- doc/administration/geo/replication/disable_geo.md | 2 +- .../geo/replication/docker_registry.md | 2 +- doc/administration/geo/replication/faq.md | 2 +- .../geo/replication/object_storage.md | 16 +- .../geo/replication/remove_geo_site.md | 2 +- .../geo/replication/troubleshooting.md | 6 +- doc/administration/geo/replication/tuning.md | 2 +- .../geo/replication/updating_the_geo_nodes.md | 53 +- .../geo/replication/updating_the_geo_sites.md | 54 + doc/administration/geo/replication/usage.md | 12 +- .../geo/replication/version_specific_updates.md | 39 +- doc/administration/geo/setup/database.md | 77 +- doc/administration/geo/setup/external_database.md | 2 +- doc/administration/get_started.md | 6 +- doc/administration/git_protocol.md | 2 +- doc/administration/gitaly/configure_gitaly.md | 11 +- doc/administration/gitaly/index.md | 79 +- doc/administration/gitaly/praefect.md | 34 +- doc/administration/gitaly/troubleshooting.md | 8 +- doc/administration/housekeeping.md | 10 +- doc/administration/incoming_email.md | 6 +- doc/administration/index.md | 8 +- doc/administration/instance_limits.md | 99 +- doc/administration/instance_review.md | 2 +- doc/administration/integration/kroki.md | 2 +- doc/administration/integration/mailgun.md | 41 + doc/administration/integration/plantuml.md | 4 +- doc/administration/integration/terminal.md | 2 +- doc/administration/job_artifacts.md | 21 + doc/administration/job_logs.md | 4 +- doc/administration/logs.md | 24 +- doc/administration/maintenance_mode/index.md | 8 +- doc/administration/merge_request_diffs.md | 6 + .../gitlab_self_monitoring_project/index.md | 6 +- .../monitoring/performance/gitlab_configuration.md | 2 +- .../performance/grafana_configuration.md | 4 +- .../monitoring/performance/performance_bar.md | 4 +- .../monitoring/prometheus/gitlab_exporter.md | 7 +- .../monitoring/prometheus/gitlab_metrics.md | 16 +- doc/administration/monitoring/prometheus/index.md | 8 +- doc/administration/object_storage.md | 15 +- .../operations/cleaning_up_redis_sessions.md | 65 +- .../operations/extra_sidekiq_processes.md | 2 +- .../operations/extra_sidekiq_routing.md | 31 + .../operations/fast_ssh_key_lookup.md | 2 +- doc/administration/operations/index.md | 5 - .../operations/moving_repositories.md | 5 + doc/administration/operations/puma.md | 50 +- .../operations/sidekiq_memory_killer.md | 2 +- doc/administration/operations/ssh_certificates.md | 3 +- doc/administration/operations/unicorn.md | 9 - doc/administration/package_information/defaults.md | 72 + .../package_information/deprecated_os.md | 82 + .../package_information/deprecation_policy.md | 95 + doc/administration/package_information/index.md | 101 ++ .../package_information/licensing.md | 79 + .../package_information/omnibus_packages.md | 115 ++ .../package_information/postgresql_versions.md | 42 + .../package_information/signed_packages.md | 25 + doc/administration/packages/container_registry.md | 78 +- doc/administration/packages/dependency_proxy.md | 2 +- .../packages/img/gitlab-registry-architecture.png | Bin 0 -> 31003 bytes doc/administration/packages/index.md | 27 +- doc/administration/pages/index.md | 124 +- doc/administration/pages/source.md | 2 +- doc/administration/polling.md | 2 +- doc/administration/postgresql/pgbouncer.md | 2 +- .../postgresql/replication_and_failover.md | 16 +- doc/administration/pseudonymizer.md | 2 +- doc/administration/raketasks/check.md | 25 +- doc/administration/raketasks/github_import.md | 2 +- doc/administration/raketasks/ldap.md | 5 +- doc/administration/raketasks/praefect.md | 2 +- .../raketasks/project_import_export.md | 2 +- doc/administration/raketasks/storage.md | 2 +- .../redis/replication_and_failover_external.md | 2 +- doc/administration/redis/troubleshooting.md | 2 +- .../reference_architectures/10k_users.md | 4 +- .../reference_architectures/1k_users.md | 2 +- .../reference_architectures/25k_users.md | 2 +- .../reference_architectures/2k_users.md | 2 +- .../reference_architectures/3k_users.md | 2 +- .../reference_architectures/50k_users.md | 2 +- .../reference_architectures/5k_users.md | 2 +- .../reference_architectures/index.md | 4 +- .../reference_architectures/troubleshooting.md | 2 +- doc/administration/repository_checks.md | 6 +- doc/administration/repository_storage_paths.md | 2 +- doc/administration/repository_storage_types.md | 2 +- .../static_objects_external_storage.md | 4 +- .../troubleshooting/diagnostics_tools.md | 5 - .../troubleshooting/elasticsearch.md | 2 +- .../troubleshooting/gitlab_rails_cheat_sheet.md | 21 +- doc/administration/troubleshooting/log_parsing.md | 6 + doc/administration/troubleshooting/postgresql.md | 6 +- .../troubleshooting/tracing_correlation_id.md | 10 +- doc/administration/uploads.md | 4 +- doc/administration/whats-new.md | 2 +- doc/api/access_requests.md | 2 +- doc/api/admin_sidekiq_queues.md | 19 +- doc/api/api_resources.md | 6 +- doc/api/applications.md | 2 +- doc/api/avatar.md | 2 +- doc/api/award_emoji.md | 2 +- doc/api/boards.md | 2 +- doc/api/branches.md | 6 +- doc/api/broadcast_messages.md | 4 +- doc/api/bulk_imports.md | 2 +- doc/api/commits.md | 6 +- doc/api/container_registry.md | 4 +- doc/api/custom_attributes.md | 2 +- doc/api/dependency_proxy.md | 7 +- doc/api/deploy_keys.md | 15 +- doc/api/deploy_tokens.md | 4 +- doc/api/deployments.md | 2 +- doc/api/discussions.md | 205 ++- doc/api/dora/metrics.md | 4 +- doc/api/dora4_project_analytics.md | 2 +- doc/api/environments.md | 4 +- doc/api/epic_links.md | 2 +- doc/api/error_tracking.md | 86 +- doc/api/events.md | 8 +- doc/api/feature_flag_specs.md | 2 +- doc/api/features.md | 2 +- doc/api/freeze_periods.md | 2 +- doc/api/geo_nodes.md | 27 + doc/api/graphql/audit_report.md | 2 +- doc/api/graphql/custom_emoji.md | 4 +- doc/api/graphql/index.md | 2 +- doc/api/graphql/reference/index.md | 1891 ++++++++++++++------ doc/api/graphql/removed_items.md | 4 +- doc/api/graphql/users_example.md | 2 +- doc/api/group_activity_analytics.md | 2 +- doc/api/group_badges.md | 2 +- doc/api/group_boards.md | 14 +- doc/api/group_import_export.md | 2 +- doc/api/group_labels.md | 4 +- doc/api/group_level_variables.md | 2 +- doc/api/group_milestones.md | 2 +- doc/api/group_protected_environments.md | 14 +- doc/api/group_relations_export.md | 2 +- doc/api/group_wikis.md | 2 +- doc/api/groups.md | 19 +- doc/api/index.md | 160 +- doc/api/instance_clusters.md | 2 +- doc/api/instance_level_ci_variables.md | 2 +- doc/api/issue_links.md | 2 +- doc/api/issues.md | 73 +- doc/api/job_artifacts.md | 10 +- doc/api/jobs.md | 2 +- doc/api/labels.md | 4 +- doc/api/lint.md | 4 +- doc/api/members.md | 6 +- doc/api/merge_request_approvals.md | 4 +- doc/api/merge_requests.md | 28 +- doc/api/metrics_dashboard_annotations.md | 2 +- doc/api/metrics_user_starred_dashboards.md | 2 +- doc/api/milestones.md | 2 +- doc/api/notification_settings.md | 2 +- doc/api/oauth2.md | 44 +- doc/api/packages.md | 2 +- doc/api/packages/composer.md | 15 +- doc/api/packages/conan.md | 2 +- doc/api/packages/go_proxy.md | 2 +- doc/api/packages/helm.md | 10 +- doc/api/packages/maven.md | 2 +- doc/api/packages/npm.md | 12 +- doc/api/packages/nuget.md | 4 +- doc/api/packages/pypi.md | 10 +- doc/api/packages/rubygems.md | 2 +- doc/api/pages.md | 2 +- doc/api/pages_domains.md | 2 +- doc/api/personal_access_tokens.md | 10 +- doc/api/pipeline_triggers.md | 3 + doc/api/pipelines.md | 6 +- doc/api/plan_limits.md | 2 +- doc/api/project_aliases.md | 2 +- doc/api/project_clusters.md | 2 +- doc/api/project_level_variables.md | 2 +- doc/api/project_vulnerabilities.md | 2 +- doc/api/projects.md | 18 +- doc/api/protected_environments.md | 2 +- doc/api/releases/index.md | 36 +- doc/api/releases/links.md | 2 +- doc/api/repositories.md | 20 +- doc/api/resource_access_tokens.md | 2 +- doc/api/resource_label_events.md | 2 +- doc/api/runners.md | 57 +- doc/api/scim.md | 2 +- doc/api/services.md | 14 +- doc/api/settings.md | 22 +- doc/api/statistics.md | 2 +- doc/api/status_checks.md | 12 +- doc/api/system_hooks.md | 4 +- doc/api/templates/dockerfiles.md | 2 +- doc/api/templates/gitignores.md | 2 +- doc/api/templates/gitlab_ci_ymls.md | 2 +- doc/api/templates/licenses.md | 2 +- doc/api/usage_data.md | 4 +- doc/api/users.md | 105 +- doc/api/v3_to_v4.md | 2 +- doc/api/version.md | 2 +- doc/api/vulnerabilities.md | 2 +- doc/api/vulnerability_exports.md | 4 +- doc/api/vulnerability_findings.md | 2 +- .../index.md | 3 + .../container_registry_metadata_database/index.md | 44 +- .../patterns/img/db_terminology_v14_2.png | Bin 51264 -> 0 bytes .../img/read_mostly_licenses_calls_v14_2.png | Bin 157824 -> 50040 bytes .../img/read_mostly_licenses_fixed_v14_2.png | Bin 85790 -> 33505 bytes .../img/read_mostly_readwriteratio_v14_2.png | Bin 93291 -> 26819 bytes .../img/read_mostly_subscriptions_reads_v14_2.png | Bin 60703 -> 22800 bytes .../img/read_mostly_subscriptions_writes_v14_2.png | Bin 52727 -> 22380 bytes doc/ci/caching/index.md | 10 +- doc/ci/chatops/index.md | 4 +- .../ci_cd_for_external_repos/github_integration.md | 4 +- doc/ci/ci_cd_for_external_repos/index.md | 4 +- doc/ci/cloud_deployment/index.md | 2 +- doc/ci/directed_acyclic_graph/index.md | 2 +- doc/ci/docker/using_docker_build.md | 2 +- doc/ci/enable_or_disable_ci.md | 79 +- doc/ci/environments/deployment_safety.md | 4 +- doc/ci/environments/environments_dashboard.md | 2 +- doc/ci/environments/incremental_rollouts.md | 4 +- doc/ci/environments/index.md | 53 +- doc/ci/environments/protected_environments.md | 35 +- .../end_to_end_testing_webdriverio/index.md | 4 +- doc/ci/examples/index.md | 21 +- doc/ci/index.md | 71 +- doc/ci/interactive_web_terminal/index.md | 5 +- doc/ci/jobs/ci_job_token.md | 165 ++ doc/ci/jobs/img/job_group_v12_10.png | Bin 5436 -> 0 bytes doc/ci/jobs/img/pipeline_delayed_job_v14_2.png | Bin 0 -> 27591 bytes doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png | Bin 0 -> 38540 bytes doc/ci/jobs/img/pipeline_incremental_rollout.png | Bin 4794 -> 0 bytes doc/ci/jobs/img/pipelines_grouped.png | Bin 12888 -> 0 bytes doc/ci/jobs/index.md | 10 +- doc/ci/jobs/job_control.md | 35 +- doc/ci/large_repositories/index.md | 9 +- doc/ci/lint.md | 7 +- doc/ci/migration/circleci.md | 12 +- doc/ci/migration/jenkins.md | 8 +- doc/ci/pipeline_editor/index.md | 2 +- doc/ci/pipelines/img/manual_pipeline_v14_2.png | Bin 0 -> 24536 bytes doc/ci/pipelines/img/pipelines.png | Bin 6298 -> 0 bytes .../img/pipelines_graph_stage_view_v13_12.png | Bin 25204 -> 0 bytes .../img/pipelines_graph_stage_view_v14_2.png | Bin 0 -> 29978 bytes doc/ci/pipelines/index.md | 29 +- doc/ci/pipelines/multi_project_pipelines.md | 2 +- doc/ci/pipelines/parent_child_pipelines.md | 9 +- doc/ci/pipelines/pipeline_efficiency.md | 1 + doc/ci/pipelines/settings.md | 3 +- doc/ci/quick_start/index.md | 23 +- doc/ci/review_apps/index.md | 2 +- doc/ci/runners/build_cloud/macos/environment.md | 6 +- doc/ci/runners/build_cloud/macos_build_cloud.md | 4 +- doc/ci/runners/configure_runners.md | 70 +- doc/ci/runners/index.md | 2 +- doc/ci/runners/runners_scope.md | 8 +- doc/ci/secrets/index.md | 2 +- doc/ci/services/gitlab.md | 9 +- doc/ci/services/index.md | 58 +- doc/ci/services/mysql.md | 14 +- doc/ci/services/postgres.md | 24 +- doc/ci/services/redis.md | 2 +- doc/ci/triggers/index.md | 75 +- doc/ci/troubleshooting.md | 4 +- doc/ci/variables/index.md | 37 +- doc/ci/variables/predefined_variables.md | 7 +- doc/ci/variables/where_variables_can_be_used.md | 35 +- doc/ci/yaml/gitlab_ci_yaml.md | 2 +- doc/ci/yaml/includes.md | 187 +- doc/ci/yaml/index.md | 306 ++-- doc/ci/yaml/script.md | 2 +- doc/development/adding_service_component.md | 3 +- doc/development/api_graphql_styleguide.md | 6 +- doc/development/application_limits.md | 4 +- doc/development/architecture.md | 6 +- doc/development/avoiding_downtime_in_migrations.md | 24 +- doc/development/background_migrations.md | 21 +- doc/development/cascading_settings.md | 4 +- doc/development/changelog.md | 1 + .../cicd/cicd_reference_documentation_guide.md | 2 +- doc/development/cicd/index.md | 8 +- doc/development/cicd/templates.md | 14 +- doc/development/code_intelligence/index.md | 2 +- doc/development/code_review.md | 92 +- doc/development/contributing/community_roles.md | 4 - doc/development/contributing/design.md | 18 +- doc/development/contributing/issue_workflow.md | 31 +- .../contributing/merge_request_workflow.md | 37 +- doc/development/contributing/style_guides.md | 9 +- .../database/add_foreign_key_to_existing_column.md | 34 +- .../database/constraint_naming_convention.md | 5 +- .../database/database_reviewer_guidelines.md | 4 +- .../database/efficient_in_operator_queries.md | 949 ++++++++++ doc/development/database/index.md | 1 + doc/development/database/keyset_pagination.md | 29 +- doc/development/database/multiple_databases.md | 236 ++- doc/development/database/not_null_constraints.md | 16 +- doc/development/database/pagination_guidelines.md | 2 +- doc/development/database/rename_database_tables.md | 4 +- .../database/strings_and_the_text_data_type.md | 53 +- doc/development/database/table_partitioning.md | 6 +- doc/development/database/transaction_guidelines.md | 2 +- doc/development/database_debugging.md | 36 + doc/development/database_review.md | 4 +- doc/development/deprecation_guidelines/index.md | 2 +- doc/development/documentation/feature_flags.md | 27 +- doc/development/documentation/index.md | 203 +-- doc/development/documentation/redirects.md | 155 ++ doc/development/documentation/review_apps.md | 101 ++ .../documentation/site_architecture/index.md | 11 - doc/development/documentation/styleguide/index.md | 204 +-- .../documentation/styleguide/word_list.md | 348 ++-- doc/development/documentation/testing.md | 34 +- doc/development/elasticsearch.md | 7 +- .../experiment_guide/experimentation.md | 2 +- doc/development/experiment_guide/index.md | 30 +- doc/development/fe_guide/accessibility.md | 4 +- doc/development/fe_guide/axios.md | 2 +- doc/development/fe_guide/content_editor.md | 376 +++- doc/development/fe_guide/development_process.md | 2 +- doc/development/fe_guide/graphql.md | 44 +- .../img/content_editor_highlevel_diagram.png | Bin 47794 -> 0 bytes doc/development/fe_guide/index.md | 2 +- doc/development/fe_guide/source_editor.md | 2 +- doc/development/github_importer.md | 13 + doc/development/go_guide/dependencies.md | 2 +- doc/development/go_guide/index.md | 6 +- doc/development/gotchas.md | 70 - doc/development/graphql_guide/graphql_pro.md | 4 +- doc/development/graphql_guide/index.md | 4 +- doc/development/graphql_guide/pagination.md | 4 +- doc/development/i18n/externalization.md | 63 +- doc/development/i18n/proofreader.md | 5 +- doc/development/img/elasticsearch_architecture.svg | 2 +- doc/development/import_project.md | 2 +- doc/development/integrations/jenkins.md | 4 +- doc/development/integrations/jira_connect.md | 2 +- doc/development/integrations/secure.md | 8 +- doc/development/internal_api.md | 54 +- doc/development/issue_types.md | 5 +- doc/development/migration_style_guide.md | 161 +- doc/development/multi_version_compatibility.md | 4 +- doc/development/packages.md | 2 +- doc/development/pipelines.md | 54 +- doc/development/prometheus_metrics.md | 4 +- doc/development/query_recorder.md | 8 +- doc/development/rake_tasks.md | 12 +- doc/development/secure_coding_guidelines.md | 2 + doc/development/service_ping/implement.md | 862 ++++++++- doc/development/service_ping/index.md | 849 +-------- doc/development/service_ping/metrics_dictionary.md | 18 +- .../service_ping/metrics_instrumentation.md | 4 +- doc/development/service_ping/metrics_lifecycle.md | 4 +- doc/development/service_ping/review_guidelines.md | 2 +- doc/development/sidekiq_style_guide.md | 6 +- doc/development/single_table_inheritance.md | 4 +- doc/development/snowplow/index.md | 47 +- doc/development/snowplow/review_guidelines.md | 4 +- doc/development/sql.md | 4 +- doc/development/stage_group_dashboards.md | 2 +- doc/development/testing_guide/best_practices.md | 86 +- .../testing_guide/end_to_end/beginners_guide.md | 4 +- .../testing_guide/end_to_end/best_practices.md | 106 +- doc/development/testing_guide/end_to_end/index.md | 39 + .../end_to_end/rspec_metadata_tests.md | 1 + doc/development/testing_guide/frontend_testing.md | 193 +- doc/development/testing_guide/index.md | 4 +- doc/development/testing_guide/review_apps.md | 2 +- doc/development/testing_guide/testing_levels.md | 13 +- doc/development/transient/prevention-patterns.md | 2 +- doc/development/understanding_explain_plans.md | 2 +- doc/development/work_items.md | 196 ++ doc/downgrade_ee_to_ce/index.md | 93 +- doc/install/aws/eks_clusters_aws.md | 53 + doc/install/aws/gitlab_hybrid_on_aws.md | 362 ++++ doc/install/aws/gitlab_sre_for_aws.md | 59 + doc/install/aws/index.md | 866 +-------- doc/install/aws/manual_install_aws.md | 850 +++++++++ doc/install/azure/index.md | 2 +- doc/install/docker.md | 8 +- doc/install/installation.md | 6 +- doc/install/next_steps.md | 2 +- doc/install/requirements.md | 20 +- doc/integration/akismet.md | 4 +- doc/integration/auth0.md | 4 +- doc/integration/azure.md | 48 +- doc/integration/bitbucket.md | 4 +- doc/integration/cas.md | 6 +- doc/integration/datadog.md | 4 +- doc/integration/elasticsearch.md | 191 +- doc/integration/facebook.md | 18 +- doc/integration/github.md | 2 +- doc/integration/gitlab.md | 2 +- doc/integration/gitpod.md | 6 +- doc/integration/gmail_action_buttons_for_gitlab.md | 5 +- doc/integration/google.md | 18 +- doc/integration/jenkins.md | 2 +- doc/integration/jenkins_deprecated.md | 5 +- doc/integration/jira/configure.md | 2 +- doc/integration/jira/connect-app.md | 28 +- doc/integration/jira/development_panel.md | 8 +- doc/integration/jira/dvcs.md | 44 +- doc/integration/jira/index.md | 13 +- doc/integration/jira/jira_cloud_configuration.md | 6 +- doc/integration/jira/jira_server_configuration.md | 2 +- doc/integration/kerberos.md | 14 +- doc/integration/mattermost/gitlab-mattermost.msc | 28 + .../mattermost/img/gitlab-mattermost.png | Bin 0 -> 88419 bytes doc/integration/mattermost/index.md | 495 +++++ doc/integration/oauth_provider.md | 16 +- doc/integration/omniauth.md | 207 ++- doc/integration/openid_connect_provider.md | 5 +- doc/integration/recaptcha.md | 14 +- doc/integration/saml.md | 98 +- doc/integration/slash_commands.md | 40 +- doc/integration/sourcegraph.md | 4 +- doc/integration/trello_power_up.md | 2 +- doc/integration/twitter.md | 5 +- doc/integration/vault.md | 2 +- doc/intro/index.md | 50 +- doc/operations/error_tracking.md | 53 +- .../img/error_tracking_setting_v14_3.png | Bin 0 -> 27537 bytes doc/operations/metrics/alerts.md | 2 +- doc/policy/alpha-beta-support.md | 40 + doc/policy/maintenance.md | 4 +- doc/public_access/public_access.md | 24 +- doc/push_rules/push_rules.md | 8 +- doc/raketasks/backup_restore.md | 103 +- doc/raketasks/cleanup.md | 4 - doc/raketasks/features.md | 5 +- doc/security/password_length_limits.md | 2 +- doc/security/rack_attack.md | 2 +- doc/security/rate_limits.md | 1 + doc/security/ssh_keys_restrictions.md | 14 +- doc/security/token_overview.md | 6 +- doc/security/two_factor_authentication.md | 57 +- doc/security/user_email_confirmation.md | 2 +- doc/security/webhooks.md | 8 +- doc/ssh/index.md | 4 +- doc/subscriptions/bronze_starter.md | 10 +- doc/subscriptions/gitlab_com/index.md | 29 +- doc/subscriptions/quarterly_reconciliation.md | 28 + doc/subscriptions/self_managed/index.md | 10 +- doc/system_hooks/system_hooks.md | 4 +- doc/tools/email.md | 4 +- doc/topics/authentication/index.md | 6 +- doc/topics/autodevops/customize.md | 11 +- doc/topics/autodevops/index.md | 45 +- doc/topics/autodevops/prepare_deployment.md | 4 +- doc/topics/autodevops/quick_start_guide.md | 3 +- doc/topics/autodevops/requirements.md | 12 +- doc/topics/autodevops/stages.md | 9 +- .../upgrading_auto_deploy_dependencies.md | 4 +- doc/topics/git/cherry_picking.md | 55 +- doc/topics/git/git_rebase.md | 9 +- doc/topics/git/index.md | 6 +- doc/topics/git/lfs/migrate_to_git_lfs.md | 5 + .../numerous_undo_possibilities_in_git/index.md | 3 +- doc/topics/gitlab_flow.md | 171 +- doc/topics/img/gitlab_flow.png | Bin 46844 -> 0 bytes doc/topics/img/gitlab_flow_ci_mr.png | Bin 12024 -> 0 bytes doc/topics/img/gitlab_flow_close_issue_mr.png | Bin 42108 -> 0 bytes .../img/gitlab_flow_environment_branches.png | Bin 12354 -> 0 bytes doc/topics/img/gitlab_flow_four_stages.png | Bin 7124 -> 0 bytes doc/topics/img/gitlab_flow_git_pull.png | Bin 28701 -> 0 bytes doc/topics/img/gitlab_flow_github_flow.png | Bin 6173 -> 0 bytes doc/topics/img/gitlab_flow_good_commit.png | Bin 8740 -> 0 bytes doc/topics/img/gitlab_flow_merge_commits.png | Bin 7564 -> 0 bytes doc/topics/img/gitlab_flow_merge_request.png | Bin 47225 -> 0 bytes doc/topics/img/gitlab_flow_messy_flow.png | Bin 11663 -> 0 bytes doc/topics/img/gitlab_flow_production_branch.png | Bin 7262 -> 0 bytes doc/topics/img/gitlab_flow_rebase.png | Bin 28939 -> 0 bytes doc/topics/img/gitlab_flow_release_branches.png | Bin 12736 -> 0 bytes doc/topics/offline/index.md | 2 +- doc/topics/offline/quick_start_guide.md | 2 +- doc/update/deprecations.md | 67 + doc/update/index.md | 144 +- doc/update/package/convert_to_ee.md | 118 ++ doc/update/package/downgrade.md | 83 + doc/update/package/index.md | 278 +++ doc/update/patch_versions.md | 2 +- doc/update/plan_your_upgrade.md | 180 ++ doc/update/upgrading_from_ce_to_ee.md | 2 +- doc/update/upgrading_from_source.md | 14 +- doc/update/zero_downtime.md | 942 ++++++++++ doc/user/admin_area/analytics/dev_ops_report.md | 7 +- .../analytics/img/admin_devops_adoption_v14_2.png | Bin 67833 -> 25280 bytes doc/user/admin_area/analytics/index.md | 4 +- doc/user/admin_area/analytics/usage_trends.md | 2 +- doc/user/admin_area/appearance.md | 4 +- doc/user/admin_area/broadcast_messages.md | 6 +- doc/user/admin_area/credentials_inventory.md | 2 +- doc/user/admin_area/diff_limits.md | 4 +- doc/user/admin_area/geo_nodes.md | 4 +- doc/user/admin_area/index.md | 44 +- doc/user/admin_area/license.md | 10 +- doc/user/admin_area/merge_requests_approvals.md | 4 +- doc/user/admin_area/moderate_users.md | 33 +- doc/user/admin_area/monitoring/health_check.md | 4 +- doc/user/admin_area/review_abuse_reports.md | 4 +- .../settings/account_and_limit_settings.md | 48 +- .../admin_area/settings/continuous_integration.md | 28 +- doc/user/admin_area/settings/email.md | 20 +- .../admin_area/settings/external_authorization.md | 4 +- doc/user/admin_area/settings/floc.md | 4 +- .../admin_area/settings/git_lfs_rate_limits.md | 35 + doc/user/admin_area/settings/gitaly_timeouts.md | 2 +- doc/user/admin_area/settings/help_page.md | 15 +- .../settings/img/domain_denylist_v14_1.png | Bin 49389 -> 31473 bytes .../img/import_export_rate_limits_v13_2.png | Bin 18320 -> 0 bytes .../img/rate_limit_on_issues_creation_v14_2.png | Bin 29368 -> 10102 bytes .../settings/img/user_and_ip_rate_limits.png | Bin 36909 -> 0 bytes .../settings/import_export_rate_limits.md | 34 +- doc/user/admin_area/settings/index.md | 15 +- .../settings/instance_template_repository.md | 6 +- .../settings/package_registry_rate_limits.md | 53 +- .../settings/project_integration_management.md | 12 +- .../settings/push_event_activities_limit.md | 4 +- .../settings/rate_limit_on_issues_creation.md | 2 +- .../settings/rate_limit_on_notes_creation.md | 10 +- .../settings/rate_limits_on_raw_endpoints.md | 4 +- doc/user/admin_area/settings/sidekiq_job_limits.md | 36 + .../admin_area/settings/sign_in_restrictions.md | 8 +- .../admin_area/settings/sign_up_restrictions.md | 28 +- doc/user/admin_area/settings/terms.md | 4 +- doc/user/admin_area/settings/third_party_offers.md | 2 +- doc/user/admin_area/settings/usage_statistics.md | 7 +- .../admin_area/settings/user_and_ip_rate_limits.md | 85 +- .../settings/visibility_and_access_controls.md | 56 +- doc/user/admin_area/user_cohorts.md | 4 +- doc/user/analytics/index.md | 10 +- doc/user/analytics/issue_analytics.md | 7 +- doc/user/analytics/merge_request_analytics.md | 9 +- doc/user/analytics/productivity_analytics.md | 6 +- doc/user/analytics/value_stream_analytics.md | 4 +- doc/user/application_security/api_fuzzing/index.md | 17 +- .../application_security/configuration/index.md | 65 +- .../container_scanning/index.md | 70 +- .../application_security/coverage_fuzzing/index.md | 21 +- .../application_security/dast/browser_based.md | 2 +- .../dast/dast_troubleshooting.md | 4 + doc/user/application_security/dast/index.md | 157 +- doc/user/application_security/dast_api/index.md | 2 +- .../application_security/dependency_list/index.md | 8 +- .../dependency_scanning/index.md | 34 +- .../img/mr_security_scanning_results_v14_3.png | Bin 0 -> 32391 bytes doc/user/application_security/index.md | 19 +- .../offline_deployments/index.md | 2 +- .../img/container_policy_rule_mode_v14_3.png | Bin 0 -> 39343 bytes .../img/container_policy_yaml_mode_v14_3.png | Bin 0 -> 50096 bytes .../policies/img/policies_list_v14_3.png | Bin 0 -> 34232 bytes .../img/scan_execution_policy_yaml_mode_v14_3.png | Bin 0 -> 23658 bytes .../policies/img/security_policy_project_v14_3.png | Bin 0 -> 29763 bytes doc/user/application_security/policies/index.md | 281 ++- doc/user/application_security/sast/analyzers.md | 4 +- doc/user/application_security/sast/index.md | 29 +- .../application_security/secret_detection/index.md | 7 +- .../img/pipeline_security_dashboard_v14_2.png | Bin 83851 -> 46428 bytes .../security_dashboard/index.md | 35 +- doc/user/application_security/terminology/index.md | 12 + .../threat_monitoring_policy_alert_list_v13_12.png | Bin 22929 -> 0 bytes .../threat_monitoring_policy_alert_list_v14_3.png | Bin 0 -> 17296 bytes .../threat_monitoring/index.md | 152 +- .../application_security/vulnerabilities/index.md | 4 +- .../img/group_vulnerability_report_v14_2.png | Bin 109933 -> 65346 bytes ...ject_security_dashboard_status_change_v14_2.png | Bin 63558 -> 37318 bytes .../vulnerability_report/index.md | 22 +- doc/user/clusters/agent/ci_cd_tunnel.md | 46 +- doc/user/clusters/agent/index.md | 48 +- doc/user/clusters/agent/repository.md | 35 + doc/user/clusters/applications.md | 12 +- doc/user/clusters/environments.md | 2 +- ...d-settings-cluster-management-project-v12_5.png | Bin 37271 -> 0 bytes doc/user/clusters/integrations.md | 3 - doc/user/clusters/management_project.md | 26 +- doc/user/clusters/management_project_template.md | 92 +- .../migrating_from_gma_to_project_template.md | 49 +- doc/user/compliance/compliance_report/index.md | 54 +- doc/user/compliance/license_compliance/index.md | 46 +- .../img/btn_new_issue_for_all_threads.png | Bin 12468 -> 0 bytes .../discussions/img/create-new-issue_v14_3.png | Bin 0 -> 4358 bytes .../discussions/img/new-issue-one-thread_v14_3.png | Bin 0 -> 3752 bytes doc/user/discussions/img/new_issue_for_thread.png | Bin 11820 -> 0 bytes doc/user/discussions/index.md | 51 +- doc/user/gitlab_com/index.md | 18 +- .../img/group_devops_adoption_v14_2.png | Bin 59733 -> 22069 bytes doc/user/group/devops_adoption/index.md | 1 + doc/user/group/epics/epic_boards.md | 4 +- doc/user/group/epics/index.md | 2 +- doc/user/group/import/index.md | 2 +- doc/user/group/index.md | 24 +- doc/user/group/issues_analytics/index.md | 2 +- doc/user/group/iterations/index.md | 12 +- doc/user/group/repositories_analytics/index.md | 6 +- .../roadmap/img/epics_state_dropdown_v12_10.png | Bin 8092 -> 0 bytes .../roadmap/img/epics_state_dropdown_v14_3.png | Bin 0 -> 6994 bytes doc/user/group/roadmap/img/roadmap_view_v13_2.png | Bin 53200 -> 0 bytes doc/user/group/roadmap/img/roadmap_view_v14_3.png | Bin 0 -> 67558 bytes doc/user/group/roadmap/index.md | 38 +- doc/user/group/saml_sso/index.md | 158 +- doc/user/group/saml_sso/scim_setup.md | 38 +- doc/user/group/settings/import_export.md | 6 +- doc/user/group/subgroups/index.md | 2 +- doc/user/group/value_stream_analytics/index.md | 9 +- doc/user/index.md | 6 +- doc/user/infrastructure/clusters/connect/index.md | 126 ++ .../clusters/connect/new_gke_cluster.md | 2 +- .../management_project_applications/certmanager.md | 17 +- .../management_project_applications/cilium.md | 6 - .../elasticstack.md | 5 - .../management_project_applications/falco.md | 6 - .../management_project_applications/fluentd.md | 6 - .../management_project_applications/ingress.md | 5 - .../management_project_applications/prometheus.md | 5 - .../management_project_applications/runner.md | 12 +- .../management_project_applications/sentry.md | 6 - .../management_project_applications/vault.md | 6 - .../iac/img/terraform_list_view_v13_8.png | Bin 0 -> 74877 bytes .../iac/img/terraform_plan_log_v13_0.png | Bin 0 -> 23683 bytes .../iac/img/terraform_plan_widget_v13_2.png | Bin 0 -> 33916 bytes doc/user/infrastructure/iac/index.md | 4 +- doc/user/infrastructure/iac/mr_integration.md | 210 +++ doc/user/infrastructure/iac/terraform_state.md | 446 +++++ .../img/terraform_list_view_v13_8.png | Bin 74877 -> 0 bytes .../img/terraform_plan_log_v13_0.png | Bin 23683 -> 0 bytes .../img/terraform_plan_widget_v13_2.png | Bin 33916 -> 0 bytes doc/user/infrastructure/index.md | 41 +- doc/user/infrastructure/mr_integration.md | 211 +-- doc/user/infrastructure/terraform_state.md | 432 +---- doc/user/instance/clusters/index.md | 4 +- doc/user/packages/conan_repository/index.md | 3 - doc/user/packages/container_registry/index.md | 16 +- doc/user/packages/debian_repository/index.md | 4 +- doc/user/packages/dependency_proxy/index.md | 12 +- doc/user/packages/generic_packages/index.md | 6 +- doc/user/packages/helm_repository/index.md | 42 +- .../packages/terraform_module_registry/index.md | 8 +- doc/user/permissions.md | 140 +- doc/user/profile/account/create_accounts.md | 2 +- doc/user/profile/account/delete_account.md | 4 +- .../profile/account/two_factor_authentication.md | 26 +- doc/user/profile/active_sessions.md | 4 +- .../img/notification_group_settings_v12_8.png | Bin 36922 -> 0 bytes .../img/notification_project_settings_v12_8.png | Bin 39303 -> 0 bytes doc/user/profile/index.md | 16 +- doc/user/profile/notifications.md | 202 ++- doc/user/profile/personal_access_tokens.md | 25 +- doc/user/project/canary_deployments.md | 18 +- doc/user/project/clusters/add_eks_clusters.md | 8 +- doc/user/project/clusters/add_existing_cluster.md | 13 +- doc/user/project/clusters/add_gke_clusters.md | 4 +- doc/user/project/clusters/add_remove_clusters.md | 43 +- doc/user/project/clusters/deploy_to_cluster.md | 8 +- doc/user/project/clusters/index.md | 70 +- doc/user/project/clusters/kubernetes_pod_logs.md | 6 +- .../quick_start_guide.md | 4 +- doc/user/project/clusters/runbooks/index.md | 2 +- doc/user/project/clusters/serverless/index.md | 7 +- doc/user/project/deploy_boards.md | 26 +- doc/user/project/deploy_keys/index.md | 2 +- doc/user/project/deploy_tokens/index.md | 2 +- doc/user/project/description_templates.md | 2 +- doc/user/project/import/bitbucket.md | 18 +- doc/user/project/import/github.md | 88 +- doc/user/project/import/index.md | 2 +- doc/user/project/import/jira.md | 2 +- doc/user/project/index.md | 10 +- doc/user/project/integrations/github.md | 2 +- doc/user/project/integrations/img/slack_setup.png | Bin 86314 -> 65156 bytes .../project/integrations/img/zentao_product_id.png | Bin 0 -> 40486 bytes doc/user/project/integrations/index.md | 4 +- .../integrations/mattermost_slash_commands.md | 4 +- doc/user/project/integrations/overview.md | 7 +- .../project/integrations/services_templates.md | 9 - doc/user/project/integrations/slack.md | 104 +- .../project/integrations/slack_slash_commands.md | 41 +- doc/user/project/integrations/webex_teams.md | 2 +- doc/user/project/integrations/zentao.md | 40 + doc/user/project/issue_board.md | 77 +- doc/user/project/issues/crosslinking_issues.md | 12 +- doc/user/project/issues/index.md | 4 +- doc/user/project/issues/issue_data_and_actions.md | 2 +- doc/user/project/issues/managing_issues.md | 8 +- doc/user/project/issues/sorting_issue_lists.md | 1 + .../project/members/share_project_with_groups.md | 2 +- doc/user/project/merge_requests/approvals/index.md | 4 +- doc/user/project/merge_requests/changes.md | 26 +- .../project/merge_requests/cherry_pick_changes.md | 6 +- doc/user/project/merge_requests/code_quality.md | 11 +- .../project/merge_requests/fail_fast_testing.md | 2 +- .../project/merge_requests/fast_forward_merge.md | 8 +- doc/user/project/merge_requests/getting_started.md | 32 +- doc/user/project/merge_requests/index.md | 21 +- .../merge_requests/load_performance_testing.md | 2 +- doc/user/project/merge_requests/revert_changes.md | 6 +- doc/user/project/merge_requests/reviews/index.md | 45 +- .../project/merge_requests/reviews/suggestions.md | 2 +- .../project/merge_requests/squash_and_merge.md | 6 +- doc/user/project/merge_requests/status_checks.md | 2 +- .../merge_requests/test_coverage_visualization.md | 13 +- doc/user/project/merge_requests/versions.md | 4 +- doc/user/project/pages/index.md | 2 +- doc/user/project/pages/pages_access_control.md | 2 +- doc/user/project/pages/redirects.md | 264 ++- doc/user/project/quick_actions.md | 1 + .../project/releases/img/deploy_freeze_v13_10.png | Bin 15902 -> 0 bytes .../project/releases/img/deploy_freeze_v14_3.png | Bin 0 -> 13557 bytes doc/user/project/releases/index.md | 16 +- doc/user/project/repository/branches/default.md | 12 +- .../project/repository/gpg_signed_commits/index.md | 11 +- doc/user/project/repository/index.md | 6 +- .../project/repository/repository_mirroring.md | 12 +- .../repository/x509_signed_commits/index.md | 356 +++- doc/user/project/service_desk.md | 4 +- doc/user/project/settings/import_export.md | 14 +- doc/user/project/settings/index.md | 100 +- doc/user/project/settings/project_access_tokens.md | 34 +- doc/user/project/time_tracking.md | 2 +- doc/user/project/web_ide/img/open_web_ide.png | Bin 28571 -> 0 bytes doc/user/project/web_ide/index.md | 25 +- doc/user/project/wiki/index.md | 28 +- doc/user/project/working_with_projects.md | 46 + doc/user/search/advanced_search.md | 21 + doc/user/search/index.md | 42 +- doc/user/workspace/img/hardware_settings.png | Bin 76085 -> 29457 bytes doc/user/workspace/index.md | 18 +- 763 files changed, 17312 insertions(+), 8502 deletions(-) create mode 100644 doc/.vale/gitlab/ElementDescriptors.yml delete mode 100644 doc/.vale/gitlab/HeaderGerunds.yml create mode 100644 doc/.vale/gitlab/UnclearAntecedent.yml create mode 100644 doc/administration/cicd.md create mode 100644 doc/administration/geo/replication/updating_the_geo_sites.md create mode 100644 doc/administration/integration/mailgun.md delete mode 100644 doc/administration/operations/unicorn.md create mode 100644 doc/administration/package_information/defaults.md create mode 100644 doc/administration/package_information/deprecated_os.md create mode 100644 doc/administration/package_information/deprecation_policy.md create mode 100644 doc/administration/package_information/index.md create mode 100644 doc/administration/package_information/licensing.md create mode 100644 doc/administration/package_information/omnibus_packages.md create mode 100644 doc/administration/package_information/postgresql_versions.md create mode 100644 doc/administration/package_information/signed_packages.md create mode 100644 doc/administration/packages/img/gitlab-registry-architecture.png delete mode 100644 doc/architecture/blueprints/database/scalability/patterns/img/db_terminology_v14_2.png create mode 100644 doc/ci/jobs/ci_job_token.md delete mode 100644 doc/ci/jobs/img/job_group_v12_10.png create mode 100644 doc/ci/jobs/img/pipeline_delayed_job_v14_2.png create mode 100644 doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png delete mode 100644 doc/ci/jobs/img/pipeline_incremental_rollout.png delete mode 100644 doc/ci/jobs/img/pipelines_grouped.png create mode 100644 doc/ci/pipelines/img/manual_pipeline_v14_2.png delete mode 100644 doc/ci/pipelines/img/pipelines.png delete mode 100644 doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png create mode 100644 doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png create mode 100644 doc/development/database/efficient_in_operator_queries.md create mode 100644 doc/development/documentation/redirects.md create mode 100644 doc/development/documentation/review_apps.md delete mode 100644 doc/development/fe_guide/img/content_editor_highlevel_diagram.png create mode 100644 doc/development/work_items.md create mode 100644 doc/install/aws/eks_clusters_aws.md create mode 100644 doc/install/aws/gitlab_hybrid_on_aws.md create mode 100644 doc/install/aws/gitlab_sre_for_aws.md create mode 100644 doc/install/aws/manual_install_aws.md create mode 100644 doc/integration/mattermost/gitlab-mattermost.msc create mode 100644 doc/integration/mattermost/img/gitlab-mattermost.png create mode 100644 doc/integration/mattermost/index.md create mode 100644 doc/operations/img/error_tracking_setting_v14_3.png create mode 100644 doc/policy/alpha-beta-support.md delete mode 100644 doc/topics/img/gitlab_flow.png delete mode 100644 doc/topics/img/gitlab_flow_ci_mr.png delete mode 100644 doc/topics/img/gitlab_flow_close_issue_mr.png delete mode 100644 doc/topics/img/gitlab_flow_environment_branches.png delete mode 100644 doc/topics/img/gitlab_flow_four_stages.png delete mode 100644 doc/topics/img/gitlab_flow_git_pull.png delete mode 100644 doc/topics/img/gitlab_flow_github_flow.png delete mode 100644 doc/topics/img/gitlab_flow_good_commit.png delete mode 100644 doc/topics/img/gitlab_flow_merge_commits.png delete mode 100644 doc/topics/img/gitlab_flow_merge_request.png delete mode 100644 doc/topics/img/gitlab_flow_messy_flow.png delete mode 100644 doc/topics/img/gitlab_flow_production_branch.png delete mode 100644 doc/topics/img/gitlab_flow_rebase.png delete mode 100644 doc/topics/img/gitlab_flow_release_branches.png create mode 100644 doc/update/deprecations.md create mode 100644 doc/update/package/convert_to_ee.md create mode 100644 doc/update/package/downgrade.md create mode 100644 doc/update/package/index.md create mode 100644 doc/update/plan_your_upgrade.md create mode 100644 doc/update/zero_downtime.md create mode 100644 doc/user/admin_area/settings/git_lfs_rate_limits.md delete mode 100644 doc/user/admin_area/settings/img/import_export_rate_limits_v13_2.png delete mode 100644 doc/user/admin_area/settings/img/user_and_ip_rate_limits.png create mode 100644 doc/user/admin_area/settings/sidekiq_job_limits.md create mode 100644 doc/user/application_security/img/mr_security_scanning_results_v14_3.png create mode 100644 doc/user/application_security/policies/img/container_policy_rule_mode_v14_3.png create mode 100644 doc/user/application_security/policies/img/container_policy_yaml_mode_v14_3.png create mode 100644 doc/user/application_security/policies/img/policies_list_v14_3.png create mode 100644 doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png create mode 100644 doc/user/application_security/policies/img/security_policy_project_v14_3.png delete mode 100644 doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v13_12.png create mode 100644 doc/user/application_security/threat_monitoring/img/threat_monitoring_policy_alert_list_v14_3.png delete mode 100644 doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png delete mode 100644 doc/user/discussions/img/btn_new_issue_for_all_threads.png create mode 100644 doc/user/discussions/img/create-new-issue_v14_3.png create mode 100644 doc/user/discussions/img/new-issue-one-thread_v14_3.png delete mode 100644 doc/user/discussions/img/new_issue_for_thread.png delete mode 100644 doc/user/group/roadmap/img/epics_state_dropdown_v12_10.png create mode 100644 doc/user/group/roadmap/img/epics_state_dropdown_v14_3.png delete mode 100644 doc/user/group/roadmap/img/roadmap_view_v13_2.png create mode 100644 doc/user/group/roadmap/img/roadmap_view_v14_3.png create mode 100644 doc/user/infrastructure/clusters/connect/index.md create mode 100644 doc/user/infrastructure/iac/img/terraform_list_view_v13_8.png create mode 100644 doc/user/infrastructure/iac/img/terraform_plan_log_v13_0.png create mode 100644 doc/user/infrastructure/iac/img/terraform_plan_widget_v13_2.png create mode 100644 doc/user/infrastructure/iac/mr_integration.md create mode 100644 doc/user/infrastructure/iac/terraform_state.md delete mode 100644 doc/user/infrastructure/img/terraform_list_view_v13_8.png delete mode 100644 doc/user/infrastructure/img/terraform_plan_log_v13_0.png delete mode 100644 doc/user/infrastructure/img/terraform_plan_widget_v13_2.png delete mode 100644 doc/user/profile/img/notification_group_settings_v12_8.png delete mode 100644 doc/user/profile/img/notification_project_settings_v12_8.png create mode 100644 doc/user/project/integrations/img/zentao_product_id.png delete mode 100644 doc/user/project/integrations/services_templates.md create mode 100644 doc/user/project/integrations/zentao.md delete mode 100644 doc/user/project/releases/img/deploy_freeze_v13_10.png create mode 100644 doc/user/project/releases/img/deploy_freeze_v14_3.png delete mode 100644 doc/user/project/web_ide/img/open_web_ide.png (limited to 'doc') diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml index 2d4d0c6909f..122cac6f8a1 100644 --- a/doc/.vale/gitlab/Acronyms.yml +++ b/doc/.vale/gitlab/Acronyms.yml @@ -107,6 +107,7 @@ exceptions: - NTP - ONLY - OSS + - OTP - OWASP - PAT - PCI-DSS diff --git a/doc/.vale/gitlab/BadgeCapitalization.yml b/doc/.vale/gitlab/BadgeCapitalization.yml index 89d6f509d63..33425693d53 100644 --- a/doc/.vale/gitlab/BadgeCapitalization.yml +++ b/doc/.vale/gitlab/BadgeCapitalization.yml @@ -10,4 +10,5 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html level: error scope: raw raw: - - '\*\*\(([Ff]ree|[Pp]remium|[Uu]ltimate)( [Ss](elf|ass))?\)\*\*' + - '(?!\*\*\((FREE|PREMIUM|ULTIMATE)( (SELF|SAAS))?\)\*\*)' + - '(?i)\*\*\((free|premium|ultimate)( (self|saas))?\)\*\*' diff --git a/doc/.vale/gitlab/CurlStringsQuoted.yml b/doc/.vale/gitlab/CurlStringsQuoted.yml index c0bc8c18c93..a59fe64d990 100644 --- a/doc/.vale/gitlab/CurlStringsQuoted.yml +++ b/doc/.vale/gitlab/CurlStringsQuoted.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguid level: error scope: code raw: - - 'curl.*[^"=]https?://.*' + - 'curl [^"]+://.*' diff --git a/doc/.vale/gitlab/ElementDescriptors.yml b/doc/.vale/gitlab/ElementDescriptors.yml new file mode 100644 index 00000000000..254da16d00c --- /dev/null +++ b/doc/.vale/gitlab/ElementDescriptors.yml @@ -0,0 +1,14 @@ +--- +# Suggestion: gitlab.ElementDescriptors +# +# Suggests the correct way to describe elements in a form. +# +# For a list of all options, see https://errata-ai.github.io/vale/styles/ +extends: substitution +message: 'When describing elements, %s "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language +level: suggestion +ignorecase: true +swap: + button: 'if possible, rewrite to not use' + area: 'use "section" instead of' diff --git a/doc/.vale/gitlab/HeaderGerunds.yml b/doc/.vale/gitlab/HeaderGerunds.yml deleted file mode 100644 index 9e5fa19f867..00000000000 --- a/doc/.vale/gitlab/HeaderGerunds.yml +++ /dev/null @@ -1,14 +0,0 @@ ---- -# Suggestion: gitlab.HeaderGerunds -# -# Checks for headers that start with gerunds (ing words). -# Related to: https://docs.gitlab.com/ee/development/documentation/structure.html -# -# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles -extends: substitution -message: 'Can this header start with an imperative verb, instead of a gerund (ing word)?' -link: https://docs.gitlab.com/ee/development/documentation/styleguide/#heading-titles -level: suggestion -scope: heading -swap: - - '^\w*ing.*': 'Troubleshooting' diff --git a/doc/.vale/gitlab/InternalLinkExtension.yml b/doc/.vale/gitlab/InternalLinkExtension.yml index 0b1baaf667c..5783c4347a9 100644 --- a/doc/.vale/gitlab/InternalLinkExtension.yml +++ b/doc/.vale/gitlab/InternalLinkExtension.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html level: error scope: raw raw: - - '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*?\)' + - '\[.+\]\([\w\/\.-]+\.html[^)]*\)' diff --git a/doc/.vale/gitlab/InternalLinkFormat.yml b/doc/.vale/gitlab/InternalLinkFormat.yml index 51d5198a0ce..b9ee83b7f5c 100644 --- a/doc/.vale/gitlab/InternalLinkFormat.yml +++ b/doc/.vale/gitlab/InternalLinkFormat.yml @@ -10,4 +10,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html level: error scope: raw raw: - - '\[.+\]\(\.\/.+?\)' + - '\[.+\]\(\.\/.*?\)' diff --git a/doc/.vale/gitlab/OutdatedVersions.yml b/doc/.vale/gitlab/OutdatedVersions.yml index 05323726838..15ae0a5814a 100644 --- a/doc/.vale/gitlab/OutdatedVersions.yml +++ b/doc/.vale/gitlab/OutdatedVersions.yml @@ -19,3 +19,5 @@ tokens: - "GitLab (v)?7." - "GitLab (v)?8." - "GitLab (v)?9." + - "GitLab (v)?10." + - "GitLab (v)?11." diff --git a/doc/.vale/gitlab/ReadingLevel.yml b/doc/.vale/gitlab/ReadingLevel.yml index 0099e70ec8f..2e78c3ef36c 100644 --- a/doc/.vale/gitlab/ReadingLevel.yml +++ b/doc/.vale/gitlab/ReadingLevel.yml @@ -6,6 +6,7 @@ # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: readability message: "Grade level (%s) is high. To lower the score, use shorter sentences and words." +link: https://docs.gitlab.com/ee/development/documentation/testing.html#vale-readability-score level: suggestion grade: 8 metrics: diff --git a/doc/.vale/gitlab/SubstitutionSuggestions.yml b/doc/.vale/gitlab/SubstitutionSuggestions.yml index bc9a6e3c70d..e7c0cc04244 100644 --- a/doc/.vale/gitlab/SubstitutionSuggestions.yml +++ b/doc/.vale/gitlab/SubstitutionSuggestions.yml @@ -14,7 +14,9 @@ swap: active user: '"billable user"' active users: '"billable users"' docs: '"documentation"' + e-mail: '"email"' GFM: '"GitLab Flavored Markdown"' + it is recommended: '"we recommend"' OAuth2: '"OAuth 2.0"' once that: '"after that"' once the: '"after the"' diff --git a/doc/.vale/gitlab/UnclearAntecedent.yml b/doc/.vale/gitlab/UnclearAntecedent.yml new file mode 100644 index 00000000000..863bbd4e109 --- /dev/null +++ b/doc/.vale/gitlab/UnclearAntecedent.yml @@ -0,0 +1,22 @@ +--- +# Suggestion: gitlab.UnclearAntecedent +# +# Checks for words that need a noun for clarity. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: "'%s' is not precise. Try rewriting with a specific subject and verb." +link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#this-these-that-those +level: suggestion +ignorecase: false +tokens: + - 'That is' + - 'That was' + - 'These are' + - 'These were' + - 'There are' + - 'There were' + - 'This is' + - 'This was' + - 'Those are' + - 'Those were' diff --git a/doc/.vale/gitlab/VersionText.yml b/doc/.vale/gitlab/VersionText.yml index e66a62497b1..fbdda17e2a0 100644 --- a/doc/.vale/gitlab/VersionText.yml +++ b/doc/.vale/gitlab/VersionText.yml @@ -9,9 +9,9 @@ # - `> Introduced` (version text without a link) # - `> [Introduced` (version text with a link) # -# Because it excludes `-`, it doesn't look for multi-line version text, for which content -# immediately on the next line is ok. However, this will often highlight where multi-line version -# text is attempted without `-` characters. +# Because it excludes the prefix `> - `, it doesn't look for multi-line version text, for which +# content immediately on the next line is ok. However, this will often highlight where multi-line +# version text is attempted without `-` characters. # # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles extends: existence @@ -20,4 +20,4 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html level: error scope: raw raw: - - '> (- ){0}\[?Introduced.+\n[^\n`]' + - '> \[?Introduced.+\n[^\n]' diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index 43ff584b550..d397a436ff9 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -90,6 +90,7 @@ callstack callstacks Camo canonicalized +captcha CentOS Certbot changeset @@ -160,7 +161,12 @@ deprovisions dequarantine dequarantined dequarantining +deserialization +deserialize +deserializers +deserializes DevOps +Dhall disambiguates discoverability dismissable @@ -209,6 +215,7 @@ fixup Flawfinder Flowdock Fluentd +Flycheck Forgerock formatters Fugit @@ -469,6 +476,7 @@ queryable Quicktime Rackspace Raspbian +rbenv rbtrace Rdoc reachability @@ -815,8 +823,10 @@ Worldline Xcode Xeon YouTrack +ytt Yubico Zeitwerk Zendesk +ZenTao zsh Zstandard diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index 48bd812c7f2..3ff5fb2635d 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -39,7 +39,7 @@ There are two kinds of events logged: ### Impersonation data -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/536) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/536) in GitLab 13.0. When a user is being [impersonated](../user/admin_area/index.md#user-impersonation), their actions are logged as audit events as usual, with two additional details: @@ -48,7 +48,7 @@ When a user is being [impersonated](../user/admin_area/index.md#user-impersonati ![audit events](img/impersonated_audit_events_v13_8.png) -### Group events **(PREMIUM)** +### Group events A user with: @@ -86,7 +86,7 @@ From there, you can see the following actions: Group events can also be accessed via the [Group Audit Events API](../api/audit_events.md#group-audit-events) -### Project events **(PREMIUM)** +### Project events A user with a Maintainer role (or above) can retrieve project audit events of all users. A user with a Developer role is limited to project audit events based on their individual actions. @@ -126,6 +126,10 @@ From there, you can see the following actions: - User password required for approvals was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2) - Permission to modify merge requests approval rules in merge requests was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2) - New approvals requirement when new commits are added to an MR was updated ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336211) in GitLab 14.2) +- When [strategies for feature flags](../operations/feature_flags.md#feature-flag-strategies) are changed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68408) in GitLab 14.3) +- Allowing force push to protected branch changed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3) +- Code owner approval requirement on merge requests targeting protected branch changed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3) +- Users and groups allowed to merge and push to protected branch added or removed ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338873) in GitLab 14.3) Project events can also be accessed via the [Project Audit Events API](../api/audit_events.md#project-audit-events). @@ -133,7 +137,7 @@ Project event queries are limited to a maximum of 30 days. ### Instance events **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2336) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2336) in GitLab 9.3. Server-wide audit events introduce the ability to observe user actions across the entire instance of your GitLab server, making it easy to understand who @@ -143,7 +147,7 @@ Instance events do not include group or project audit events. To view the server-wide audit events: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Audit Events**. The following user actions are recorded: @@ -203,6 +207,8 @@ to request it, or you can [add it yourself](../development/audit_event_guide/). #### Repository push +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/337993) in GitLab 14.3. + 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 events very busy, and the disk space consumed by the `audit_events` PostgreSQL table may increase considerably. It's disabled by default @@ -240,8 +246,8 @@ The search filters you can see depends on which audit level you are at. ## Export to CSV **(PREMIUM SELF)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1449) in GitLab 13.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/285441) in GitLab 13.7. Export to CSV allows customers to export the current filter view of your audit events as a CSV file, which stores tabular data in plain text. The data provides a comprehensive view with respect to @@ -249,7 +255,7 @@ audit events. To export the Audit Events to CSV: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Audit Events**. 1. Select the available search [filters](#search). 1. Select **Export as CSV**. diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index 5f31ed709f2..5498ea9d4be 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -57,7 +57,7 @@ helpful: To create an Auditor user: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Users**. 1. Create a new user or edit an existing one, and in the **Access** section select Auditor. diff --git a/doc/administration/auth/atlassian.md b/doc/administration/auth/atlassian.md index 868482148e5..b58bbfa8eac 100644 --- a/doc/administration/auth/atlassian.md +++ b/doc/administration/auth/atlassian.md @@ -16,7 +16,7 @@ To enable the Atlassian OmniAuth provider for passwordless authentication you mu 1. Click **Create a new app**. 1. Choose an App Name, such as 'GitLab', and click **Create**. 1. Note the `Client ID` and `Secret` for the [GitLab configuration](#gitlab-configuration) steps. -1. In the left sidebar under **APIS AND FEATURES**, click **OAuth 2.0 (3LO)**. +1. On the left sidebar under **APIS AND FEATURES**, click **OAuth 2.0 (3LO)**. 1. Enter the GitLab callback URL using the format `https://gitlab.example.com/users/auth/atlassian_oauth2/callback` and click **Save changes**. 1. Click **+ Add** in the left sidebar under **APIS AND FEATURES**. 1. Click **Add** for **Jira platform REST API** and then **Configure**. diff --git a/doc/administration/auth/ldap/google_secure_ldap.md b/doc/administration/auth/ldap/google_secure_ldap.md index 55ccf6653a3..137f35986ac 100644 --- a/doc/administration/auth/ldap/google_secure_ldap.md +++ b/doc/administration/auth/ldap/google_secure_ldap.md @@ -87,6 +87,7 @@ values obtained during the LDAP client configuration earlier: password: 'd6V5H8nhMUW9AuDP25abXeLd' encryption: 'simple_tls' verify_certificates: true + retry_empty_result_with_codes: [80] tls_options: cert: | @@ -159,6 +160,7 @@ values obtained during the LDAP client configuration earlier: password: 'd6V5H8nhMUW9AuDP25abXeLd' encryption: 'simple_tls' verify_certificates: true + retry_empty_result_with_codes: [80] tls_options: cert: | @@ -213,7 +215,7 @@ values obtained during the LDAP client configuration earlier: ## Using encrypted credentials You can optionally store the `bind_dn` and `password` in a separate encrypted configuration file using the -[same steps as the regular LDAP integration](index.md#using-encrypted-credentials). +[same steps as the regular LDAP integration](index.md#use-encrypted-credentials). diff --git a/doc/administration/clusters/kas.md b/doc/administration/clusters/kas.md index 8e5c162001e..6afaff73396 100644 --- a/doc/administration/clusters/kas.md +++ b/doc/administration/clusters/kas.md @@ -129,3 +129,25 @@ or the path to `config.yaml` inside the project is not valid. To fix this, ensure that the paths to the configuration repository and to the `config.yaml` file are correct. + +### KAS logs - `dial tcp :443: connect: connection refused` + +If you are running a self-managed GitLab instance and: + +- The instance isn't running behind an SSL-terminating proxy. +- The instance doesn't have HTTPS configured on the GitLab instance itself. +- The instance's hostname resolves locally to its internal IP address. + +You may see the following error when the KAS tries to connect to the GitLab API: + +```json +{"level":"error","time":"2021-08-16T14:56:47.289Z","msg":"GetAgentInfo()","correlation_id":"01FD7QE35RXXXX8R47WZFBAXTN","grpc_service":"gitlab.agent.reverse_tunnel.rpc.ReverseTunnel","grpc_method":"Connect","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": dial tcp 172.17.0.4:443: connect: connection refused"} +``` + +To fix this for [Omnibus](https://docs.gitlab.com/omnibus/) package installations, +set the following parameter in `/etc/gitlab/gitlab.rb` +(replacing `gitlab.example.com` with your GitLab instance's hostname): + +```ruby +gitlab_kas['gitlab_address'] = 'http://gitlab.example.com' +``` diff --git a/doc/administration/compliance.md b/doc/administration/compliance.md index e356ef0366b..1761af1ffa1 100644 --- a/doc/administration/compliance.md +++ b/doc/administration/compliance.md @@ -31,3 +31,4 @@ relevant compliance standards. |**[Compliance frameworks](../user/project/settings/index.md#compliance-frameworks)**
Create a custom compliance framework at the group level to describe the type of compliance requirements any child project needs to follow. | Premium+ | **{check-circle}** Yes | Group | |**[Compliance pipelines](../user/project/settings/index.md#compliance-pipeline-configuration)**
Define a pipeline configuration to run for any projects with a given compliance framework. | Ultimate | **{check-circle}** Yes | Group | |**[Compliance report](../user/compliance/compliance_report/index.md)**
Quickly get visibility into the compliance posture of your organization. | Ultimate | **{check-circle}** Yes | Group | +|**[External Status Checks](../user/project/merge_requests/status_checks.md)**
Interface with third party systems you already use during development to ensure you remain compliant. | Ultimate | **{check-circle}** Yes | Project | diff --git a/doc/administration/configure.md b/doc/administration/configure.md index 73fbf527fe1..d3e37b4a0ee 100644 --- a/doc/administration/configure.md +++ b/doc/administration/configure.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Configure your GitLab installation +# Configure your GitLab installation **(FREE SELF)** Customize and configure your self-managed GitLab installation. diff --git a/doc/administration/consul.md b/doc/administration/consul.md index c88047c4c61..72b3487a549 100644 --- a/doc/administration/consul.md +++ b/doc/administration/consul.md @@ -21,7 +21,7 @@ Before configuring Consul: 1. Review the [reference architecture](reference_architectures/index.md#available-reference-architectures) documentation to determine the number of Consul server nodes you should have. -1. If necessary, ensure the [appropriate ports are open](https://docs.gitlab.com/omnibus/package-information/defaults.html#ports) in your firewall. +1. If necessary, ensure the [appropriate ports are open](package_information/defaults.md#ports) in your firewall. ## Configure the Consul nodes diff --git a/doc/administration/database_load_balancing.md b/doc/administration/database_load_balancing.md index 7d17b22a4d7..45f27a8a8f2 100644 --- a/doc/administration/database_load_balancing.md +++ b/doc/administration/database_load_balancing.md @@ -117,9 +117,9 @@ For Sidekiq, we can define [data consistency](../development/sidekiq_style_guide.md#job-data-consistency-strategies) requirements for a specific job. -## Service Discovery +## Service Discovery **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5883) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5883) in GitLab 11.0. Service discovery allows GitLab to automatically retrieve a list of secondary databases to use, instead of having to manually specify these in the @@ -237,9 +237,9 @@ For example: {"severity":"INFO","time":"2019-09-02T12:12:01.728Z","correlation_id":"abcdefg","event":"host_online","message":"Host came back online","db_host":"111.222.333.444","db_port":null,"tag":"rails.database_load_balancing","environment":"production","hostname":"web-example-1","fqdn":"gitlab.example.com","path":null,"params":null} ``` -## Handling Stale Reads +## Handling Stale Reads **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3526) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3526) in GitLab 10.3. To prevent reading from an outdated secondary the load balancer checks if it is in sync with the primary. If the data is determined to be recent enough the diff --git a/doc/administration/encrypted_configuration.md b/doc/administration/encrypted_configuration.md index 8afe30d20ab..9224def4a5a 100644 --- a/doc/administration/encrypted_configuration.md +++ b/doc/administration/encrypted_configuration.md @@ -11,8 +11,8 @@ type: reference GitLab can read settings for certain features from encrypted settings files. The supported features are: -- [LDAP `user_bn` and `password`](auth/ldap/index.md#using-encrypted-credentials) -- [SMTP `user_name` and `password`](raketasks/smtp.md#secrets) +- [LDAP `user_bn` and `password`](auth/ldap/index.md#use-encrypted-credentials). +- [SMTP `user_name` and `password`](raketasks/smtp.md#secrets). In order to enable the encrypted configuration settings, a new base key needs to be generated for `encrypted_settings_key_base`. The secret can be generated in the following ways: @@ -35,4 +35,4 @@ The new secret can be generated by running: bundle exec rake gitlab:env:info RAILS_ENV=production GITLAB_GENERATE_ENCRYPTED_SETTINGS_KEY_BASE=true ``` -This prints general information on the GitLab instance, but also causes the key to be generated in `/config/secrets.yml` +This prints general information on the GitLab instance, but also causes the key to be generated in `/config/secrets.yml`. diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index 65e0ffd4366..caa806c92c8 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -60,7 +60,7 @@ Feature.enable('geo_repository_verification') On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Expand **Verification information** tab for that node to view automatic checksumming status for repositories and wikis. Successes are shown in green, pending work @@ -70,7 +70,7 @@ On the **primary** node: On the **secondary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Expand **Verification information** tab for that node to view automatic checksumming status for repositories and wikis. Successes are shown in green, pending work @@ -89,7 +89,7 @@ in sync. ## Repository re-verification -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8550) in GitLab Enterprise Edition 11.6. Available in [GitLab Premium](https://about.gitlab.com/pricing/). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8550) in GitLab 11.6. Due to bugs or transient infrastructure failures, it is possible for Git repositories to change unexpectedly without being marked for verification. @@ -100,7 +100,7 @@ increase load and vice versa. On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Edit** for the **primary** node to customize the minimum re-verification interval: @@ -151,7 +151,7 @@ sudo gitlab-rake geo:verification:wiki:reset If the **primary** and **secondary** nodes have a checksum verification mismatch, the cause may not be apparent. To find the cause of a checksum mismatch: 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Projects**. 1. Find the project that you want to check the checksum differences and select its name. diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index 8b55bebb42b..a7a64701cbd 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -111,7 +111,7 @@ ensure these processes are close to 100% as possible during active use. On the **secondary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. Replicated objects (shown in green) should be close to 100%, and there should be no failures (shown in red). If a large proportion of @@ -139,7 +139,7 @@ This [content was moved to another location](background_verification.md). On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Messages**. 1. Add a message notifying users on the maintenance window. You can check under **Geo > Nodes** to estimate how long it @@ -152,7 +152,7 @@ To ensure that all data is replicated to a secondary site, updates (write reques be disabled on the **primary** site: 1. Enable [maintenance mode](../../maintenance_mode/index.md) on the **primary** node. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Cron**. 1. Select `Disable All` to disable non-Geo periodic background jobs. @@ -165,7 +165,7 @@ be disabled on the **primary** site: 1. If you are manually replicating any data not managed by Geo, trigger the final replication process now. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -180,7 +180,7 @@ be disabled on the **primary** site: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md index 27990748071..4255fba83f6 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md @@ -65,7 +65,7 @@ promote a Geo replica and perform a failover. On the **secondary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes** to see 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 @@ -130,7 +130,7 @@ follow these steps to avoid unnecessary data loss: connection. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dhasboard, select **Cron**. 1. Select `Disable All` to disable any non-Geo periodic background jobs. @@ -148,7 +148,7 @@ follow these steps to avoid unnecessary data loss: [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), trigger the final replication process now. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -163,7 +163,7 @@ follow these steps to avoid unnecessary data loss: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md index 9d5e65cd194..18923da1056 100644 --- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md +++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md @@ -115,7 +115,7 @@ follow these steps to avoid unnecessary data loss: connection. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dhasboard, select **Cron**. 1. Select `Disable All` to disable any non-Geo periodic background jobs. @@ -133,7 +133,7 @@ follow these steps to avoid unnecessary data loss: [data not managed by Geo](../../replication/datatypes.md#limitations-on-replicationverification), trigger the final replication process now. 1. On the **primary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all queues except those with `geo` in the name to drop to 0. @@ -148,7 +148,7 @@ follow these steps to avoid unnecessary data loss: - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** node: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. On the Sidekiq dashboard, select **Queues**, and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md index 7175d41abd8..48091967189 100644 --- a/doc/administration/geo/index.md +++ b/doc/administration/geo/index.md @@ -7,12 +7,6 @@ type: howto # Geo **(PREMIUM SELF)** -> - Introduced in GitLab Enterprise Edition 8.9. -> - Using Geo in combination with -> [multi-node architectures](../reference_architectures/index.md) -> is considered **Generally Available** (GA) in -> [GitLab Premium](https://about.gitlab.com/pricing/) 10.4. - Geo is the solution for widely distributed development teams and for providing a warm-standby as part of a disaster recovery strategy. ## Overview @@ -144,7 +138,7 @@ The following table lists basic ports that must be open between the **primary** | 22 | 22 | TCP | | 5432 | | PostgreSQL | -See the full list of ports used by GitLab in [Package defaults](https://docs.gitlab.com/omnibus/package-information/defaults.html) +See the full list of ports used by GitLab in [Package defaults](../package_information/defaults.md) NOTE: [Web terminal](../../ci/environments/index.md#web-terminals) support requires your load balancer to correctly handle WebSocket connections. @@ -214,11 +208,11 @@ For information on configuring Geo, see [Geo configuration](replication/configur ### Updating Geo -For information on how to update your Geo site(s) to the latest GitLab version, see [Updating the Geo sites](replication/updating_the_geo_nodes.md). +For information on how to update your Geo site(s) to the latest GitLab version, see [Updating the Geo sites](replication/updating_the_geo_sites.md). ### Pausing and resuming replication -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35913) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35913) in GitLab 13.2. WARNING: In GitLab 13.2 and 13.3, promoting a secondary site to a primary while the @@ -230,7 +224,7 @@ WARNING: Pausing and resuming of replication is currently only supported for Geo installations using an Omnibus GitLab-managed database. External databases are currently not supported. -In some circumstances, like during [upgrades](replication/updating_the_geo_nodes.md) or a [planned failover](disaster_recovery/planned_failover.md), it is desirable to pause replication between the primary and secondary. +In some circumstances, like during [upgrades](replication/updating_the_geo_sites.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 a node in the secondary site where the `postgresql` service is enabled. diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 5b22741f578..88f1ad5b490 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -199,7 +199,7 @@ keys must be manually replicated to the **secondary** site. gitlab-ctl reconfigure ``` -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Sites**. 1. Select **New site**. ![Add secondary site](img/adding_a_secondary_v13_3.png) @@ -257,7 +257,7 @@ method to be enabled. This is enabled by default, but if converting an existing On the **primary** site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Ensure "Enabled Git access protocols" is set to either "Both SSH and HTTP(S)" or "Only HTTP(S)". @@ -267,7 +267,7 @@ On the **primary** site: You can sign in to the **secondary** site with the same credentials you used with the **primary** site. After you sign in: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Sites**. 1. Verify that it's correctly identified as a **secondary** Geo site, and that Geo is enabled. @@ -338,7 +338,7 @@ when: ## Upgrading Geo -See the [updating the Geo sites document](updating_the_geo_nodes.md). +See the [updating the Geo sites document](updating_the_geo_sites.md). ## Troubleshooting diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index a696e5410e5..3f38436429a 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -47,12 +47,16 @@ verification methods: | Blobs | Container registry _(object storage)_ | Geo with API/Managed/Docker API (*2*) | _Not implemented_ | | Blobs | Package registry _(file system)_ | Geo with API | SHA256 checksum | | Blobs | Package registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Infrastructure registry _(file system)_ | Geo with API | SHA256 checksum | +| Blobs | Infrastructure registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | Versioned Terraform State _(file system)_ | Geo with API | SHA256 checksum | | Blobs | Versioned Terraform State _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | External Merge Request Diffs _(file system)_ | Geo with API | _Not implemented_ | | Blobs | External Merge Request Diffs _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | Pipeline artifacts _(file system)_ | Geo with API | SHA256 checksum | | Blobs | Pipeline artifacts _(object storage)_ | Geo with API/Managed (*2*) | SHA256 checksum | +| Blobs | Pages _(file system)_ | Geo with API | _Not implemented_ | +| Blobs | Pages _(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 sites. - (*2*): Object storage replication can be performed by Geo or by your object storage provider/appliance @@ -189,21 +193,15 @@ successfully, you must replicate their data using some other means. |[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 sites and comparing the output between them. | |[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 | | -|[Infrastructure Registry for Terraform Module](../../../user/packages/terraform_module_registry/index.md) | **Yes** (14.0) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (14.0) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | +|[Infrastructure Registry](../../../user/packages/infrastructure_registry/index.md) | **Yes** (14.0) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (14.0) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | No | Designs also require replication of LFS objects and Uploads. | -|[Package Registry for npm](../../../user/packages/npm_registry/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for Maven](../../../user/packages/maven_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for Conan](../../../user/packages/conan_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for NuGet](../../../user/packages/nuget_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for PyPI](../../../user/packages/pypi_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for Composer](../../../user/packages/composer_repository/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | -|[Package Registry for generic packages](../../../user/packages/generic_packages/index.md) | **Yes** (13.5) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | +|[Package Registry](../../../user/packages/package_registry/index.md) | **Yes** (13.2) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.10) | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Versioned Terraform State](../../terraform_state.md) | **Yes** (13.5) | [**Yes**](#limitation-of-verification-for-files-in-object-storage) (13.12) | Via Object Storage provider if supported. Native Geo support (Beta). | Replication is behind the feature flag `geo_terraform_state_version_replication`, enabled by default. Verification was behind the feature flag `geo_terraform_state_version_verification`, which was removed in 14.0| |[External merge request diffs](../../merge_request_diffs.md) | **Yes** (13.5) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Replication is behind the feature flag `geo_merge_request_diff_replication`, enabled by default. Verification is under development, behind the feature flag `geo_merge_request_diff_verification`, introduced in 14.0.| |[Versioned snippets](../../../user/snippets.md#versioned-snippets) | [**Yes** (13.7)](https://gitlab.com/groups/gitlab-org/-/epics/2809) | [**Yes** (14.2)](https://gitlab.com/groups/gitlab-org/-/epics/2810) | No | Verification was implemented behind the feature flag `geo_snippet_repository_verification` in 13.11, and the feature flag was removed in 14.2. | |[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 | Via Object Storage provider if supported. **No** native Geo support (Beta). | | +|[GitLab Pages](../../pages/index.md) | [**Yes** (14.3)](https://gitlab.com/groups/gitlab-org/-/epics/589) | No | Via Object Storage provider if supported. Native Geo support (Beta). | Behind feature flag `geo_pages_deployment_replication`, enabled by default. | |[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). Replication of this cache is not needed for Disaster Recovery purposes because it can be recreated from external sources. | |[Vulnerability Export](../../../user/application_security/vulnerability_report/#export-vulnerability-details) | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/3111) | No | | 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 485a5ee1950..ae2597ad649 100644 --- a/doc/administration/geo/replication/disable_geo.md +++ b/doc/administration/geo/replication/disable_geo.md @@ -36,7 +36,7 @@ to do that. To remove the **primary** site: 1. [Remove all secondary Geo sites](remove_geo_site.md) -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Remove** for the **primary** node. 1. Confirm by selecting **Remove** when the prompt appears. diff --git a/doc/administration/geo/replication/docker_registry.md b/doc/administration/geo/replication/docker_registry.md index 5cc4f66017b..4004ef3c17f 100644 --- a/doc/administration/geo/replication/docker_registry.md +++ b/doc/administration/geo/replication/docker_registry.md @@ -130,7 +130,7 @@ For each application and Sidekiq node on the **secondary** site: To verify Container Registry replication is working, on the **secondary** site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. The initial replication, or "backfill", is probably still in progress. diff --git a/doc/administration/geo/replication/faq.md b/doc/administration/geo/replication/faq.md index 28030dccb3b..70a6e506c28 100644 --- a/doc/administration/geo/replication/faq.md +++ b/doc/administration/geo/replication/faq.md @@ -52,7 +52,7 @@ query. ## Can I `git push` to a **secondary** site? -Yes! Pushing directly to a **secondary** site (for both HTTP and SSH, including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in [GitLab Premium](https://about.gitlab.com/pricing/#self-managed) 11.3. +Yes! Pushing directly to a **secondary** site (for both HTTP and SSH, including Git LFS) was [introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in GitLab 11.3. ## How long does it take to have a commit replicated to a **secondary** site? diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md index d3931c0ba80..1f799b30125 100644 --- a/doc/administration/geo/replication/object_storage.md +++ b/doc/administration/geo/replication/object_storage.md @@ -9,15 +9,19 @@ type: howto Geo can be used in combination with Object Storage (AWS S3, or other compatible object storage). -The storage method for files is recorded in the database, and the database is replicated -from the **primary** Geo site to the **secondary** Geo site, so the **secondary** Geo site -must match the storage method of the **primary** Geo site. -Therefore, if the **primary** Geo site uses object storage, the **secondary** Geo site must use it too. - Currently, **secondary** sites can use either: - The same storage bucket as the **primary** site. - A replicated storage bucket. +- Local storage, if the primary uses local storage. + +The storage method (local or object storage) for files is recorded in the database, and the database +is replicated from the **primary** Geo site to the **secondary** Geo site. + +When accessing an uploaded object, we get its storage method (local or object storage) from the +database, so the **secondary** Geo site must match the storage method of the **primary** Geo site. + +Therefore, if the **primary** Geo site uses object storage, the **secondary** Geo site must use it too. To have: @@ -38,7 +42,7 @@ whether they are stored on the local file system or in object storage. To enable GitLab replication: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Edit** on the **secondary** site. 1. In the **Synchronization Settings** section, find the **Allow this secondary node to replicate content on Object Storage** diff --git a/doc/administration/geo/replication/remove_geo_site.md b/doc/administration/geo/replication/remove_geo_site.md index 274eb28dbc9..b69dfe2e723 100644 --- a/doc/administration/geo/replication/remove_geo_site.md +++ b/doc/administration/geo/replication/remove_geo_site.md @@ -9,7 +9,7 @@ type: howto **Secondary** sites can be removed from the Geo cluster using the Geo administration page of the **primary** site. To remove a **secondary** site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select the **Remove** button for the **secondary** site you want to remove. 1. Confirm by selecting **Remove** when the prompt appears. diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index e072696b37c..7b82d742bd5 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -27,7 +27,7 @@ Before attempting more advanced troubleshooting: On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. We perform the following health checks on each **secondary** node @@ -610,7 +610,7 @@ to start again from scratch, there are a few steps that can help you: ### Design repository failures on mirrored projects and project imports -On the top bar, under **Menu >** **{admin}** **Admin > Geo > Nodes**, +On the top bar, under **Menu > Admin > Geo > Nodes**, if the Design repositories progress bar shows `Synced` and `Failed` greater than 100%, and negative `Queued`, then the instance is likely affected by @@ -836,7 +836,7 @@ node's URL matches its external URL. On the **primary** node: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Find the affected **secondary** site and select **Edit**. 1. Ensure the **URL** field matches the value found in `/etc/gitlab/gitlab.rb` diff --git a/doc/administration/geo/replication/tuning.md b/doc/administration/geo/replication/tuning.md index 9807f3e6444..bcff6181296 100644 --- a/doc/administration/geo/replication/tuning.md +++ b/doc/administration/geo/replication/tuning.md @@ -14,7 +14,7 @@ in the background. On the **primary** site: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Geo > Nodes**. 1. Select **Edit** of the secondary node you want to tune. 1. Under **Tuning settings**, there are several variables that can be tuned to diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md index 03570048071..f07c8d547a4 100644 --- a/doc/administration/geo/replication/updating_the_geo_nodes.md +++ b/doc/administration/geo/replication/updating_the_geo_nodes.md @@ -1,52 +1,9 @@ --- -stage: Enablement -group: Geo -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: howto +redirect_to: 'updating_the_geo_sites.md' +remove_date: '2021-11-23' --- -# Updating the Geo nodes **(PREMIUM SELF)** +This file was moved to [another location](updating_the_geo_sites.md). -WARNING: -Read these sections carefully before updating your Geo nodes. Not following -version-specific update steps may result in unexpected downtime. If you have -any specific questions, [contact Support](https://about.gitlab.com/support/#contact-support). - -Updating Geo nodes involves performing: - -1. [Version-specific update steps](version_specific_updates.md), depending on the - version being updated to or from. -1. [General update steps](#general-update-steps), for all updates. - -## General update steps - -NOTE: -These general update steps are not intended for [high-availability deployments](https://docs.gitlab.com/omnibus/update/README.html#multi-node--ha-deployment), and will cause downtime. If you want to avoid downtime, consider using [zero downtime updates](https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates). - -To update the Geo nodes when a new GitLab version is released, update **primary** -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/#update-using-the-official-repositories). -1. Log into each **secondary** node. -1. [Update GitLab on each **secondary** node using Omnibus](https://docs.gitlab.com/omnibus/update/#update-using-the-official-repositories). -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. - -### Check status after updating - -Now that the update process is complete, you may want to check whether -everything is working correctly: - -1. Run the Geo Rake task on all nodes, everything should be green: - - ```shell - sudo gitlab-rake gitlab:geo:check - ``` - -1. Check the **primary** node's Geo dashboard for any errors. -1. Test the data replication by pushing code to the **primary** node and see if it - is received by **secondary** nodes. - -If you encounter any issues, see the [Geo troubleshooting guide](troubleshooting.md). + + diff --git a/doc/administration/geo/replication/updating_the_geo_sites.md b/doc/administration/geo/replication/updating_the_geo_sites.md new file mode 100644 index 00000000000..e82afe5f0d4 --- /dev/null +++ b/doc/administration/geo/replication/updating_the_geo_sites.md @@ -0,0 +1,54 @@ +--- +stage: Enablement +group: Geo +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: howto +--- + +# Updating the Geo sites **(PREMIUM SELF)** + +WARNING: +Read these sections carefully before updating your Geo sites. Not following +version-specific update steps may result in unexpected downtime. If you have +any specific questions, [contact Support](https://about.gitlab.com/support/#contact-support). + +Updating Geo sites involves performing: + +1. [Version-specific update steps](version_specific_updates.md), depending on the + version being updated to or from. +1. [General update steps](#general-update-steps), for all updates. + +## General update steps + +NOTE: +These general update steps are not intended for multi-site deployments, +and will cause downtime. If you want to avoid downtime, consider using +[zero downtime upgrades](../../../update/zero_downtime.md#multi-node--ha-deployment-with-geo). + +To update the Geo sites when a new GitLab version is released, update **primary** +and all **secondary** sites: + +1. **Optional:** [Pause replication on each **secondary** sites.](../index.md#pausing-and-resuming-replication) +1. SSH into each node of the **primary** site. +1. [Upgrade GitLab on the **primary** site](../../../update/package/index.md#upgrade-using-the-official-repositories). +1. SSH into each node of **secondary** sites. +1. [Upgrade GitLab on each **secondary** site](../../../update/package/index.md#upgrade-using-the-official-repositories). +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** sites, and check version in each. + +### Check status after updating + +Now that the update process is complete, you may want to check whether +everything is working correctly: + +1. Run the Geo Rake task on an application node for the primary and secondary sites. Everything should be green: + + ```shell + sudo gitlab-rake gitlab:geo:check + ``` + +1. Check the **primary** site's Geo dashboard for any errors. +1. Test the data replication by pushing code to the **primary** site and see if it + is received by **secondary** sites. + +If you encounter any issues, see the [Geo troubleshooting guide](troubleshooting.md). diff --git a/doc/administration/geo/replication/usage.md b/doc/administration/geo/replication/usage.md index 7fe8eec467e..f3c8f6ac759 100644 --- a/doc/administration/geo/replication/usage.md +++ b/doc/administration/geo/replication/usage.md @@ -11,7 +11,7 @@ type: howto After you set up the [database replication and configure the Geo nodes](../index.md#setup-instructions), use your closest GitLab site as you would do with the primary one. -You can push directly to a **secondary** site (for both HTTP, SSH including Git LFS), and the request will be proxied to the primary site instead ([introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in [GitLab Premium](https://about.gitlab.com/pricing/#self-managed) 11.3). +You can push directly to a **secondary** site (for both HTTP, SSH including Git LFS), and the request will be proxied to the primary site instead ([introduced](https://about.gitlab.com/releases/2018/09/22/gitlab-11-3-released/) in GitLab 11.3). Example of the output you will see when pushing to a **secondary** site: @@ -33,3 +33,13 @@ you can't store credentials in the URL like `user:password@URL`. Instead, you ca for Unix-like operating systems or `_netrc` for Windows. In that case, the credentials will be stored as a plain text. If you're looking for a more secure way to store credentials, you can use [Git Credential Storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). + +## Fetch Go modules from Geo secondary sites + +Go modules can be pulled from secondary sites, with a number of limitations: + +- Git configuration (using `insteadOf`) is needed to fetch data from the Geo secondary site. +- For private projects, authentication details need to be specified in `~/.netrc`. + +Read more in the +[working with projects `go get` documentation](../../../user/project/working_with_projects.md#fetch-go-modules-from-geo-secondary-sites). diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md index 155c06f90b8..84193e6baac 100644 --- a/doc/administration/geo/replication/version_specific_updates.md +++ b/doc/administration/geo/replication/version_specific_updates.md @@ -8,9 +8,44 @@ type: howto # Version-specific update instructions **(PREMIUM SELF)** Review this page for update instructions for your version. These steps -accompany the [general steps](updating_the_geo_nodes.md#general-update-steps) +accompany the [general steps](updating_the_geo_sites.md#general-update-steps) for updating Geo nodes. +## Updating to 14.1, 14.2, 14.3 + +We found an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336013) where the Container Registry replication wasn't fully working if you used multi-arch images. In case of a multi-arch image, only the primary architecture (for example `amd64`) would be replicated to the secondary node. This has been [fixed in GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67624) and was backported to 14.2 and 14.1, but manual steps are required to force a re-sync. + +You can check if you are affected by running: + +```shell +docker manifest inspect | jq '.mediaType' +``` + +Where `` is a container image on your secondary node. +If the output matches `application/vnd.docker.distribution.manifest.list.v2+json` +(there can be a `mediaType` entry at several levels, we only care about the top level entry), +then you don't need to do anything. + +Otherwise, on all your **secondary** nodes, in a [Rails console](../../operations/rails_console.md), run the following: + + ```ruby + list_type = 'application/vnd.docker.distribution.manifest.list.v2+json' + + Geo::ContainerRepositoryRegistry.synced.each do |gcr| + cr = gcr.container_repository + primary = Geo::ContainerRepositorySync.new(cr) + cr.tags.each do |tag| + primary_manifest = JSON.parse(primary.send(:client).repository_raw_manifest(cr.path, tag.name)) + next unless primary_manifest['mediaType'].eql?(list_type) + + cr.delete_tag_by_name(tag.name) + end + primary.execute + end + ``` + +If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your Container Registry, we recommend [upgrading](updating_the_geo_sites.md) to at least GitLab 14.1. + ## Updating to GitLab 14.0/14.1 We found an issue where [Primary sites can not be removed from the UI](https://gitlab.com/gitlab-org/gitlab/-/issues/338231). @@ -277,7 +312,7 @@ GitLab 12.2 includes the following minor PostgreSQL updates: This update occurs even if major PostgreSQL updates are disabled. -Before [refreshing Foreign Data Wrapper during a Geo upgrade](https://docs.gitlab.com/omnibus/update/README.html#run-post-deployment-migrations-and-checks), +Before [refreshing Foreign Data Wrapper during a Geo upgrade](../../../update/zero_downtime.md#step-4-run-post-deployment-migrations-and-checks), restart the Geo tracking database: ```shell diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index fa343f7eb40..d72bb0737ae 100644 --- a/doc/administration/geo/setup/database.md +++ b/doc/administration/geo/setup/database.md @@ -501,6 +501,79 @@ two other clusters of nodes supporting a Geo **secondary** site. One for the main database and the other for the tracking database. For more information, see [High Availability with Omnibus GitLab](../../postgresql/replication_and_failover.md). +### Changing the replication password + +To change the password for the [replication user](https://wiki.postgresql.org/wiki/Streaming_Replication) +when using Omnibus-managed PostgreSQL instances: + +On the GitLab Geo **primary** server: + +1. The default value for the replication user is `gitlab_replicator`, but if you've set a custom replication + user in your `/etc/gitlab/gitlab.rb` under the `postgresql['sql_replication_user']` setting, make sure to + adapt the following instructions for your own user. + + Generate an MD5 hash of the desired password: + + ```shell + sudo gitlab-ctl pg-password-md5 gitlab_replicator + # Enter password: + # Confirm password: + # 950233c0dfc2f39c64cf30457c3b7f1e + ``` + + Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab_replicator` + postgresql['sql_replication_password'] = '' + ``` + +1. Save the file and reconfigure GitLab to change the replication user's password in PostgreSQL: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +1. Restart PostgreSQL for the replication password change to take effect: + + ```shell + sudo gitlab-ctl restart postgresql + ``` + +Until the password is updated on any **secondary** servers, the [PostgreSQL log](../../logs.md#postgresql-logs) on +the secondaries will report the following error message: + +```console +FATAL: could not connect to the primary server: FATAL: password authentication failed for user "gitlab_replicator" +``` + +On all GitLab Geo **secondary** servers: + +1. The first step isn't necessary from a configuration perspective, since the hashed `'sql_replication_password'` + is not used on the GitLab Geo **secondary**. However in the event that **secondary** needs to be promoted + to the GitLab Geo **primary**, make sure to match the `'sql_replication_password'` in the secondary + server configuration. + + Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab_replicator` on the Geo primary + postgresql['sql_replication_password'] = '' + ``` + +1. During the initial replication setup, the `gitlab-ctl replicate-geo-database` command writes the plaintext + password for the replication user account to two locations: + + - `gitlab-geo.conf`: Used by the PostgreSQL replication process, written to the PostgreSQL data + directory, by default at `/var/opt/gitlab/postgresql/data/gitlab-geo.conf`. + - `.pgpass`: Used by the `gitlab-psql` user, located by default at `/var/opt/gitlab/postgresql/.pgpass`. + + Update the plaintext password in both of these files, and restart PostgreSQL: + + ```shell + sudo gitlab-ctl restart postgresql + ``` + ## Multi-node database replication In GitLab 14.0, Patroni replaced `repmgr` as the supported @@ -521,7 +594,7 @@ For instructions about how to set up Patroni on the primary site, see the #### Configuring Patroni cluster for a Geo secondary site -In a Geo secondary site, the main PostgreSQL database is a read-only replica of the primary site’s PostgreSQL database. +In a Geo secondary site, the main PostgreSQL database is a read-only replica of the primary site's PostgreSQL database. If you are currently using `repmgr` on your Geo primary site, see [these instructions](#migrating-from-repmgr-to-patroni) for migrating from `repmgr` to Patroni. @@ -651,7 +724,7 @@ Refer to your preferred Load Balancer's documentation for further guidance. ##### Step 3. Configure a PgBouncer node on the secondary site A production-ready and highly available configuration requires at least -three Consul nodes, a minimum of one PgBouncer node, but it’s recommended to have +three Consul nodes, a minimum of one PgBouncer node, but it's recommended to have one per database node. An internal load balancer (TCP) is required when there is more than one PgBouncer service nodes. The internal load balancer provides a single endpoint for connecting to the PgBouncer cluster. For more information, diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md index 56d196b54ec..13dbf9d1434 100644 --- a/doc/administration/geo/setup/external_database.md +++ b/doc/administration/geo/setup/external_database.md @@ -249,7 +249,7 @@ the tracking database on port 5432. gitlab-rake geo:db:create ``` -1. The reconfigure should automatically migrate the database. You can migrate the database manually if needed, for example if `gitlab_rails['auto_migrate'] = false`: +1. The reconfigure should automatically migrate the database. You can migrate the database manually if needed, for example if `geo_secondary['auto_migrate'] = false`: ```shell gitlab-rake geo:db:migrate diff --git a/doc/administration/get_started.md b/doc/administration/get_started.md index 6fe66aa1642..c0d5a45d8d1 100644 --- a/doc/administration/get_started.md +++ b/doc/administration/get_started.md @@ -137,7 +137,7 @@ Keep your configuration files and backup archives in a separate location to ensu You can restore a backup only to **the exact same version and type** (Community Edition/Enterprise Edition) of GitLab on which it was created. - Review the [Omnibus backup and restore documentation](https://docs.gitlab.com/omnibus/settings/backups). -- Review the [Helm Chart backup and restore documentation](https://docs.gitlab.com/charts/backup-restore). +- Review the [Helm Chart backup and restore documentation](https://docs.gitlab.com/charts/backup-restore/). ### Back up GitLab SaaS @@ -177,7 +177,7 @@ The EC2 instance meets the requirements for an application data backup by taking In general, if you're running GitLab on a virtualized server, you can create VM snapshots of the entire GitLab server. It is common for a VM snapshot to require you to power down the server. -#### Option 2: GitLab Geo +#### Option 2: GitLab Geo **(PREMIUM SELF)** Geo provides local, read-only instances of your GitLab instances. @@ -191,7 +191,7 @@ Learn more about [replication limitations](../administration/geo/replication/dat GitLab provides support for self-managed GitLab through different channels. -- Priority support: Premium and Ultimate self-managed customers receive priority support with tiered response times. +- Priority support: [Premium and Ultimate](https://about.gitlab.com/pricing/) self-managed customers receive priority support with tiered response times. Learn more about [upgrading to priority support](https://about.gitlab.com/support/#upgrading-to-priority-support). - Live upgrade assistance: Get one-on-one expert guidance during a production upgrade. With your **priority support plan**, you're eligible for a live, scheduled screen-sharing session with a member of our support team. diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index e3e2db81fb0..c8c532e9a01 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -99,7 +99,7 @@ $ GIT_TRACE_PACKET=1 git -c protocol.version=2 ls-remote https://your-gitlab-ins Verify Git v2 is used by the client: ```shell -GIT_SSH_COMMAND="ssh -v" git -c protocol.version=2 ls-remote ssh://git@your-gitlab-instance.com/group/repo.git 2>&1 |grep GIT_PROTOCOL +GIT_SSH_COMMAND="ssh -v" git -c protocol.version=2 ls-remote ssh://git@your-gitlab-instance.com/group/repo.git 2>&1 | grep GIT_PROTOCOL ``` You should see that the `GIT_PROTOCOL` environment variable is sent: diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md index 5e8cbac42c1..d0841f4e607 100644 --- a/doc/administration/gitaly/configure_gitaly.md +++ b/doc/administration/gitaly/configure_gitaly.md @@ -41,9 +41,8 @@ However, Gitaly can be deployed to its own server, which can benefit GitLab inst multiple machines. NOTE: -When configured to run on their own servers, Gitaly servers -[must be upgraded](https://docs.gitlab.com/omnibus/update/#upgrading-gitaly-servers) before Gitaly -clients in your cluster. +When configured to run on their own servers, Gitaly servers must be +[upgraded](../../update/package/index.md) before Gitaly clients in your cluster. The process for setting up Gitaly on its own server is: @@ -340,6 +339,12 @@ disable enforcement. For more information, see the documentation on configuring 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. +WARNING: +If directly copying repository data from a GitLab server to Gitaly, ensure that the metadata file, +default path `/var/opt/gitlab/git-data/repositories/.gitaly-metadata`, is not included in the transfer. +Copying this file causes GitLab to use the [Rugged patches](index.md#direct-access-to-git-in-gitlab) for repositories hosted on the Gitaly server, +leading to `Error creating pipeline` and `Commit not found` errors, or stale data. + ### Configure Gitaly clients As the final step, you must update Gitaly clients to switch from using local Gitaly service to use diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index bca83e903ac..7a7aac884ed 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -87,11 +87,8 @@ Gitaly comes pre-configured with Omnibus GitLab, which is a configuration - Omnibus GitLab installations for up to 2000 users, see [specific Gitaly configuration instructions](../reference_architectures/2k_users.md#configure-gitaly). - Source installations or custom Gitaly installations, see [Configure Gitaly](configure_gitaly.md). -GitLab installations for more than 2000 users should use Gitaly Cluster. - -NOTE: -If not set in GitLab, feature flags are read as false from the console and Gitaly uses their -default value. The default value depends on the GitLab version. +GitLab installations for more than 2000 active users performing daily Git write operation may be +best suited by using Gitaly Cluster. ## Gitaly Cluster @@ -137,7 +134,7 @@ In this example: - The [replication factor](#replication-factor) is `3`. There are three copies maintained of each repository. -The availability objectives for Gitaly clusters are: +The availability objectives for Gitaly clusters assuming a single node failure are: - **Recovery Point Objective (RPO):** Less than 1 minute. @@ -155,6 +152,58 @@ The availability objectives for Gitaly clusters are: Faster outage detection, to improve this speed to less than 1 second, is tracked [in this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/2608). +WARNING: +If complete cluster failure occurs, disaster recovery plans should be executed. These can affect the +RPO and RTO discussed above. + +### Architecture and configuration recommendations + +The following table provides recommendations based on your +requirements. Users means concurrent users actively performing +simultaneous Git Operations. + +Gitaly services are present in every GitLab installation and always coordinates Git repository storage and +retrieval. Gitaly can be as simple as a single background service when operating on a single instance Omnibus +GitLab (All of GitLab on one machine). Gitaly can be separated into it's own instance and it can be configured in +a full cluster configuration depending on scaling and availability requirements. + +The GitLab Reference Architectures provide guidance for what Gitaly configuration is advisable at each of the scales. +The Gitaly configuration is noted by the architecture diagrams and the table of required resources. + +| User Scaling | Reference Architecture To Use | GitLab Instance Configuration | Gitaly Configuration | Git Repository Storage | Instances Dedicated to Gitaly Services | +| ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------- | ------------------------------- | ---------------------------------- | -------------------------------------- | +| Up to 1000 Users | [1K](../reference_architectures/1k_users.md) | Single Instance for all of GitLab | Already Integrated as a Service | Local Disk | 0 | +| Up to 2999 Users | [2K](../reference_architectures/2k_users.md) | Horizontally Scaled GitLab Instance (Non-HA) | Single Gitaly Server | Local Disk of Gitaly Instance | 1 | +| 3000 Users and Over | [3K](../reference_architectures/1k_users.md) | Horizontally Scaled GitLab Instance with HA | Gitaly Cluster | Local Disk of Each Gitaly Instance | 8 | +| RTO/RPO Requirements for AZ Failure Tolerance Regardless of User Scale | [3K (with downscaling)](../reference_architectures/3k_users.md) | Custom (1) | Gitaly Cluster | Local Disk of Each Gitaly Instance | 8 | + +1. If you feel that you need AZ Failure Tolerance for user scaling lower than 3K, please contact Customer Success + to discuss your RTO and RPO needs and what options exist to meet those objectives. + +WARNING: +At present, some [known database inconsistency issues](#known-issues-impacting-gitaly-cluster) +exist in Gitaly Cluster. It is our recommendation that for now, you remain on your current service. +We will adjust the date for NFS support removal if this applies to you. + +### Known issues impacting Gitaly Cluster + +The following table outlines current known issues impacting the use of Gitaly Cluster. For +the most up to date status of these issues, please refer to the referenced issues / epics. + +| Issue | Summary | +| Gitaly Cluster + Geo can cause database inconsistencies | There are some conditions during Geo replication that can cause database inconsistencies with Gitaly Cluster. These have been identified and are being resolved by updating Gitaly Cluster to [identify repositories with a unique and persistent identifier](https://gitlab.com/gitlab-org/gitaly/-/issues/3485). | +| Database inconsistencies due to repository access outside of Gitaly Cluster's control | Operations that write to the repository storage which do not go through normal Gitaly Cluster methods can cause database inconsistencies. These can include (but are not limited to) snapshot restoration for cluster node disks, node upgrades which modify files under Git control, or any other disk operation that may touch repository storage external to GitLab. The Gitaly team is actively working to provide manual commands to [reconcile the Praefect database with the repository storage](https://gitlab.com/groups/gitlab-org/-/epics/6723). | + +### Snapshot backup and recovery limitations + +Gitaly Cluster does not support snapshot backups because these can cause issues where the +Praefect database becomes out of sync with the disk storage. Because of how Praefect rebuilds +the replication metadata of Gitaly disk information during a restore, we recommend using the +[official backup and restore Rake tasks](../../raketasks/backup_restore.md). + +To track progress on work on a solution for manually re-synchronizing the Praefect database +with disk storage, see [this epic](https://gitlab.com/groups/gitlab-org/-/epics/6575). + ### Virtual storage Virtual storage makes it viable to have a single repository storage in GitLab to simplify repository @@ -306,7 +355,10 @@ For configuration information, see [Configure replication factor](praefect.md#co For more information on configuring Gitaly Cluster, see [Configure Gitaly Cluster](praefect.md). -### Migrate to Gitaly Cluster +## Migrate to Gitaly Cluster + +We recommend you migrate to Gitaly Cluster if your +[requirements recommend](#architecture-and-configuration-recommendations) Gitaly Cluster. Whether migrating to Gitaly Cluster because of [NFS support deprecation](index.md#nfs-deprecation-notice) or to move from single Gitaly nodes, the basic process involves: @@ -318,6 +370,11 @@ or to move from single Gitaly nodes, the basic process involves: Gitaly Cluster, existing repositories stored outside Gitaly Cluster must be moved. There is no automatic migration but the moves can be scheduled with the GitLab API. +WARNING: +At present, some [known database inconsistency issues](#known-issues-impacting-gitaly-cluster) +exist in Gitaly Cluster. It is our recommendation that for now, you remain on your current service. +We will adjust the date for NFS support removal if this applies to you. + ## Monitor Gitaly and Gitaly Cluster You can use the available logs and [Prometheus metrics](../monitoring/prometheus/index.md) to @@ -449,6 +506,8 @@ To monitor [strong consistency](#strong-consistency), you can use the following - `gitaly_hook_transaction_voting_delay_seconds`, the client-side delay introduced by waiting for the transaction to be committed. +You can also monitor the [Praefect logs](../logs.md#praefect-logs). + ## Do not bypass Gitaly GitLab doesn't advise directly accessing Gitaly repositories stored on disk with a Git client, @@ -539,12 +598,6 @@ To see if GitLab can access the repository file system directly, we use the foll Direct Git access is enable by default in Omnibus GitLab because it fills in the correct repository paths in the GitLab configuration file `config/gitlab.yml`. This satisfies the UUID check. -WARNING: -If directly copying repository data from a GitLab server to Gitaly, ensure that the metadata file, -default path `/var/opt/gitlab/git-data/repositories/.gitaly-metadata`, is not included in the transfer. -Copying this file causes GitLab to use the Rugged patches for repositories hosted on the Gitaly server, -leading to `Error creating pipeline` and `Commit not found` errors, or stale data. - ### Transition to Gitaly Cluster For the sake of removing complexity, we must remove direct Git access in GitLab. However, we can't diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 4af7f1a58a5..eb666f1caf4 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -20,10 +20,6 @@ Configure Gitaly Cluster using either: Smaller GitLab installations may need only [Gitaly itself](index.md). -NOTE: -Upgrade instructions for Omnibus GitLab installations -[are available](https://docs.gitlab.com/omnibus/update/#gitaly-cluster). - ## Requirements The minimum recommended configuration for a Gitaly Cluster requires: @@ -279,7 +275,7 @@ you need to prepare PostgreSQL server with [setup instruction](#manual-database- ```ruby pgbouncer['databases'] = { - # Other database configuation including gitlabhq_production + # Other database configuration including gitlabhq_production ... praefect_production: { @@ -353,6 +349,7 @@ If there are multiple Praefect nodes: To complete this section you need a [configured PostgreSQL server](#postgresql), including: +WARNING: Praefect should be run on a dedicated node. Do not run Praefect on the application server, or a Gitaly node. @@ -994,7 +991,7 @@ Particular attention should be shown to: 1. Check that the Praefect storage is configured to store new repositories: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand the **Repository storage** section. @@ -1574,3 +1571,28 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t - Replace the placeholder `` with the virtual storage containing the Gitaly node storage to be checked. - Replace the placeholder `` with the Gitaly storage name containing up to date repositories. - Replace the placeholder `` with the Gitaly storage name containing outdated repositories. + +### Manually remove repositories + +> [Introduced](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3767) in GitLab 14.3. + +The `remove-repository` Praefect sub-command removes repositories from a Gitaly Cluster. It removes +all state associated with a given repository including: + +- On-disk repositories on all relevant Gitaly nodes. +- Any database state tracked by Praefect. + +```shell +sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml remove-repository -virtual-storage -repository +``` + +- `-virtual-storage` is the virtual storage the repository is located in. +- `-repository` is the repository's relative path in the storage. + +Sometimes parts of the repository continue to exist after running `remove-repository`. This can be caused +because of: + +- A deletion error. +- An in-flight RPC call targeting the repository. + +If this occurs, run `remove-repository` again. diff --git a/doc/administration/gitaly/troubleshooting.md b/doc/administration/gitaly/troubleshooting.md index 3dd700968f9..1b53a0994f5 100644 --- a/doc/administration/gitaly/troubleshooting.md +++ b/doc/administration/gitaly/troubleshooting.md @@ -23,7 +23,7 @@ See also [Gitaly timeout](../../user/admin_area/settings/gitaly_timeouts.md) set When using standalone Gitaly servers, you must make sure they are the same version as GitLab to ensure full compatibility: -1. On the top bar, select **Menu >** **{admin}** **Admin** on your GitLab instance. +1. On the top bar, select **Menu > Admin** on your GitLab instance. 1. On the left sidebar, select **Overview > Gitaly Servers**. 1. Confirm all Gitaly servers indicate that they are up to date. @@ -226,8 +226,8 @@ update the secrets file on the Gitaly server to match the Gitaly client, then ### Repository pushes fail with a `deny updating a hidden ref` error Due to [a change](https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3426) -introduced in GitLab 13.12, Gitaly has read-only, internal GitLab references that users are not -permitted to update. If you attempt to update internal references with `git push --mirror`, Git +introduced in GitLab 13.12, Gitaly has read-only, internal GitLab references that users are not +permitted to update. If you attempt to update internal references with `git push --mirror`, Git returns the rejection error, `deny updating a hidden ref`. The following references are read-only: @@ -243,7 +243,7 @@ To mirror-push branches and tags only, and avoid attempting to mirror-push prote git push origin +refs/heads/*:refs/heads/* +refs/tags/*:refs/tags/* ``` -Any other namespaces that the admin wants to push can be included there as well via additional patterns. +Any other namespaces that the admin wants to push can be included there as well via additional patterns. ### Command line tools cannot connect to Gitaly diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index 8f5bf2ee013..4de48aa3f14 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -27,7 +27,7 @@ GitLab automatically runs `git gc` and `git repack` on repositories after Git pu You can change how often this happens or turn it off: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Repository maintenance**. 1. In the **Housekeeping** section, configure the [housekeeping options](#housekeeping-options). @@ -62,6 +62,12 @@ Housekeeping also [removes unreferenced LFS files](../raketasks/cleanup.md#remov from your project on the same schedule as the `git gc` operation, freeing up storage space for your project. +WARNING: +Running `git gc` or `git repack` commands manually in the +[repository folder](repository_storage_types.md#from-project-name-to-hashed-path) +is discouraged. If the created pack files get incorrect access rights (that is, owned by the wrong user) +browsing to the project page might result in `404` and `503` errors. + ## How housekeeping handles pool repositories Housekeeping for pool repositories is handled differently from standard repositories. It is @@ -76,7 +82,7 @@ This is the current call stack by which it is invoked: 1. `ObjectPoolService#fetch` 1. `Gitaly::FetchIntoObjectPoolRequest` -To manually invoke it from a Rails console if needed, you can call +To manually invoke it from a [Rails console](operations/rails_console.md) if needed, you can call `project.pool_repository.object_pool.fetch`. This is a potentially long-running task, though Gitaly times out in about 8 hours. diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index c5cabc5794a..5b72583bc95 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -76,7 +76,7 @@ and use [an application password](https://support.google.com/mail/answer/185833) If you want to use Office 365, and two-factor authentication is enabled, make sure you're using an -[app password](https://docs.microsoft.com/en-us/azure/active-directory/user-help/multi-factor-authentication-end-user-app-passwords) +[app password](https://support.microsoft.com/en-us/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9) instead of the regular password for the mailbox. To set up a basic Postfix mail server with IMAP access on Ubuntu, follow the @@ -464,7 +464,7 @@ Example configurations for Microsoft Office 365 with IMAP enabled. NOTE: As of September 2020 sub-addressing support -[has been added to Office 365](https://office365.uservoice.com/forums/273493-office-365-admin/suggestions/18612754-support-for-dynamic-email-aliases-in-office-36). This feature is not +[has been added to Office 365](https://support.microsoft.com/en-us/office/uservoice-pages-430e1a78-e016-472a-a10f-dc2a3df3450a). This feature is not enabled by default, and must be enabled through PowerShell. This series of PowerShell commands enables [sub-addressing](#email-sub-addressing) @@ -638,7 +638,7 @@ incoming_email: #### Microsoft Graph -> Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/214900). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214900) in GitLab 13.11. GitLab can read incoming email using the Microsoft Graph API instead of IMAP. Because [Microsoft is deprecating IMAP usage with Basic Authentication](https://techcommunity.microsoft.com/t5/exchange-team-blog/announcing-oauth-2-0-support-for-imap-and-smtp-auth-protocols-in/ba-p/1330432), the Microsoft Graph API will soon be required for new Microsoft Exchange Online diff --git a/doc/administration/index.md b/doc/administration/index.md index 46624ab39a3..9412994edb7 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -111,7 +111,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. ### GitLab platform integrations -- [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/): Integrate with [Mattermost](https://mattermost.com), an open source, private cloud workplace for web messaging. +- [Mattermost](../integration/mattermost/index.md): Integrate with [Mattermost](https://mattermost.com), an open source, private cloud workplace for web messaging. - [PlantUML](integration/plantuml.md): Create diagrams in AsciiDoc and Markdown documents created in snippets, wikis, and repositories. - [Web terminals](integration/terminal.md): Provide terminal access to your applications deployed to Kubernetes from GitLab CI/CD [environments](../ci/environments/index.md#web-terminals). @@ -164,16 +164,16 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Limit repository size](../user/admin_area/settings/account_and_limit_settings.md): Set a hard limit for your repositories' size. - [Static objects external storage](static_objects_external_storage.md): Set external storage for static objects in a repository. -## Continuous Integration settings +## CI/CD settings -- [Enable/disable GitLab CI/CD](../ci/enable_or_disable_ci.md#make-gitlab-cicd-disabled-by-default-in-new-projects): Enable or disable GitLab CI/CD for your instance. +- [Enable or disable GitLab CI/CD](cicd.md#disable-gitlab-cicd-in-new-projects): Set new projects in your instance to have GitLab CI/CD enabled or disabled by default. - [GitLab CI/CD administration settings](../user/admin_area/settings/continuous_integration.md): Enable or disable Auto DevOps site-wide and define the artifacts' max size and expiration time. - [External Pipeline Validation](external_pipeline_validation.md): Enable, disable, and configure external pipeline validation. - [Job artifacts](job_artifacts.md): Enable, disable, and configure job artifacts (a set of files and directories which are outputted by a job when it completes successfully). - [Job logs](job_logs.md): Information about the job logs. - [Register runners](../ci/runners/runners_scope.md): Learn how to register and configure runners. - [Shared runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota): Limit the usage of pipeline minutes for shared runners. -- [Enable/disable Auto DevOps](../topics/autodevops/index.md#enable-or-disable-auto-devops): Enable or disable Auto DevOps for your instance. +- [Enable or disable Auto DevOps](../topics/autodevops/index.md#enable-or-disable-auto-devops): Enable or disable Auto DevOps for your instance. ## Snippet settings diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md index 1ea2ec4c904..24ffee088f3 100644 --- a/doc/administration/instance_limits.md +++ b/doc/administration/instance_limits.md @@ -78,6 +78,16 @@ This setting limits the request rate on the Packages API per user or IP. For mor - **Default rate limit**: Disabled by default. +### Git LFS + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68642) in GitLab 14.3. + +This setting limits the request rate on the [Git LFS](../topics/git/lfs/index.md) +requests per user. For more information, read +[GitLab Git Large File Storage (LFS) Administration](../administration/lfs/index.md). + +- **Default rate limit**: Disabled by default. + ### Import/Export > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35728) in GitLab 13.2. @@ -387,6 +397,31 @@ To set this limit for a self-managed installation, run the following in the Plan.default.actual_limits.update!(ci_pipeline_schedules: 100) ``` +### Limit the number of pipelines created by a pipeline schedule per day + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/323066) in GitLab 14.0. + +You can limit the number of pipelines that pipeline schedules can trigger per day. + +Schedules that try to run pipelines more frequently than the limit are slowed to a maximum frequency. +The frequency is calculated by dividing 1440 (the number minutes in a day) by the +limit value. For example, for a maximum frequency of: + +- Once per minute, the limit must be `1440`. +- Once per 10 minutes, the limit must be `144`. +- Once per 60 minutes, the limit must be `24` + +There is no limit for self-managed instances by default. + +To set this limit to `1440` on a self-managed 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_daily_pipeline_schedule_triggers: 1440) +``` + +This limit is [enabled on GitLab.com](../user/gitlab_com/index.md#gitlab-cicd). + ### Number of instance level variables > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216097) in GitLab 13.1. @@ -513,19 +548,61 @@ Update `ci_jobs_trace_size_limit` with the new value in megabytes: Plan.default.actual_limits.update!(ci_jobs_trace_size_limit: 125) ``` +### Maximum number of active DAST profile schedules per project + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68551) in GitLab 14.3. + +Limit the number of active DAST profile schedules per project. A DAST profile schedule can be active or inactive. + +You can change the limit in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session). +Update `dast_profile_schedules` with the new value: + +```ruby +Plan.default.actual_limits.update!(dast_profile_schedules: 50) +``` + +### Maximum size and depth of CI/CD configuration YAML files + +The default maximum size of a CI/CD configuration YAML file is 1 megabyte and the default depth is 100. + +You can change these limits in the [GitLab Rails console](operations/rails_console.md#starting-a-rails-console-session). +Update `max_yaml_size_bytes` with the new value in megabytes: + +```ruby +ApplicationSetting.update!(max_yaml_size_bytes: 2.megabytes) +``` + +Update `max_yaml_depth` with the new value in megabytes: + +```ruby +ApplicationSetting.update!(max_yaml_depth: 125) +``` + +To disable this limitation entirely, disable the feature flag in the console: + +```ruby +Feature.disable(:ci_yaml_limit_size) +``` + ## Instance monitoring and metrics -### Incident Management inbound alert limits +### Limit inbound incident management alerts > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17859) in GitLab 12.5. -Limiting inbound alerts for an incident reduces the number of alerts (issues) -that can be created within a period of time, which can help prevent overloading -your incident responders with duplicate issues. You can reduce the volume of -alerts in the following ways: +You can limit the number of inbound alerts for [incidents](../operations/incident_management/incidents.md) +that can be created in a period of time. The inbound [incident management](../operations/incident_management/index.md) +alert limit can help prevent overloading your incident responders by reducing the +number of alerts or duplicate issues. + +To set inbound incident management alert limits: -- Max requests per period per project, 3600 seconds by default. -- Rate limit period in seconds, 3600 seconds by default. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Network**. +1. Expand General **Incident Management Limits**. +1. Select the **Enable Incident Management inbound alert limit** checkbox. +1. Optional. Input a custom value for **Maximum requests per project per rate limit period**. Default is 3600. +1. Optional. Input a custom value for **Rate limit period**. Default is 3600 seconds. ### Prometheus Alert JSON payloads @@ -577,9 +654,9 @@ panel_groups: See [Environment Dashboard](../ci/environments/environments_dashboard.md#adding-a-project-to-the-dashboard) for the maximum number of displayed projects. -## Environment data on Deploy Boards +## Environment data on deploy boards -[Deploy Boards](../user/project/deploy_boards.md) load information from Kubernetes about +[Deploy boards](../user/project/deploy_boards.md) load information from Kubernetes about Pods and Deployments. However, data over 10 MB for a certain environment read from Kubernetes won't be shown. @@ -645,7 +722,7 @@ indexed, which have a separate limit. For more information, read - For self-managed installations, the field length is unlimited by default. You can configure this limit for self-managed installations when you -[enable Elasticsearch](../integration/elasticsearch.md#enabling-advanced-search). +[enable Elasticsearch](../integration/elasticsearch.md#enable-advanced-search). Set the limit to `0` to disable it. ## Wiki limits @@ -733,7 +810,7 @@ Set the limit to `0` to allow any file size. When asking for versions of a given NuGet package name, the GitLab Package Registry returns a maximum of 300 versions. -## Branch retargeting on merge **(FREE SELF)** +## Branch retargeting on merge > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. diff --git a/doc/administration/instance_review.md b/doc/administration/instance_review.md index f2ba3a5a562..b166bb32aa1 100644 --- a/doc/administration/instance_review.md +++ b/doc/administration/instance_review.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Instance Review **(FREE SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6995) in [GitLab Free](https://about.gitlab.com/pricing/) 11.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6995) in GitLab 11.3. If you run a medium-sized self-managed instance (50+ users) of a free version of GitLab, [either Community Edition or unlicensed Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/), diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md index 729894052b2..008d33c6c94 100644 --- a/doc/administration/integration/kroki.md +++ b/doc/administration/integration/kroki.md @@ -56,7 +56,7 @@ read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images You need to enable Kroki integration from Settings under Admin Area. To do that, log in with an administrator account and follow these steps: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. Go to **Settings > General**. 1. Expand the **Kroki** section. 1. Select **Enable Kroki** checkbox. diff --git a/doc/administration/integration/mailgun.md b/doc/administration/integration/mailgun.md new file mode 100644 index 00000000000..5a56aed4427 --- /dev/null +++ b/doc/administration/integration/mailgun.md @@ -0,0 +1,41 @@ +--- +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/#assignments +type: reference, howto +--- + +# Mailgun and GitLab **(FREE SELF)** + +When you use Mailgun to send emails for your GitLab instance and [Mailgun](https://www.mailgun.com/) +integration is enabled and configured in GitLab, you can receive their webhook for +permanent invite email failures. To set up the integration, you must: + +1. [Configure your Mailgun domain](#configure-your-mailgun-domain). +1. [Enable Mailgun integration](#enable-mailgun-integration). + +After completing the integration, Mailgun `permanent_failure` webhooks are sent to your GitLab instance. + +## Configure your Mailgun domain + +Before you can enable Mailgun in GitLab, set up your own Mailgun permanent failure endpoint to receive the webhooks. + +Using the [Mailgun webhook guide](https://www.mailgun.com/blog/a-guide-to-using-mailguns-webhooks/): + +1. Add a webhook with the **Event type** set to **Permanent Failure**. +1. Fill in the URL of your instance and include the `/-/members/mailgun/permanent_failures` path. + - Example: `https://myinstance.gitlab.com/-/members/mailgun/permanent_failures` + +## Enable Mailgun integration + +After configuring your Mailgun domain for the permanent failures endpoint, +you're ready to enable the Mailgun integration: + +1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. +1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the left sidebar, go to **Settings > General** and expand the **Mailgun** section. +1. Select the **Enable Mailgun** check box. +1. Enter the Mailgun HTTP webhook signing key as described in + [the Mailgun documentation](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks) and + shown in the [API security](https://app.mailgun.com/app/account/security/api_keys) section for your Mailgun account. +1. Select **Save changes**. diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 9f83ba8e972..94fef89d966 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -206,8 +206,8 @@ stop; After configuring your local PlantUML server, you're ready to enable the PlantUML integration: 1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user. -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, go to **Settings > General** and expand the **PlantUML** section. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, go to **Settings > General** and expand the **PlantUML** section. 1. Select the **Enable PlantUML** checkbox. 1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`, and click **Save changes**. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 1be234c2771..882580b35b6 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -100,7 +100,7 @@ they receive a `Connection failed` message. By default, terminal sessions do not expire. To limit the terminal session lifetime in your GitLab instance: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. Select [**Settings > Web terminal**](../../user/admin_area/settings/index.md#general). 1. Set a `max session time`. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 3b1d253b4b6..b4c16e007cc 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -435,6 +435,27 @@ Ci::JobArtifact.where(project: project).order(size: :desc).limit(50).map { |a| p You can change the number of job artifacts listed by modifying `.limit(50)` to the number you want. +#### List artifacts in a single project + +List the artifacts for a single project, sorted by artifact size. The output includes the: + +- ID of the job that created the artifact +- artifact size +- artifact file type +- artifact creation date +- on-disk location of the artifact + +```ruby +p = Project.find_by_id(:project ID) +arts = Ci::JobArtifact.where(project: p) + +list = arts.order('sort DESC').limit(50).each do |art| + puts "Job ID: #{art.job_id} - Size: #{art.size}b - Type: #{art.file_type} - Created: #{art.created_at} - File loc: #{art.file}" +end +``` + +To change the number of projects listed, change the number in `limit(50)`. + #### Delete job artifacts from jobs completed before a specific date WARNING: diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index a4fdf734c2e..64d9248cb16 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -138,7 +138,7 @@ For more information, see [delete references to missing artifacts](raketasks/che > - Enabled on GitLab.com. > - [Recommended for production use](https://gitlab.com/groups/gitlab-org/-/epics/4275) in GitLab 13.6. > - [Recommended for production use with AWS S3](https://gitlab.com/gitlab-org/gitlab/-/issues/273498) in GitLab 13.7. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-incremental-logging). **(FREE SELF)** +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-incremental-logging). By default job logs are sent from the GitLab Runner in chunks and cached temporarily on disk in `/var/opt/gitlab/gitlab-ci/builds` by Omnibus GitLab. After the job completes, @@ -183,7 +183,7 @@ Here is the detailed data flow: to disk, and there is no protection against misconfiguration. - There is [an epic tracking other potential limitations and improvements](https://gitlab.com/groups/gitlab-org/-/epics/3791). -### Enable or disable incremental logging **(FREE SELF)** +### Enable or disable incremental logging Incremental logging is under development, but [ready for production use as of GitLab 13.6](https://gitlab.com/groups/gitlab-org/-/epics/4275). It is deployed behind a feature flag that is **disabled by default**. diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 883f1db8e09..990287e3907 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -50,6 +50,7 @@ except those captured by `runit`. | [Mailroom](#mail_room_jsonlog-default) | **{check-circle}** Yes | **{check-circle}** Yes | | [NGINX](#nginx-logs) | **{check-circle}** Yes | **{check-circle}** Yes | | [PostgreSQL Logs](#postgresql-logs) | **{dotted-circle}** No | **{check-circle}** Yes | +| [Praefect Logs](#praefect-logs) | **{dotted-circle}** Yes| **{check-circle}** Yes | | [Prometheus Logs](#prometheus-logs) | **{dotted-circle}** No | **{check-circle}** Yes | | [Puma](#puma-logs) | **{check-circle}** Yes | **{check-circle}** Yes | | [Redis Logs](#redis-logs) | **{dotted-circle}** No | **{check-circle}** Yes | @@ -63,9 +64,6 @@ Depending on your installation method, this file is located at: - Omnibus GitLab: `/var/log/gitlab/gitlab-rails/production_json.log` - Installations from source: `/home/git/gitlab/log/production_json.log` -When GitLab is running in an environment other than production, -the corresponding log file is shown here. - It contains a structured log for Rails controller requests received from GitLab, thanks to [Lograge](https://github.com/roidrage/lograge/). Requests from the API are logged to a separate file in `api_json.log`. @@ -216,9 +214,6 @@ Depending on your installation method, this file is located at: - Omnibus GitLab: `/var/log/gitlab/gitlab-rails/production.log` - Installations from source: `/home/git/gitlab/log/production.log` -When GitLab is running in an environment other than production, -the corresponding log file is shown here. - It contains information about all performed requests. You can see the URL and type of request, IP address, and what parts of code were involved to service this particular request. Also, you can see all SQL @@ -556,10 +551,9 @@ access to Git repositories. ### For GitLab versions 12.10 and up -For GitLab version 12.10 and later, there are two `gitlab-shell.log` files. Information containing `git-{upload-pack,receive-pack}` requests is at `/var/log/gitlab/gitlab-shell/gitlab-shell.log`. Information about hooks to -GitLab Shell from Gitaly is at `/var/log/gitlab/gitaly/gitlab-shell.log`. +GitLab Shell from Gitaly is at `/var/log/gitlab/gitaly/current`. Example log entries for `/var/log/gitlab/gitlab-shell/gitlab-shell.log`: @@ -585,7 +579,7 @@ Example log entries for `/var/log/gitlab/gitlab-shell/gitlab-shell.log`: } ``` -Example log entries for `/var/log/gitlab/gitaly/gitlab-shell.log`: +Example log entries for `/var/log/gitlab/gitaly/current`: ```json { @@ -668,6 +662,12 @@ This file is at `/var/log/gitlab/gitaly/gitaly_ruby_json.log` and is produced by [`gitaly-ruby`](gitaly/reference.md#gitaly-ruby). It contains an access log of gRPC calls made by Gitaly to `gitaly-ruby`. +### `gitaly_hooks.log` + +This file is at `/var/log/gitlab/gitaly/gitaly_hooks.log` and is +produced by `gitaly-hooks` command. It also contains records about +failures received during processing of the responses from GitLab API. + ## Puma Logs ### `puma_stdout.log` @@ -1063,6 +1063,12 @@ For Omnibus GitLab installations, GitLab Exporter logs are in `/var/log/gitlab/g For Omnibus GitLab installations, GitLab Kubernetes Agent Server logs are in `/var/log/gitlab/gitlab-kas/`. +## Praefect Logs + +For Omnibus GitLab installations, Praefect logs are in `/var/log/gitlab/praefect/`. + +GitLab also tracks [Prometheus metrics for Praefect](gitaly/#monitor-gitaly-cluster). + ## Performance bar stats > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48149) in GitLab 13.7. diff --git a/doc/administration/maintenance_mode/index.md b/doc/administration/maintenance_mode/index.md index 7664c7c1751..39ee357cc2f 100644 --- a/doc/administration/maintenance_mode/index.md +++ b/doc/administration/maintenance_mode/index.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Maintenance Mode **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2149) in GitLab Premium 13.9. +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2149) in GitLab 13.9. Maintenance Mode allows administrators to reduce write operations to a minimum while maintenance tasks are performed. The main goal is to block all external actions that change the internal state, including the PostgreSQL database, but especially files, Git repositories, Container repositories, and so on. @@ -21,7 +21,7 @@ Maintenance Mode allows most external actions that do not change internal state. There are three ways to enable Maintenance Mode as an administrator: - **Web UI**: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Maintenance Mode**, and toggle **Enable Maintenance Mode**. You can optionally add a message for the banner as well. @@ -45,7 +45,7 @@ There are three ways to enable Maintenance Mode as an administrator: There are three ways to disable Maintenance Mode: - **Web UI**: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Maintenance Mode**, and toggle **Enable Maintenance Mode**. You can optionally add a message for the banner as well. @@ -171,7 +171,7 @@ it is recommended that you disable all cron jobs except for those related to Geo To monitor queues and disable jobs: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. ### Incident management diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md index 1133bff204c..d6b9fa2b8d3 100644 --- a/doc/administration/merge_request_diffs.md +++ b/doc/administration/merge_request_diffs.md @@ -265,3 +265,9 @@ by assigning different processes to different parts of the table. The `BATCH` and `UPDATE_DELAY` parameters allow the speed of the migration to be traded off against concurrent access to the table. The `ANSI` parameter should be set to false if your terminal does not support ANSI escape codes. + +By default, `sudo` does not preserve existing environment variables. You should append them, rather than prefix them. + +```shell +sudo gitlab-rake gitlab:external_diffs:force_object_storage START_ID=59946109 END_ID=59946109 UPDATE_DELAY=5 +``` diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index f8764468256..90d0b65dbe5 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -14,7 +14,7 @@ GitLab provides administrators insights into the health of their GitLab instance To provide a native experience (similar interacting with an application deployed using GitLab), a project called **Monitoring** is created: -- With [internal visibility](../../../public_access/public_access.md#internal-projects). +- With [internal visibility](../../../public_access/public_access.md#internal-projects-and-groups). - Under a group called **GitLab Instance**. The project is created specifically for visualizing and configuring the monitoring of your GitLab @@ -34,7 +34,7 @@ This project can be used to: ## Create the self monitoring project -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling** and expand **Self monitoring**. 1. Toggle **Self monitoring** on. 1. After your GitLab instance creates the project, GitLab displays a link to the @@ -47,7 +47,7 @@ WARNING: Deleting the self monitoring project removes any changes made to the project. If you create the project again, it's created in its default state. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, go to **Settings > Metrics and profiling** and expand **Self monitoring**. 1. Toggle **Self monitoring** off. 1. In the confirmation dialog that opens, click **Delete self monitoring project**. diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index e8abe2708c7..f316a75a868 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab Performance Monitoring is disabled by default. To enable it and change any of its settings: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling** (`/admin/application_settings/metrics_and_profiling`). 1. Add the necessary configuration changes. diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 0f40fd3c0e7..c37a264938e 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -62,7 +62,7 @@ repository. After setting up Grafana, you can enable a link to access it easily from the GitLab sidebar: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling** and expand **Metrics - Grafana**. 1. Select the **Add a link to Grafana** checkbox. @@ -79,7 +79,7 @@ GitLab displays your link in the **Menu > Admin > Monitoring > Metrics Dashboard > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5822) in GitLab 13.10. When setting up Grafana through the process above, no scope shows in the screen at -**Menu >** **{admin}** **Admin > Applications > GitLab Grafana**. However, the `read_user` scope is +**Menu > Admin > Applications > GitLab Grafana**. However, the `read_user` scope is required and is provided to the application automatically. Setting any scope other than `read_user` without also including `read_user` leads to this error when you try to log in using GitLab as the OAuth provider: diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index 6d9418133d8..ef4db93d5fc 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -72,7 +72,7 @@ From left to right, the performance bar displays: NOTE: Not all indicators are available in all environments. For instance, the memory view -requires running Ruby with [specific patches](https://gitlab.com/gitlab-org/gitlab-build-images/-/blob/master/patches/ruby/2.7.2/thread-memory-allocations-2.7.patch) +requires running Ruby with [specific patches](https://gitlab.com/gitlab-org/gitlab-build-images/-/blob/master/patches/ruby/2.7.4/thread-memory-allocations-2.7.patch) applied. When running GitLab locally using [GDK](../../../development/contributing/index.md#gitlab-development-kit), this is typically not the case and the memory view cannot be used. @@ -104,7 +104,7 @@ The performance bar is disabled by default for non-administrators. To enable it for a given group: 1. Sign in as a user with Administrator [role](../../../user/permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling** (`admin/application_settings/metrics_and_profiling`), and expand **Profiling - Performance bar**. diff --git a/doc/administration/monitoring/prometheus/gitlab_exporter.md b/doc/administration/monitoring/prometheus/gitlab_exporter.md index 4ba4cad9143..d9852524aec 100644 --- a/doc/administration/monitoring/prometheus/gitlab_exporter.md +++ b/doc/administration/monitoring/prometheus/gitlab_exporter.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab exporter **(FREE SELF)** ->- Available since [Omnibus GitLab 8.17](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1132). ->- Renamed from `GitLab monitor exporter` to `GitLab exporter` in [GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16511). +> Renamed from `GitLab monitor exporter` to `GitLab exporter` in [GitLab 12.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16511). The [GitLab exporter](https://gitlab.com/gitlab-org/gitlab-exporter) enables you to measure various GitLab metrics pulled from Redis and the database in Omnibus GitLab @@ -33,8 +32,8 @@ the GitLab exporter exposed at `localhost:9168`. ## Use a different Rack server ->- Introduced in [Omnibus GitLab 13.8](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4896). ->- WEBrick is now the default Rack server instead of Puma. +> - Introduced in [Omnibus GitLab 13.8](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4896). +> - WEBrick is now the default Rack server instead of Puma. By default, the GitLab exporter runs on [WEBrick](https://github.com/ruby/webrick), a single-threaded Ruby web server. You can choose a different Rack server that better matches your performance needs. diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 459eb259498..c36d2b0f7a4 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w To enable the GitLab Prometheus metrics: 1. Log in to GitLab as a user with Administrator [role](../../../user/permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Metrics and profiling**. 1. Find the **Metrics - Prometheus** section, and select **Add link to Prometheus**. 1. [Restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) for the changes to take effect. @@ -252,12 +252,26 @@ configuration option in `gitlab.yml`. These metrics are served from the | `geo_group_wiki_repositories_synced` | Gauge | 13.10 | Number of syncable group wikis synced on secondary | `url` | | `geo_group_wiki_repositories_failed` | Gauge | 13.10 | Number of syncable group wikis failed on secondary | `url` | | `geo_group_wiki_repositories_registry` | Gauge | 13.10 | Number of syncable group wikis in the registry | `url` | +| `geo_pages_deployments` | Gauge | 14.3 | Number of pages deployments on primary | `url` | +| `geo_pages_deployments_checksum_total` | Gauge | 14.3 | Number of pages deployments tried to checksum on primary | `url` | +| `geo_pages_deployments_checksummed` | Gauge | 14.3 | Number of pages deployments successfully checksummed on primary | `url` | +| `geo_pages_deployments_checksum_failed` | Gauge | 14.3 | Number of pages deployments failed to calculate the checksum on primary | `url` | +| `geo_pages_deployments_synced` | Gauge | 14.3 | Number of syncable pages deployments synced on secondary | `url` | +| `geo_pages_deployments_failed` | Gauge | 14.3 | Number of syncable pages deployments failed to sync on secondary | `url` | +| `geo_pages_deployments_registry` | Gauge | 14.3 | Number of pages deployments in the registry | `url` | +| `geo_pages_deployments_verification_total` | Gauge | 14.3 | Number of pages deployments verifications tried on secondary | `url` | +| `geo_pages_deployments_verified` | Gauge | 14.3 | Number of pages deployments verified on secondary | `url` | +| `geo_pages_deployments_verification_failed` | Gauge | 14.3 | Number of pages deployments verifications failed on secondary | `url` | | `limited_capacity_worker_running_jobs` | Gauge | 13.5 | Number of running jobs | `worker` | | `limited_capacity_worker_max_running_jobs` | Gauge | 13.5 | Maximum number of running jobs | `worker` | | `limited_capacity_worker_remaining_work_count` | Gauge | 13.5 | Number of jobs waiting to be enqueued | `worker` | | `destroyed_job_artifacts_count_total` | Counter | 13.6 | Number of destroyed expired job artifacts | | | `destroyed_pipeline_artifacts_count_total` | Counter | 13.8 | Number of destroyed expired pipeline artifacts | | | `gitlab_optimistic_locking_retries` | Histogram | 13.10 | Number of retry attempts to execute optimistic retry lock | | +| `geo_uploads` | Gauge | 14.1 | Number of uploads on primary | `url` | +| `geo_uploads_synced` | Gauge | 14.1 | Number of uploads synced on secondary | `url` | +| `geo_uploads_failed` | Gauge | 14.1 | Number of syncable uploads failed to sync on secondary | `url` | +| `geo_uploads_registry` | Gauge | 14.1 | Number of uploads in the registry | `url` | ## Database load balancing metrics **(PREMIUM SELF)** diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index dd81f71d418..e04aad9c6b8 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -55,8 +55,7 @@ To disable Prometheus and all of its exporters, as well as any added in the futu ### Changing the port and address Prometheus listens on WARNING: -The following change was added in [Omnibus GitLab 8.17](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1261). Although possible, -it's not recommended to change the port Prometheus listens +Although possible, it's not recommended to change the port Prometheus listens on, as this might affect or conflict with other services running on the GitLab server. Proceed at your own risk. @@ -330,8 +329,6 @@ To add a Prometheus dashboard for a single server GitLab setup: ## GitLab metrics -> Introduced in GitLab 9.3. - GitLab monitors its own internal service metrics, and makes them available at the `/-/metrics` endpoint. Unlike other exporters, this endpoint requires authentication as it's available on the same URL and port as user traffic. Read more about the [GitLab Metrics](gitlab_metrics.md). @@ -380,9 +377,6 @@ The GitLab exporter allows you to measure various GitLab metrics, pulled from Re ## Configuring Prometheus to monitor Kubernetes -> - Introduced in GitLab 9.0. -> - Pod monitoring introduced in GitLab 9.4. - If your GitLab server is running within Kubernetes, Prometheus collects metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration](../../../user/project/integrations/prometheus.md) to monitor them. To disable the monitoring of Kubernetes: diff --git a/doc/administration/object_storage.md b/doc/administration/object_storage.md index b8a6f2acc56..6c77576cb27 100644 --- a/doc/administration/object_storage.md +++ b/doc/administration/object_storage.md @@ -14,7 +14,7 @@ typically much more performant, reliable, and scalable. ## Options -GitLab has been tested on a number of object storage providers: +GitLab has been tested by vendors and customers on a number of object storage providers: - [Amazon S3](https://aws.amazon.com/s3/) - [Google Cloud Storage](https://cloud.google.com/storage) @@ -22,7 +22,7 @@ GitLab has been tested on a number of object storage providers: - [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. +- On-premises hardware and appliances from various storage vendors, whose list is not officially established. - MinIO. We have [a guide to deploying this](https://docs.gitlab.com/charts/advanced/external-object-storage/minio.html) within our Helm Chart documentation. ### Known compatibility issues @@ -33,6 +33,10 @@ GitLab has been tested on a number of object storage providers: - Ceph S3 prior to [Kraken 11.0.2](https://ceph.com/releases/kraken-11-0-2-released/) does not support the [Upload Copy Part API](https://gitlab.com/gitlab-org/gitlab/-/issues/300604). You may need to [disable multi-threaded copying](#multi-threaded-copying). +- Amazon S3 [Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) + is not supported. Follow [issue #335775](https://gitlab.com/gitlab-org/gitlab/-/issues/335775) + for progress on enabling this option. + ## Configuration guides There are two ways of specifying object storage configuration in GitLab: @@ -70,6 +74,7 @@ because it does not require a shared folder. Consolidated object storage configuration can't be used for backups or Mattermost. See the [full table for a complete list](#storage-specific-configuration). +However, backups can be configured with [server side encryption](../raketasks/backup_restore.md#s3-encrypted-buckets) separately. Enabling consolidated object storage enables object storage for all object types. If you want to use local storage for specific object types, you can @@ -683,8 +688,8 @@ configuration. #### Encrypted S3 buckets -> - Introduced in [GitLab 13.1](https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/466) for instance profiles only and [S3 default encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html). -> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34460) for static credentials when [consolidated object storage configuration](#consolidated-object-storage-configuration) and [S3 default encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html) are used. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-workhorse/-/merge_requests/466) in GitLab 13.1 for instance profiles only and [S3 default encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34460) in GitLab 13.2 for static credentials when [consolidated object storage configuration](#consolidated-object-storage-configuration) and [S3 default encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html) are used. When configured either with an instance profile or with the consolidated object configuration, GitLab Workhorse properly uploads files to S3 @@ -695,7 +700,7 @@ supported since this requires sending the encryption keys in every request](http ##### Server-side encryption headers -> Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38240). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38240) in GitLab 13.3. Setting a default encryption on an S3 bucket is the easiest way to enable encryption, but you may want to [set a bucket policy to ensure diff --git a/doc/administration/operations/cleaning_up_redis_sessions.md b/doc/administration/operations/cleaning_up_redis_sessions.md index 194dd8f39e2..ed5014b65e1 100644 --- a/doc/administration/operations/cleaning_up_redis_sessions.md +++ b/doc/administration/operations/cleaning_up_redis_sessions.md @@ -1,64 +1,9 @@ --- -stage: Enablement -group: Distribution -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'index.md' +remove_date: '2021-12-10' --- -# Cleaning up stale Redis sessions +This document was moved to [another location](index.md). -Since version 6.2, GitLab stores web user sessions as key-value pairs in Redis. -Prior to GitLab 7.3, user sessions did not automatically expire from Redis. If -you have been running a large GitLab server (thousands of users) since before -GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis -database after you upgrade to GitLab 7.3. You can also perform a cleanup while -still running GitLab 7.2 or older, but in that case new stale sessions will -start building up again after you clean up. - -In GitLab versions prior to 7.3.0, the session keys in Redis are 16-byte -hexadecimal values such as '976aa289e2189b17d7ef525a6702ace9'. Starting with -GitLab 7.3.0, the keys are -prefixed with `session:gitlab:`, so they would look like -`session:gitlab:976aa289e2189b17d7ef525a6702ace9`. Below we describe how to -remove the keys in the old format. - -NOTE: -The instructions below must be modified in accordance with your -configuration settings if you have used the advanced Redis -settings outlined in -[Configuration Files Documentation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/README.md). - -First we define a shell function with the proper Redis connection details. - -```shell -rcli() { - # This example works for Omnibus installations of GitLab 7.3 or newer. For an - # installation from source you will have to change the socket path and the - # path to redis-cli. - sudo /opt/gitlab/embedded/bin/redis-cli -s /var/opt/gitlab/redis/redis.socket "$@" -} - -# test the new shell function; the response should be PONG -rcli ping -``` - -Now we do a search to see if there are any session keys in the old format for -us to clean up. - -```shell -# returns the number of old-format session keys in Redis -rcli keys '*' | grep '^[a-f0-9]\{32\}$' | wc -l -``` - -If the number is larger than zero, you can proceed to expire the keys from -Redis. If the number is zero there is nothing to clean up. - -```shell -# Tell Redis to expire each matched key after 600 seconds. -rcli keys '*' | grep '^[a-f0-9]\{32\}$' | awk '{ print "expire", $0, 600 }' | rcli -# This will print '(integer) 1' for each key that gets expired. -``` - -Over the next 15 minutes (10 minutes expiry time plus 5 minutes Redis -background save interval) your Redis database will be compacted. If you are -still using GitLab 7.2, users who are not clicking around in GitLab during the -10 minute expiry window will be signed out of GitLab. + + diff --git a/doc/administration/operations/extra_sidekiq_processes.md b/doc/administration/operations/extra_sidekiq_processes.md index 2cc4e3a4551..31cbd6c457b 100644 --- a/doc/administration/operations/extra_sidekiq_processes.md +++ b/doc/administration/operations/extra_sidekiq_processes.md @@ -90,7 +90,7 @@ To start multiple processes: To view the Sidekiq processes in GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. ## Negate settings diff --git a/doc/administration/operations/extra_sidekiq_routing.md b/doc/administration/operations/extra_sidekiq_routing.md index 6938f8a7012..bb8eb184302 100644 --- a/doc/administration/operations/extra_sidekiq_routing.md +++ b/doc/administration/operations/extra_sidekiq_routing.md @@ -40,6 +40,8 @@ In `/etc/gitlab/gitlab.rb`: ```ruby sidekiq['routing_rules'] = [ + # Do not re-route workers that require their own queue + ['tags=needs_own_queue', nil], # Route all non-CPU-bound workers that are high urgency to `high-urgency` queue ['resource_boundary!=cpu&urgency=high', 'high-urgency'], # Route all database, gitaly and global search workers that are throttled to `throttled` queue @@ -164,3 +166,32 @@ with the migration to avoid losing jobs entirely, especially in a system with long queues of jobs. The migration can be done by following the migration steps mentioned in [Sidekiq job migration](../../raketasks/sidekiq_job_migration.md) + +### Workers that cannot be migrated + +Some workers cannot share a queue with other workers - typically because +they check the size of their own queue - and so must be excluded from +this process. We recommend excluding these from any further worker +routing by adding a rule to keep them in their own queue, for example: + +```ruby +sidekiq['routing_rules'] = [ + ['tags=needs_own_queue', nil], + # ... +] +``` + +These queues will also need to be included in at least one [Sidekiq +queue group](extra_sidekiq_processes.md#start-multiple-processes). + +The following table shows the workers that should have their own queue: + +| Worker name | Queue name | GitLab issue | +| --- | --- | --- | +| `EmailReceiverWorker` | `email_receiver` | [`gitlab-com/gl-infra/scalability#1263`](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1263) | +| `ServiceDeskEmailReceiverWorker` | `service_desk_email_receiver` | [`gitlab-com/gl-infra/scalability#1263`](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/1263) | +| `ProjectImportScheduleWorker` | `project_import_schedule` | [`gitlab-org/gitlab#340630`](https://gitlab.com/gitlab-org/gitlab/-/issues/340630) | +| `HashedStorage::MigratorWorker` | `hashed_storage:hashed_storage_migrator` | [`gitlab-org/gitlab#340629`](https://gitlab.com/gitlab-org/gitlab/-/issues/340629) | +| `HashedStorage::ProjectMigrateWorker` | `hashed_storage:hashed_storage_project_migrate` | [`gitlab-org/gitlab#340629`](https://gitlab.com/gitlab-org/gitlab/-/issues/340629) | +| `HashedStorage::ProjectRollbackWorker` | `hashed_storage:hashed_storage_project_rollback` | [`gitlab-org/gitlab#340629`](https://gitlab.com/gitlab-org/gitlab/-/issues/340629) | +| `HashedStorage::RollbackerWorker` | `hashed_storage:hashed_storage_rollbacker` | [`gitlab-org/gitlab#340629`](https://gitlab.com/gitlab-org/gitlab/-/issues/340629) | diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 5c1271486c0..e30ad4d8248 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -106,7 +106,7 @@ users as long as a large file exists. To disable any more writes to the `authorized_keys` file: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Network**. 1. Expand **Performance optimization**. 1. Clear the **Write to "authorized_keys" file** checkbox. diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index 4b16c3b3a7e..7ccfa2739bb 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -8,11 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Keep your GitLab instance up and running smoothly. -- [Clean up Redis sessions](cleaning_up_redis_sessions.md): Prior to GitLab 7.3, - user sessions did not automatically expire from Redis. If - you have been running a large GitLab server (thousands of users) since before - GitLab 7.3 we recommend cleaning up stale sessions to compact the Redis - database after you upgrade to GitLab 7.3. - [Rake tasks](../../raketasks/index.md): Tasks for common administration and operational processes such as [cleaning up unneeded items from GitLab instance](../../raketasks/cleanup.md), integrity checks, and more. diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md index 765cf64e735..61a9ec8e7d4 100644 --- a/doc/administration/operations/moving_repositories.md +++ b/doc/administration/operations/moving_repositories.md @@ -39,6 +39,11 @@ WARNING: To move repositories into a [Gitaly Cluster](../gitaly/index.md#gitaly-cluster) in GitLab versions 13.12 to 14.1, you must [enable the `gitaly_replicate_repository_direct_fetch` feature flag](../feature_flags.md). +WARNING: +Repositories can be **permanently deleted** by a call to `/projects/:project_id/repository_storage_moves` +that attempts to move a project already stored in a Gitaly Cluster back into that cluster. +See [this issue for more details](https://gitlab.com/gitlab-org/gitaly/-/issues/3752). + Each repository is made read-only for the duration of the move. The repository is not writable until the move has completed. diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index e8477eaf686..775761d655d 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -36,6 +36,14 @@ For more details about the Puma configuration, see the ## Puma Worker Killer +Puma forks worker processes as part of a strategy to reduce memory use. + +Each time a worker is created, it shares memory with the primary process and +only uses additional memory when it makes changes or additions to its memory pages. + +Memory use by workers therefore increases over time, and Puma Worker Killer is the +mechanism that recovers this memory. + By default: - The [Puma Worker Killer](https://github.com/schneems/puma_worker_killer) restarts a worker if it @@ -56,6 +64,47 @@ To change the memory limit setting: sudo gitlab-ctl reconfigure ``` +There are costs associated with killing and replacing workers including +reduced capacity to run GitLab, and CPU that is consumed +restarting the workers. `per_worker_max_memory_mb` should be set to a +higher value if the worker killer is replacing workers too often. + +Worker count is calculated based on CPU cores, so a small GitLab deployment +with 4-8 workers may experience performance issues if workers are being restarted +frequently, once or more per minute. This is too often. + +A higher value of `1200` or more would be beneficial if the server has free memory. + +The worker killer checks every 20 seconds, and can be monitored using +[the Puma log](../logs.md#puma_stdoutlog) `/var/log/gitlab/puma/puma_stdout.log`. +For example, for GitLab 13.5: + +```plaintext +PumaWorkerKiller: Out of memory. 4 workers consuming total: 4871.23828125 MB +out of max: 4798.08 MB. Sending TERM to pid 26668 consuming 1001.00390625 MB. +``` + +From this output: + +- The formula that calculates the maximum memory value results in workers + being killed before they reach the `per_worker_max_memory_mb` value. +- The default values for the formula before GitLab 13.5 were 550MB for the primary + and `per_worker_max_memory_mb` specified 850MB for each worker. +- As of GitLab 13.5 the values are primary: 800MB, worker: 1024MB. +- The threshold for workers to be killed is set at 98% of the limit: + + ```plaintext + 0.98 * ( 800 + ( worker_processes * 1024MB ) ) + ``` + +- In the log output above, `0.98 * ( 800 + ( 4 * 1024 ) )` returns the + `max: 4798.08 MB` value. + +Increasing the maximum to `1200`, for example, would set a `max: 5488 MB` value. + +Workers use additional memory on top of the shared memory, how much +depends on a site's use of GitLab. + ## Worker timeout A [timeout of 60 seconds](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/initializers/rack_timeout.rb) @@ -95,7 +144,6 @@ considered as a fair tradeoff in a memory-constraint environment. When running Puma in Single mode, some features are not supported: -- Phased restart do not work: [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/300665) - [Phased restart](https://gitlab.com/gitlab-org/gitlab/-/issues/300665) - [Puma Worker Killer](https://gitlab.com/gitlab-org/gitlab/-/issues/300664) diff --git a/doc/administration/operations/sidekiq_memory_killer.md b/doc/administration/operations/sidekiq_memory_killer.md index 598baa4fcc7..e48ac6e65eb 100644 --- a/doc/administration/operations/sidekiq_memory_killer.md +++ b/doc/administration/operations/sidekiq_memory_killer.md @@ -4,7 +4,7 @@ group: Memory info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Sidekiq MemoryKiller +# Sidekiq MemoryKiller **(FREE SELF)** The GitLab Rails application code suffers from memory leaks. For web requests this problem is made manageable using diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md index 374eebeb773..814e742b026 100644 --- a/doc/administration/operations/ssh_certificates.md +++ b/doc/administration/operations/ssh_certificates.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # User lookup via OpenSSH's AuthorizedPrincipalsCommand **(FREE SELF)** -> [Available in](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19911) GitLab -> Community Edition 11.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19911) in GitLab 11.2. The default SSH authentication for GitLab requires users to upload their SSH public keys before they can use the SSH transport. diff --git a/doc/administration/operations/unicorn.md b/doc/administration/operations/unicorn.md deleted file mode 100644 index 6cee19186f9..00000000000 --- a/doc/administration/operations/unicorn.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'puma.md' -remove_date: '2021-08-26' ---- - -This file was moved to [another location](puma.md). - - - diff --git a/doc/administration/package_information/defaults.md b/doc/administration/package_information/defaults.md new file mode 100644 index 00000000000..45bea065995 --- /dev/null +++ b/doc/administration/package_information/defaults.md @@ -0,0 +1,72 @@ +--- +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 +--- + +# Package defaults + +Unless configuration is specified in the `/etc/gitlab/gitlab.rb` file, +the package will assume the defaults as noted below. + +## Ports + +See the table below for the list of ports that the Omnibus GitLab assigns +by default: + +| Component | On by default | Communicates via | Alternative | Connection port | +| :----------------------------------------------------: | :------------: | :--------------: | :---------: | :------------------------------------: | +| GitLab Rails | Yes | Port | X | 80 or 443 | +| GitLab Shell | Yes | Port | X | 22 | +| PostgreSQL | Yes | Socket | Port (5432) | X | +| Redis | Yes | Socket | Port (6379) | X | +| Puma | Yes | Socket | Port (8080) | X | +| GitLab Workhorse | Yes | Socket | Port (8181) | X | +| NGINX status | Yes | Port | X | 8060 | +| Prometheus | Yes | Port | X | 9090 | +| Node exporter | Yes | Port | X | 9100 | +| Redis exporter | Yes | Port | X | 9121 | +| PostgreSQL exporter | Yes | Port | X | 9187 | +| PgBouncer exporter | No | Port | X | 9188 | +| GitLab Exporter | Yes | Port | X | 9168 | +| Sidekiq exporter | Yes | Port | X | 8082 | +| Puma exporter | No | Port | X | 8083 | +| Geo PostgreSQL | No | Socket | Port (5431) | X | +| Redis Sentinel | No | Port | X | 26379 | +| Incoming email | No | Port | X | 143 | +| Elastic search | No | Port | X | 9200 | +| GitLab Pages | No | Port | X | 80 or 443 | +| GitLab Registry | No* | Port | X | 80, 443 or 5050 | +| GitLab Registry | No | Port | X | 5000 | +| LDAP | No | Port | X | Depends on the component configuration | +| Kerberos | No | Port | X | 8443 or 8088 | +| OmniAuth | Yes | Port | X | Depends on the component configuration | +| SMTP | No | Port | X | 465 | +| Remote syslog | No | Port | X | 514 | +| Mattermost | No | Port | X | 8065 | +| Mattermost | No | Port | X | 80 or 443 | +| PgBouncer | No | Port | X | 6432 | +| Consul | No | Port | X | 8300, 8301(UDP), 8500, 8600[^Consul-notes] | +| Patroni | No | Port | X | 8008 | +| GitLab KAS | No | Port | X | 8150 | +| Gitaly | No | Port | X | 8075 | + +Legend: + +- `Component` - Name of the component. +- `On by default` - Is the component running by default. +- `Communicates via` - How the component talks with the other components. +- `Alternative` - If it is possible to configure the component to use different type of communication. The type is listed with default port used in that case. +- `Connection port` - Port on which the component communicates. + +GitLab also expects a filesystem to be ready for the storage of Git repositories +and various other files. + +Note that if you are using NFS (Network File System), files will be carried +over a network which will require, based on implementation, ports `111` and +`2049` to be open. + +NOTE: +In some cases, the GitLab Registry will be automatically enabled by default. Please see [our documentation](../packages/container_registry.md) for more details + + [^Consul-notes]: If using additional Consul functionality, more ports may need to be opened. See the [official documentation](https://www.consul.io/docs/install/ports#ports-table) for the list. diff --git a/doc/administration/package_information/deprecated_os.md b/doc/administration/package_information/deprecated_os.md new file mode 100644 index 00000000000..251dbe1e20e --- /dev/null +++ b/doc/administration/package_information/deprecated_os.md @@ -0,0 +1,82 @@ +--- +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 +--- + +# OS Versions that are no longer supported + +GitLab provides omnibus packages for operating systems only until their +EOL (End-Of-Life). After the EOL date of the OS, GitLab will stop releasing +official packages. The list of deprecated operating systems and the final GitLab +release for them can be found below: + +| OS Version | End Of Life | Last supported GitLab version | +| --------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Raspbian Wheezy | [May 2015](https://downloads.raspberrypi.org/raspbian/images/raspbian-2015-05-07/) | [GitLab CE](https://packages.gitlab.com/app/gitlab/raspberry-pi2/search?q=gitlab-ce_8.17&dist=debian%2Fwheezy) 8.17 | +| OpenSUSE 13.2 | [January 2017](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-9.1&dist=opensuse%2F13.2) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-9.1&dist=opensuse%2F13.2) 9.1 | +| Ubuntu 12.04 | [April 2017](https://ubuntu.com/info/release-end-of-life) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_9.1&dist=ubuntu%2Fprecise) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_9.1&dist=ubuntu%2Fprecise) 9.1 | +| OpenSUSE 42.1 | [May 2017](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-9.3&dist=opensuse%2F42.1) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-9.3&dist=opensuse%2F42.1) 9.3 | +| OpenSUSE 42.2 | [January 2018](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-10.4&dist=opensuse%2F42.2) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-10.4&dist=opensuse%2F42.2) 10.4 | +| Debian Wheezy | [May 2018](https://www.debian.org/News/2018/20180601) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_11.6&dist=debian%2Fwheezy) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_11.6&dist=debian%2Fwheezy) 11.6 | +| Raspbian Jessie | [May 2017](https://downloads.raspberrypi.org/raspbian/images/raspbian-2017-07-05/) | [GitLab CE](https://packages.gitlab.com/app/gitlab/raspberry-pi2/search?q=gitlab-ce_11.7&dist=debian%2Fjessie) 11.7 | +| Ubuntu 14.04 | [April 2019](https://ubuntu.com/info/release-end-of-life) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_11.10&dist=ubuntu%2Ftrusty) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_11.10&dist=ubuntu%2Ftrusty) 11.10 | +| OpenSUSE 42.3 | [July 2019](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-12.1&dist=opensuse%2F42.3) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-12.1&dist=opensuse%2F42.3) 12.1 | +| OpenSUSE 15.0 | [December 2019](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-12.5&dist=opensuse%2F15.0) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-12.5&dist=opensuse%2F15.0) 12.5 | +| Raspbian Stretch | [June 2020](https://downloads.raspberrypi.org/raspbian/images/raspbian-2019-04-09/) | [GitLab CE](https://packages.gitlab.com/app/gitlab/raspberry-pi2/search?q=gitlab-ce_13.2&dist=raspbian%2Fstretch) 13.3 | +| Debian Jessie | [June 2020](https://www.debian.org/News/2020/20200709) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_13.2&dist=debian%2Fjessie) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_13.2&dist=debian%2Fjessie) 13.3 | +| CentOS 6 | [November 2020](https://wiki.centos.org/About/Product) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=13.6&filter=all&filter=all&dist=el%2F6) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=13.6&filter=all&filter=all&dist=el%2F6) 13.6 | +| OpenSUSE 15.1 | [November 2020](https://en.opensuse.org/Lifetime#Discontinued_distributions) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce-13.12&dist=opensuse%2F15.1) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee-13.12&dist=opensuse%2F15.2) 13.12 | +| Ubuntu 16.04 | [April 2021](https://ubuntu.com/info/release-end-of-life) | [GitLab CE](https://packages.gitlab.com/app/gitlab/gitlab-ce/search?q=gitlab-ce_13.12&dist=ubuntu%2Fxenial) / [GitLab EE](https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=gitlab-ee_13.12&dist=ubuntu%2Fxenial) 13.12 | + +NOTE: +An exception to this deprecation policy is when we are unable to provide +packages for the next version of the operating system. The most common reason +for this our package repository provider, Packagecloud, not supporting newer +versions and hence we can't upload packages to it. + +## Update GitLab package sources after upgrading the OS + +After upgrading the Operating System (OS) as per its own documentation, +it may be necessary to also update the GitLab package source URL +in your package manager configuration. +If your package manager reports that no further updates are available, +although [new versions have been released](https://about.gitlab.com/releases/categories/releases/), repeat the +"Add the GitLab package repository" instructions +of the [Linux package install guide](https://about.gitlab.com/install/#content). +Future GitLab upgrades will now be fetched according to your upgraded OS. + +## Supported Operating Systems + +GitLab officially supports LTS versions of operating systems. While OSs like +Ubuntu have a clear distinction between LTS and non-LTS versions, there are +other OSs, openSUSE for example, that don't follow the LTS concept. Hence to +avoid confusion, the official policy is that at any point of time, all the +operating systems supported by GitLab are listed in the [installation +page](https://about.gitlab.com/install/). + +The following lists the currently supported OSs and their possible EOL dates. + +| OS Version | First supported GitLab version | Arch | OS EOL | Details | +| ---------------- | ------------------------------ | --------------- | ------------- | ------------------------------------------------------------ | +| CentOS 7 | GitLab CE / GitLab EE 7.10.0 | x86_64 | June 2024 | | +| CentOS 8 | GitLab CE / GitLab EE 12.8.1 | x86_64, aarch64 | Dec 2021 | | +| Debian 9 | GitLab CE / GitLab EE 9.3.0 | amd64 | 2022 | | +| Debian 10 | GitLab CE / GitLab EE 12.2.0 | amd64, arm64 | TBD | | +| OpenSUSE 15.2 | GitLab CE / GitLab EE 13.11.0 | x86_64, aarch64 | Dec 2021 | | +| SLES 12 | GitLab EE 9.0.0 | x86_64 | Oct 2027 | | +| Ubuntu 18.04 | GitLab CE / GitLab EE 10.7.0 | amd64 | April 2023 | | +| Ubuntu 20.04 | GitLab CE / GitLab EE 13.2.0 | amd64, arm64 | April 2025 | | +| Raspbian Buster | GitLab CE 12.2.0 | armhf | 2022 | | + +### Packages for ARM64 + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/issues/27) in GitLab 13.4. + +GitLab provides arm64/aarch64 packages for some supported operating systems. +You can see if your operating system architecture is supported in the table +above. + +WARNING: +There are currently still some [known issues and limitation](https://gitlab.com/groups/gitlab-org/-/epics/4397) +running GitLab on ARM. diff --git a/doc/administration/package_information/deprecation_policy.md b/doc/administration/package_information/deprecation_policy.md new file mode 100644 index 00000000000..cc16661442a --- /dev/null +++ b/doc/administration/package_information/deprecation_policy.md @@ -0,0 +1,95 @@ +--- +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 +--- + +# Deprecation policy + +The Omnibus GitLab packages come with number of different libraries and services which offers users plethora of configuration options. + +As libraries and services get updated, their configuration options change +and become obsolete. To increase maintainability and preserve a working +setup, various configuration requires removal. + +## Configuration deprecation + +### Policy + +The Omnibus GitLab package will retain configuration for at least **one major** +version. We cannot guarantee that deprecated configuration +will be available in the next major release. See [example](#example) for more details. + +### Notice + +If the configuration becomes obsolete, we will announce the deprecation: + +- via release blog post on `https://about.gitlab.com/blog/`. The blog post item + will contain the deprecation notice together with the target removal date. +- via installation/reconfigure output (if applicable). +- via official documentation on `https://docs.gitlab.com/`. The documentation update will contain the corrected syntax (if applicable) or a date of configuration removal. + +### Procedure + +This section lists steps necessary for deprecating and removing configuration. + +We can differentiate two different types of configuration: + +- Sensitive: Configuration that can cause major service outage ( Data integrity, + installation integrity, preventing users from reaching the installation, etc.) +- Regular: Configuration that can make a feature unavailable but still makes the installation useable ( Change in default project/group settings, miscommunication with other components and similar ) + +We also need to differentiate deprecation and removal procedure. + +#### Deprecating configuration + +Deprecation procedure is similar for both `sensitive` and `regular` configuration. The only difference is in the removal target date. + +Common steps: + +1. Create an issue at the [Omnibus GitLab issue tracker](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues) with details on deprecation type and other necessary information. Apply the label `deprecation`. +1. Decide on the removal target for the deprecated configuration +1. Formulate deprecation notice for each item as noted in [Notice section](#notice) + +Removal target: + +For regular configuration, removal target should always be the date of the **next major** release. If the date is not known, you can reference the next major version. + +For sensitive configuration things are a bit more complicated. +We should aim to not remove sensitive configuration in the *next major* release if the next major release is 2 minor releases away (This number is chosen to match our security backport release policy). + +See the table below for some examples: + +| Config. type | Deprecation announced | Final minor release | Remove | +| -------- | -------- | -------- | -------- | +| Sensitive | 10.1.0 | 10.9.0 | 11.0.0 | +| Sensitive | 10.7.0 | 10.9.0 | 12.0.0 | +| Regular | 10.1.0 | 10.9.0 | 11.0.0 | +| Regular | 10.8.0 | 10.9.0 | 11.0.0 | + +#### Removing configuration + +When deprecation is announced and removal target set, the milestone for the issue +should be changed to match the removal target version. + +The final comment in the issue **has to have**: + +1. Text snippet for the release blog post section +1. Documentation MR ( or snippet ) for introducing the change +1. Draft MR removing the configuration OR details on what needs to be done. See [Adding deprecation messages](https://docs.gitlab.com/omnibus/development/adding-deprecation-messages.html) for more on this + +## Example + +User configuration available in `/etc/gitlab/gitlab.rb` was introduced in GitLab version 10.0, `gitlab_rails['configuration'] = true`. In GitLab version 10.4.0, a new change was introduced that requires rename of this configuration option. New configuration option is `gitlab_rails['better_configuration'] = true`. Development team will translate the old configuration into new one +and trigger a deprecation procedure. + +This means that these two configuration +options will both be valid through GitLab version 10. In other words, +if you still have `gitlab_rails['configuration'] = true` set in GitLab 10.8.0 +the feature will continue working the same way as if you had `gitlab_rails['better_configuration'] = true` set. +However, setting the old version of configuration will print out a deprecation +notice at the end of installation/upgrade/reconfigure run. + +With GitLab 11, `gitlab_rails['configuration'] = true` will no longer work and you will have to manually change the configuration in `/etc/gitlab/gitlab.rb` to the new valid config. +**Note** If this configuration option is sensitive and can put integrity of the installation or +data in danger, installation/upgrade will be aborted. diff --git a/doc/administration/package_information/index.md b/doc/administration/package_information/index.md new file mode 100644 index 00000000000..e18fb621b89 --- /dev/null +++ b/doc/administration/package_information/index.md @@ -0,0 +1,101 @@ +--- +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 +--- + +# Package information + +The Omnibus GitLab package is bundled with all dependencies required for GitLab +to function correctly. More details can be found +at [bundling dependencies document](omnibus_packages.md). + +## Package Version + +The released package versions are in the format `MAJOR.MINOR.PATCH-EDITION.OMNIBUS_RELEASE` + +| Component | Meaning | Example | +| --------- | ------- | ------- | +| MAJOR.MINOR.PATCH | The GitLab version this corresponds to | 13.3.0 | +| EDITION | The edition of GitLab this corresponds to | ee | +| OMNIBUS_RELEASE | The omnibus release. Usually, this will be 0. This will be incremented if we need to build a new package without changing the GitLab version. | 0 | + +## Licenses + +See [licensing](licensing.md) + +## Defaults + +The Omnibus GitLab package requires various configuration to get the +components in working order. +If the configuration is not provided, the package will use the default +values assumed in the package. + +These defaults are noted in the package [defaults document](defaults.md). + +## Checking the versions of bundled software + +Once the Omnibus GitLab package is installed, all versions of the bundled +libraries are located in `/opt/gitlab/version-manifest.txt`. + +If you don't have the package installed, you can always check the Omnibus GitLab +[source repository](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master), specifically the +[config directory](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/config). + +For example, if you take a look at the `8-6-stable` branch, you can conclude that +8.6 packages were running [Ruby 2.1.8](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/8-6-stable/config/projects/gitlab.rb#L48). +Or, that 8.5 packages were bundled with [NGINX 1.9.0](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/8-5-stable/config/software/nginx.rb#L20). + +## Signatures of GitLab, Inc. provided packages + +Documentation on package signatures can be found at [Signed Packages](signed_packages.md) + +## Checking for newer configuration options on upgrade + +Configuration file in `/etc/gitlab/gitlab.rb` is created on initial installation +of the Omnibus GitLab package. On subsequent package upgrades, the configuration +file is not updated with new configuration. This is done in order to avoid +accidental overwrite of user configuration provided in `/etc/gitlab/gitlab.rb`. + +New configuration options are noted in the +[`gitlab.rb.template` file](https://gitlab.com/gitlab-org/omnibus-gitlab/raw/master/files/gitlab-config-template/gitlab.rb.template). + +The Omnibus GitLab package also provides convenience command which will +compare the existing user configuration with the latest version of the +template contained in the package. + +To view a diff between your configuration file and the latest version, run: + +```shell +sudo gitlab-ctl diff-config +``` + +_**Note:** This command is available from GitLab 8.17_ + +**Important:** If you are copy-pasting the output of this command into your +`/etc/gitlab/gitlab.rb` configuration file, make sure to omit leading `+` and `-` +on each line. + +## Init system detection + +Omnibus GitLab will attempt to query the underlaying system in order to +check which init system it uses. +This manifests itself as a `WARNING` during the `sudo gitlab-ctl reconfigure` +run. + +Depending on the init system, this `WARNING` can be one of: + +```plaintext +/sbin/init: unrecognized option '--version' +``` + +when the underlying init system *IS NOT* upstart. + +```plaintext + -.mount loaded active mounted / +``` + +when the underlying init system *IS* systemd. + +These warnings _can be safely ignored_. They are not suppressed because this +allows everyone to debug possible detection issues faster. diff --git a/doc/administration/package_information/licensing.md b/doc/administration/package_information/licensing.md new file mode 100644 index 00000000000..8557a94bf93 --- /dev/null +++ b/doc/administration/package_information/licensing.md @@ -0,0 +1,79 @@ +--- +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 +--- + +# Package Licensing + +## License + +While GitLab itself is MIT, the Omnibus GitLab sources are licensed under the Apache-2.0. + +## License file location + +Starting with version 8.11, the Omnibus GitLab package contains license +information of all software that is bundled within the package. + +After installing the package, licenses for each individual bundled library +can be found in `/opt/gitlab/LICENSES` directory. + +There is also one `LICENSE` file which contains all licenses compiled together. +This compiled license can be found in `/opt/gitlab/LICENSE` file. + +Starting with version 9.2, the Omnibus GitLab package ships a +`dependency_licenses.json` file containing version and license information of +all bundled software, including software libraries, Ruby gems that the rails +application uses, and JavaScript libraries that is required for the frontend +components. This file, being in JSON format, is easily machine parseable and +can be used for automated checks or validations. The file may be found at +`/opt/gitlab/dependency_licenses.json`. + +Starting with version 11.3, we have also made the license information available +online, at: + +## Checking licenses + +The Omnibus GitLab package is made up of many pieces of software, comprising code +that is covered by many different licenses. Those licenses are provided and +compiled as stated above. + +Starting with version 8.13, GitLab has placed an additional step into +Omnibus GitLab. The `license_check` step calls +`lib/gitlab/tasks/license_check.rake`, which checks the compiled `LICENSE` file +against the current list of approved and questionable licenses as denoted in the +arrays at the top of the script. This script will output one of `Good`, +`Unknown` or `Check` for each piece of software that is a part of the +Omnibus GitLab package. + +- `Good`: denotes a license that is approved for all usage types, within GitLab and + Omnibus GitLab. +- `Unknown`: denotes a license that is not recognized in the list of 'good' or 'bad', + which should be immediately reviewed for implications of use. +- `Check`: denotes a license that has the potential be incompatible with GitLab itself, + and thus should be checked for how it is used as a part of the Omnibus GitLab package + to ensure compliance. + +This list is currently sourced from the [GitLab development documentation on licensing](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/doc/development/licensing.md). +However, due to the nature of the Omnibus GitLab package the licenses may not apply +in the same way. Such as with `git` and `rsync`. See the [GNU License FAQ](https://www.gnu.org/licenses/gpl-faq.en.html#MereAggregation) + +## License acknowledgements + +### libjpeg-turbo - BSD 3-clause license + +This software is based in part on the work of the Independent JPEG Group. + +## Trademark Usage + +Within the GitLab documentation, reference to third party technology(ies) and/or trademarks of third party entities, may be made. The inclusion of reference to third party technology and/or entities is solely for the purposes of example(s) of how GitLab software may interact with, or be used in conjunction with, such third party technology. +All trademarks, materials, documentation, and other intellectual property remain the property of any/all such third party. + +### Trademark Requirements + +Use of GitLab Trademarks must be in compliance with the standards set forth in [our guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/) (as updated from time to time). +CHEF® and all Chef marks are owned by Progress Software Corporation and must be used in accordance with the [Progress Software Trademark Usage Policy](https://www.progress.com/legal/trademarks). + +When using a GitLab or 3rd party trademark in documentation, include the (R) symbol in the first instance, for example, "Chef(R) is used for configuring...." You may omit the symbol in subsequent instances. + +If a trademark owner requires a particular notice or trademark requirement, such notice or requirement should be stated above. diff --git a/doc/administration/package_information/omnibus_packages.md b/doc/administration/package_information/omnibus_packages.md new file mode 100644 index 00000000000..aa73534fc55 --- /dev/null +++ b/doc/administration/package_information/omnibus_packages.md @@ -0,0 +1,115 @@ +--- +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 +--- + +# Omnibus based packages and images + +Below you can find some basic information on why GitLab provides packages and +a Docker image that come with bundled dependencies. + +These methods are great for physical and virtual machine installations, and simple Docker installations. + +## Goals + +We have a few core goals with these packages: + +1. Extremely easy to install, upgrade, maintain. +1. Support for a wide variety of operating systems +1. Wide support of cloud service providers + +## Omnibus GitLab Architecture + +GitLab in its core is a Ruby on Rails project. However, GitLab as a whole +application is more complex and has multiple components. If these components are +not present or are incorrectly configured, GitLab will not work or it will work +unpredictably. + +The [GitLab Architecture Overview](../../development/architecture.md#gitlab-architecture-overview) shows some of these components and how they +interact. Each of these components needs to be configured and kept up to date. + +Most of the components also have external dependencies. For example, the Rails +application depends on a number of [Ruby gems](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/Gemfile.lock). Some of these dependencies also +have their own external dependencies which need to be present on the Operating +System in order for them to function correctly. + +Furthermore, GitLab has a monthly release cycle requiring frequent maintenance +to stay up to date. + +All the things listed above present a challenge for the user maintaining the GitLab +installation. + +## External Software Dependencies + +For applications such as GitLab, external dependencies usually bring the following +challenges: + +- Keeping versions in sync between direct and indirect dependencies +- Availability of a version on a specific Operating System +- Version changes can introduce or remove previously used configuration +- Security implications when library is marked as vulnerable but does not have + a new version released yet + +Keep in mind that if a dependency exists on your Operating System, it does not +necessarily exist on other supported OSs. + +## Benefits + +A few benefits of a package with bundled dependencies: + +1. Minimal effort required to install GitLab. +1. Minimum configuration required to get GitLab up and running. +1. Minimum effort required to upgrade between GitLab versions. +1. Multiple platforms supported. +1. Maintenance on older platforms is greatly simplified. +1. Less effort to support potential issues. + +## Drawbacks + +Some drawbacks of a package with bundled dependencies: + +1. Duplication with possibly existing software. +1. Less flexibility in configuration. + +## Why would I install an omnibus package when I can use a system package? + +The answer can be simplified to: less maintenance required. Instead of handling +multiple packages that *can* break existing functionality if the versions are +not compatible, only handle one. + +Multiple packages require correct configuration in multiple locations. +Keeping configuration in sync can be error prone. + +If you have the skill set to maintain all current dependencies and enough time +to handle any future dependencies that might get introduced, the above listed +reasons might not be good enough for you to not use the omnibus package. + +There are two things to keep in mind before going down this route: + +1. Getting support for any problems + you encounter might be more difficult due to the number of possibilities that exist + when using a library version that is not tested by majority of users. +1. Omnibus package also allows shutting off of any services that you do not need, + if you need to run a component independently. For example, you can use a + [non-bundled PostgreSQL database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server) with the omnibus package. + +Keep in mind that a non-standard solution like the omnibus package +might be a better fit when the application has a number of moving parts. + +## Docker image with multiple services + +[GitLab Docker image](../../install/docker.md#gitlab-docker-images) is based on the omnibus package. + +Considering that container spawned from this image contains multiple processes, +these types of containers are also referred to as 'fat containers'. + +There are reasons for and against an image like this, but they are similar to +what was noted above: + +1. Very simple to get started. +1. Upgrading to the latest version is extremely simple. +1. Running separate services in multiple containers and keeping them running + can be more complex and might not be required for a given install. + +This method is useful for organizations just getting started with containers and schedulers, and may not be ready for a more complex installation. This method is a great introduction, and will work well for smaller organizations. diff --git a/doc/administration/package_information/postgresql_versions.md b/doc/administration/package_information/postgresql_versions.md new file mode 100644 index 00000000000..89da4864872 --- /dev/null +++ b/doc/administration/package_information/postgresql_versions.md @@ -0,0 +1,42 @@ +--- +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 +--- + +# PostgreSQL versions shipped with Omnibus GitLab + +NOTE: +This table lists only GitLab versions where a significant change happened in the +package regarding PostgreSQL versions, not all. + +Usually, PostgreSQL versions change with major or minor GitLab releases. However, patch versions +of Omnibus GitLab sometimes update the patch level of PostgreSQL. + +For example: + +- Omnibus 12.7.6 shipped with PostgreSQL 9.6.14 and 10.9. +- Omnibus 12.7.7 shipped with PostgreSQL 9.6.17 and 10.12. + +[Find out which versions of PostgreSQL (and other components) ship with +each Omnibus GitLab release](https://gitlab-org.gitlab.io/omnibus-gitlab/licenses.html). + +Read more about update policies and warnings in the PostgreSQL +[upgrade docs](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server). + +| GitLab version | PostgreSQL versions | Default version for fresh installs | Default version for upgrades | Notes | +| -------------- | --------------------- | ---------------------------------- | ---------------------------- | ----- | +| 14.1 | 12.6, 13.3 | 12.6 | 12.6 | PostgreSQL 13 available for fresh installations if not using Geo or High Availability. | +| 14.0 | 12.6 | 12.6 | 12.6 | HA installations with repmgr are no longer supported and will be prevented from upgrading to Omnibus GitLab 14.0 | +| 13.8 | 11.9, 12.4 | 12.4 | 12.4 | Package upgrades automatically performed PostgreSQL upgrade for nodes that are not part of a Geo or HA cluster.). | +| 13.7 | 11.9, 12.4 | 12.4 | 11.9 | For upgrades users can manually upgrade to 12.4 following the [upgrade docs](https://docs.gitlab.com/omnibus/settings/database.html#gitlab-133-and-later). | +| 13.4 | 11.9, 12.4 | 11.9 | 11.9 | Package upgrades aborted if users not running PostgreSQL 11 already | +| 13.3 | 11.7, 12.3 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already | +| 13.0 | 11.7 | 11.7 | 11.7 | Package upgrades aborted if users not running PostgreSQL 11 already | +| 12.10 | 9.6.17, 10.12, and 11.7 | 11.7 | 11.7 | Package upgrades automatically performed PostgreSQL upgrade for nodes that are not part of a Geo or repmgr cluster. | +| 12.8 | 9.6.17, 10.12, and 11.7 | 10.12 | 10.12 | Users can manually upgrade to 11.7 following the upgrade docs. | +| 12.0 | 9.6.11 and 10.7 | 10.7 | 10.7 | Package upgrades automatically performed PostgreSQL upgrade. | +| 11.11 | 9.6.11 and 10.7 | 9.6.11 | 9.6.11 | Users can manually upgrade to 10.7 following the upgrade docs. | +| 10.0 | 9.6.3 | 9.6.3 | 9.6.3 | Package upgrades aborted if users still on 9.2. | +| 9.0 | 9.2.18 and 9.6.1 | 9.6.1 | 9.6.1 | Package upgrades automatically performed PostgreSQL upgrade. | +| 8.14 | 9.2.18 and 9.6.1 | 9.2.18 | 9.2.18 | Users can manually upgrade to 9.6 following the upgrade docs. | diff --git a/doc/administration/package_information/signed_packages.md b/doc/administration/package_information/signed_packages.md new file mode 100644 index 00000000000..fb994809460 --- /dev/null +++ b/doc/administration/package_information/signed_packages.md @@ -0,0 +1,25 @@ +--- +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 +--- + +# Package Signatures + +As of the release of GitLab 9.5 on August 22, 2017, GitLab provides signed Omnibus GitLab packages for RPM and DEB based distributions. This means that all packages provided on are signed, starting with `9.5.0`, and all future versions of supported branches (e.g. `9.3.x` and `9.4.x` after August 22, 2017). Any package version prior to August 22, 2017, will not be signed. Please pass the appropriate argument to your package manager. (Example: `yum --nogpgcheck`) + +Omnibus GitLab packages produced by GitLab are created via the [Omnibus](https://github.com/chef/omnibus) tool, for which GitLab has added DEB signing via `debsigs` in [our own fork](https://gitlab.com/gitlab-org/omnibus). This addition, combined with the existing functionality of RPM signing, allows GitLab to provide signed packages for all supported distributions using DEB or RPM. + +These packages are produced by the GitLab CI process, as found in the [Omnibus GitLab project](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.gitlab-ci.yml), prior to their delivery to to ensure provide assurance that the packages are not altered prior to delivery to our community. + +## GnuPG Public Keys + +All packages are signed with [GnuPG](https://www.gnupg.org/), in a method appropriate for their format. The key used to sign these packages can be found on [pgp.mit.edu](https://pgp.mit.edu) at [0x3cfcf9baf27eab47](https://pgp.mit.edu/pks/lookup?op=vindex&search=0x3CFCF9BAF27EAB47) + +## Verifying Signatures + +Information on how to verify GitLab package signatures can be found in [Package Signatures](https://docs.gitlab.com/omnibus/update/package_signatures.html). + +## GPG Signature Management + +Information on how GitLab manages GPG keys for package signing can be found in [the runbooks](https://gitlab.com/gitlab-com/runbooks/-/blob/master/docs/packaging/manage-package-signing-keys.md). diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index eb118709f94..1067474c8b4 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -321,7 +321,7 @@ The different supported drivers are: | Driver | Description | |--------------|--------------------------------------| | `filesystem` | Uses a path on the local file system | -| `Azure` | Microsoft Azure Blob Storage | +| `azure` | Microsoft Azure Blob Storage | | `gcs` | Google Cloud Storage | | `s3` | Amazon Simple Storage Service. Be sure to configure your storage bucket with the correct [S3 Permission Scopes](https://docs.docker.com/registry/storage-drivers/s3/#s3-permission-scopes). | | `swift` | OpenStack Swift Object Storage | @@ -1054,6 +1054,80 @@ PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin You may want to add the `-m` flag to [remove untagged manifests and unreferenced layers](#removing-untagged-manifests-and-unreferenced-layers). +## Configuring GitLab and Registry to run on separate nodes (Omnibus GitLab) + +By default, package assumes that both services are running on the same node. +In order to get GitLab and Registry to run on a separate nodes, separate configuration +is necessary for Registry and GitLab. + +### Configuring Registry + +Below you will find configuration options you should set in `/etc/gitlab/gitlab.rb`, +for Registry to run separately from GitLab: + +- `registry['registry_http_addr']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L50). Needs to be reachable by web server (or LB). +- `registry['token_realm']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L53). Specifies the endpoint to use to perform authentication, usually the GitLab URL. + This endpoint needs to be reachable by user. +- `registry['http_secret']`, [random string](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L32). A random piece of data used to sign state that may be stored with the client to protect against tampering. +- `registry['internal_key']`, default [automatically generated](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/recipes/gitlab-rails.rb#L113-119). Contents of the key that GitLab uses to sign the tokens. They key gets created on the Registry server, but it won't be used there. +- `gitlab_rails['registry_key_path']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/recipes/gitlab-rails.rb#L35). This is the path where `internal_key` contents will be written to disk. +- `registry['internal_certificate']`, default [automatically generated](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/registry/recipes/enable.rb#L60-66). Contents of the certificate that GitLab uses to sign the tokens. +- `registry['rootcertbundle']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/registry/recipes/enable.rb#L60). Path to certificate. This is the path where `internal_certificate` + contents will be written to disk. +- `registry['health_storagedriver_enabled']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-7-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L88). Configure whether health checks on the configured storage driver are enabled. +- `gitlab_rails['registry_issuer']`, [default value](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/attributes/default.rb#L153). This setting needs to be set the same between Registry and GitLab. + +### Configuring GitLab + +Below you will find configuration options you should set in `/etc/gitlab/gitlab.rb`, +for GitLab to run separately from Registry: + +- `gitlab_rails['registry_enabled']`, must be set to `true`. This setting will + signal to GitLab that it should allow Registry API requests. +- `gitlab_rails['registry_api_url']`, default [set programmatically](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/10-3-stable/files/gitlab-cookbooks/gitlab/libraries/registry.rb#L52). This is the Registry URL used internally that users do not need to interact with, `registry['registry_http_addr']` with scheme. +- `gitlab_rails['registry_host']`, eg. `registry.gitlab.example`. Registry endpoint without the scheme, the address that gets shown to the end user. +- `gitlab_rails['registry_port']`. Registry endpoint port, visible to the end user. +- `gitlab_rails['registry_issuer']` must match the issuer in the Registry configuration. +- `gitlab_rails['registry_key_path']`, path to the key that matches the certificate on the + Registry side. +- `gitlab_rails['internal_key']`, contents of the key that GitLab uses to sign the tokens. + +## Architecture of GitLab Container Registry + +The GitLab registry is what users use to store their own Docker images. +Because of that the Registry is client facing, meaning that we expose it directly +on the web server (or load balancers, LB for short). + +![GitLab Registry diagram](img/gitlab-registry-architecture.png) + +The flow described by the diagram above: + +1. A user runs `docker login registry.gitlab.example` on their client. This reaches the web server (or LB) on port 443. +1. Web server connects to the Registry backend pool (by default, using port 5000). Since the user + didn’t provide a valid token, the Registry returns a 401 HTTP code and the URL (`token_realm` from + Registry configuration) where to get one. This points to the GitLab API. +1. The Docker client then connects to the GitLab API and obtains a token. +1. The API signs the token with the registry key and hands it to the Docker client +1. The Docker client now logs in again with the token received from the API. It can now push and pull Docker images. + +Reference: + +### Communication between GitLab and Registry + +Registry doesn’t have a way to authenticate users internally so it relies on +GitLab to validate credentials. The connection between Registry and GitLab is +TLS encrypted. The key is used by GitLab to sign the tokens while the certificate +is used by Registry to validate the signature. By default, a self-signed certificate key pair is generated +for all installations. This can be overridden as needed. + +GitLab interacts with the Registry using the Registry private key. When a Registry +request goes out, a new short-living (10 minutes) namespace limited token is generated +and signed with the private key. +The Registry then verifies that the signature matches the registry certificate +specified in its configuration and allows the operation. +GitLab background jobs processing (through Sidekiq) also interacts with Registry. +These jobs talk directly to Registry in order to handle image deletion. + ## Troubleshooting Before diving in to the following sections, here's some basic troubleshooting: @@ -1122,7 +1196,7 @@ CI/CD > Container Registry > Authorization token duration (minutes)**. ### Docker login attempt fails with: 'token signed by untrusted key' -[Registry relies on GitLab to validate credentials](https://docs.gitlab.com/omnibus/architecture/registry/). +[Registry relies on GitLab to validate credentials](#architecture-of-gitlab-container-registry) If the registry fails to authenticate valid login attempts, you get the following error message: ```shell diff --git a/doc/administration/packages/dependency_proxy.md b/doc/administration/packages/dependency_proxy.md index c4906ef6d8e..32e7e191011 100644 --- a/doc/administration/packages/dependency_proxy.md +++ b/doc/administration/packages/dependency_proxy.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Dependency Proxy administration **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. GitLab can be used as a dependency proxy for a variety of common package managers. diff --git a/doc/administration/packages/img/gitlab-registry-architecture.png b/doc/administration/packages/img/gitlab-registry-architecture.png new file mode 100644 index 00000000000..742678d5e11 Binary files /dev/null and b/doc/administration/packages/img/gitlab-registry-architecture.png differ diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 2c2e3fc0442..37473d35573 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -14,22 +14,17 @@ The Packages feature allows GitLab to act as a repository for the following: The Package Registry supports the following formats: -
-
- - - - - - - - - - - -
Package typeGitLab version
Composer13.2+
Conan12.6+
Go13.1+
Maven11.3+
npm11.7+
NuGet12.8+
PyPI12.10+
Generic packages13.5+
Helm Charts14.1+
-
-
+| Package type | GitLab version | +|-------------------------------------------------------------------|----------------| +| [Composer](../../user/packages/composer_repository/index.md) | 13.2+ | +| [Conan](../../user/packages/conan_repository/index.md) | 12.6+ | +| [Go](../../user/packages/go_proxy/index.md) | 13.1+ | +| [Maven](../../user/packages/maven_repository/index.md) | 11.3+ | +| [npm](../../user/packages/npm_registry/index.md) | 11.7+ | +| [NuGet](../../user/packages/nuget_repository/index.md) | 12.8+ | +| [PyPI](../../user/packages/pypi_repository/index.md) | 12.10+ | +| [Generic packages](../../user/packages/generic_packages/index.md) | 13.5+ | +| [Helm Charts](../../user/packages/helm_repository/index.md) | 14.1+ | ## Accepting contributions diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 5aeb3eaef7f..8b7af5ee170 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -196,43 +196,6 @@ to use the HTTPS protocol. WARNING: Multiple wildcards for one instance is not supported. Only one wildcard per instance can be assigned. -### Additional configuration for Docker container - -The GitLab Pages daemon doesn't have permissions to bind mounts when it runs -in a Docker container. To overcome this issue, you must change the `chroot` -behavior: - -1. Edit `/etc/gitlab/gitlab.rb`. -1. Set the `inplace_chroot` to `true` for GitLab Pages: - - ```ruby - gitlab_pages['inplace_chroot'] = true - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). - -NOTE: -`inplace_chroot` option might not work with the other features, such as [Pages Access Control](#access-control). -The [GitLab Pages README](https://gitlab.com/gitlab-org/gitlab-pages#caveats) has more information about caveats and workarounds. - -### Jailing mechanism disabled by default for API-based configuration - -Starting from GitLab 14.1 the [jailing/chroot mechanism is disabled by default](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/589). -If you are using API-based configuration and the new [Zip storage architecture](#zip-storage) -there is nothing you need to do. - -If you run into any problems, [open a new issue](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/new) -and enable the jail again by setting the environment variable: - -1. Edit `/etc/gitlab/gitlab.rb`. -1. Set the `DAEMON_ENABLE_JAIL` environment variable to `true` for GitLab Pages: - - ```ruby - gitlab_pages['env']['DAEMON_ENABLE_JAIL'] = "true" - ``` - -1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). - ### Global settings Below is a table of all configuration settings known to Pages in Omnibus GitLab, @@ -270,7 +233,7 @@ control over how the Pages daemon runs and serves content in your environment. | `auth_scope` | The OAuth application scope to use for authentication. Must match GitLab Pages OAuth application settings. Leave blank to use `api` scope by default. | | `gitlab_server` | Server to use for authentication when access control is enabled; defaults to GitLab `external_url`. | | `headers` | Specify any additional http headers that should be sent to the client with each response. Multiple headers can be given as an array, header and value as one string, for example `['my-header: myvalue', 'my-other-header: my-other-value']` | -| `inplace_chroot` | On [systems that don't support bind-mounts](index.md#additional-configuration-for-docker-container), this instructs GitLab Pages to `chroot` into its `pages_path` directory. Some caveats exist when using in-place `chroot`; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. | +| `inplace_chroot` | [REMOVED in GitLab 14.3.](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/561) On [systems that don't support bind-mounts](index.md#gitlab-pages-fails-to-start-in-docker-container), this instructs GitLab Pages to `chroot` into its `pages_path` directory. Some caveats exist when using in-place `chroot`; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. | | `enable_disk` | Allows the GitLab Pages daemon to serve content from disk. Shall be disabled if shared disk storage isn't available. | | `insecure_ciphers` | Use default list of cipher suites, may contain insecure ones like 3DES and RC4. | | `internal_gitlab_server` | Internal GitLab server address used exclusively for API requests. Useful if you want to send that traffic over an internal load balancer. Defaults to GitLab `external_url`. | @@ -298,8 +261,9 @@ control over how the Pages daemon runs and serves content in your environment. | `pages_path` | The directory on disk where pages are stored, defaults to `GITLAB-RAILS/shared/pages`. | | **`pages_nginx[]`** | | | `enable` | Include a virtual host `server{}` block for Pages inside NGINX. Needed for NGINX to proxy traffic back to the Pages daemon. Set to `false` if the Pages daemon should directly receive all requests, for example, when using [custom domains](index.md#custom-domains). | -| `FF_ENABLE_REDIRECTS` | Feature flag to disable redirects (enabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#disable-redirects) for more information. | -| `use_legacy_storage` | Temporarily-introduced parameter allowing to use legacy domain configuration source and storage. [Will be removed in GitLab 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166). | +| `FF_ENABLE_REDIRECTS` | Feature flag to enable/disable redirects (enabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#feature-flag-for-redirects) for more information. | +| `FF_ENABLE_PLACEHOLDERS` | Feature flag to enable/disable rewrites (disabled by default). Read the [redirects documentation](../../user/project/pages/redirects.md#feature-flag-for-rewrites) for more information. | +| `use_legacy_storage` | Temporarily-introduced parameter allowing to use legacy domain configuration source and storage. [Removed in 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166). | --- @@ -393,7 +357,7 @@ adding a GitLab-controlled verification code to the DNS records for that domain. If your user base is private or otherwise trusted, you can disable the verification requirement: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Clear the **Require users to prove ownership of custom domains** checkbox. @@ -410,7 +374,7 @@ sites served under a custom domain. To enable it: 1. Choose an email address on which you want to receive notifications about expiring domains. -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Enter the email address for receiving notifications and accept Let's Encrypt's Terms of Service. @@ -465,7 +429,7 @@ pre-existing applications must modify the GitLab Pages OAuth application. Follow this: 1. Enable [access control](#access-control). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Applications**. 1. Expand **GitLab Pages**. 1. Clear the `api` scope's checkbox and select the desired scope's checkbox (for example, @@ -484,7 +448,7 @@ This can be useful to preserve information published with Pages websites to the of your instance only. To do that: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Select the **Disable public access to Pages sites** checkbox. @@ -522,7 +486,7 @@ Authority (CA) in the system certificate store. For Omnibus, this is fixed by [installing a custom CA in Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -### Zip serving and cache configuration +### ZIP serving and cache configuration > [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/392) in GitLab 13.7. @@ -530,19 +494,19 @@ WARNING: These are advanced settings. The recommended default values are set inside GitLab Pages. You should change these settings only if absolutely necessary. Use extreme caution. -GitLab Pages can serve content from zip archives through object storage (an +GitLab Pages can serve content from ZIP archives through object storage (an [issue](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/485) exists for supporting disk storage -as well). It uses an in-memory cache to increase the performance when serving content from a zip +as well). It uses an in-memory cache to increase the performance when serving content from a ZIP archive. You can modify the cache behavior by changing the following configuration flags. | Setting | Description | | ------- | ----------- | -| `zip_cache_expiration` | The cache expiration interval of zip archives. Must be greater than zero to avoid serving stale content. Default is 60s. | +| `zip_cache_expiration` | The cache expiration interval of ZIP archives. Must be greater than zero to avoid serving stale content. Default is 60s. | | `zip_cache_cleanup` | The interval at which archives are cleaned from memory if they have already expired. Default is 30s. | | `zip_cache_refresh` | The time interval in which an archive is extended in memory if accessed before `zip_cache_expiration`. This works together with `zip_cache_expiration` to determine if an archive is extended in memory. See the [example below](#zip-cache-refresh-example) for important details. Default is 30s. | -| `zip_open_timeout` | The maximum time allowed to open a zip archive. Increase this time for big archives or slow network connections, as doing so may affect the latency of serving Pages. Default is 30s. | +| `zip_open_timeout` | The maximum time allowed to open a ZIP archive. Increase this time for big archives or slow network connections, as doing so may affect the latency of serving Pages. Default is 30s. | -#### Zip cache refresh example +#### ZIP cache refresh example Archives are refreshed in the cache (extending the time they are held in memory) if they're accessed before `zip_cache_expiration`, and the time left before expiring is less than or equal to @@ -556,7 +520,7 @@ opened) it's refreshed. This extends the time the archive remains in memory from After an archive reaches `zip_cache_expiration`, it's marked as expired and removed on the next `zip_cache_cleanup` interval. -![Zip cache configuration](img/zip_cache_configuration.png) +![ZIP cache configuration](img/zip_cache_configuration.png) ## Activate verbose logging for daemon @@ -665,7 +629,7 @@ Follow the steps below to configure the proxy listener of GitLab Pages. To set the global maximum pages size for a project: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Edit the **Maximum size of pages**. @@ -742,6 +706,9 @@ database encryption. Proceed with caution. gitlab_pages['gitlab_server'] = 'http://' ``` +1. If you have custom UID/GID settings on the **GitLab server**, add them to the **Pages server** `/etc/gitlab/gitlab.rb` as well, + otherwise running a `gitlab-ctl reconfigure` on the **GitLab server** can change file ownership and cause Pages requests to fail. + 1. Create a backup of the secrets file on the **Pages server**: ```shell @@ -1047,7 +1014,7 @@ If you use [object storage](#using-object-storage), you can disable local storag Starting from GitLab 13.12, this setting also disables the [legacy storage](#migrate-legacy-storage-to-zip-storage), so if you were using NFS to serve Pages, you can completely disconnect from it. -## Migrate GitLab Pages to 14.0 +## Prepare GitLab Pages for 14.0 In GitLab 14.0 a number of breaking changes were introduced which may require some user intervention. The steps below describe the best way to migrate without causing any downtime for your GitLab instance. @@ -1104,6 +1071,9 @@ You can also find the log file in `/var/log/gitlab/gitlab-pages/current`. ### `open /etc/ssl/ca-bundle.pem: permission denied` +WARNING: +This issue is fixed in GitLab 14.3 and above, try upgrading GitLab first. + GitLab Pages runs inside a `chroot` jail, usually in a uniquely numbered directory like `/tmp/gitlab-pages-*`. @@ -1135,6 +1105,9 @@ sudo gitlab-ctl restart gitlab-pages ### `dial tcp: lookup gitlab.example.com` and `x509: certificate signed by unknown authority` +WARNING: +This issue is fixed in GitLab 14.3 and above, try upgrading GitLab first. + When setting both `inplace_chroot` and `access_control` to `true`, you might encounter errors like: ```plaintext @@ -1260,6 +1233,14 @@ For example, you can adapt the `rsync` strategy from the [moving repositories documentation](../operations/moving_repositories.md). Alternatively, run the CI pipelines of those projects that contain a `pages` job again. +## 404 or 500 error when accessing GitLab Pages in a Geo setup + +Pages sites are only available on the primary Geo site, while the codebase of the project is available on all sites. + +If you try to access a Pages page on a secondary site, you will get a 404 or 500 HTTP code depending on the access control. + +Read more which [features don't support Geo replication/verification](../geo/replication/datatypes.md#limitations-on-replicationverification). + ### Failed to connect to the internal GitLab API If you see the following error: @@ -1297,7 +1278,7 @@ in all of your GitLab Pages instances. ### 500 error with `securecookie: failed to generate random iv` and `Failed to save the session` -This problem most likely results from an [out-dated operating system](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html). +This problem most likely results from an [out-dated operating system](../package_information/deprecated_os.md). The [Pages daemon uses the `securecookie` library](https://gitlab.com/search?group_id=9970&project_id=734943&repository_ref=master&scope=blobs&search=securecookie&snippets=false) to get random strings via [`crypto/rand` in Go](https://golang.org/pkg/crypto/rand/#pkg-variables). This requires the `getrandom` system call or `/dev/urandom` to be available on the host OS. Upgrading to an [officially supported operating system](https://about.gitlab.com/install/) is recommended. @@ -1306,7 +1287,7 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com This problem comes from the permissions of the GitLab Pages OAuth application. To fix it: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Applications > GitLab Pages**. 1. Edit the application. 1. Under **Scopes**, ensure that the `api` scope is selected. @@ -1391,17 +1372,12 @@ both servers. GitLab 14.0 introduces a number of changes to GitLab Pages which may require manual intervention. -1. Firstly [follow the migration guide](#migrate-gitlab-pages-to-140). +1. Firstly [follow the migration guide](#prepare-gitlab-pages-for-140). +1. Try to upgrade to GitLab 14.3 or above. Some of the issues were fixed in GitLab 14.1, 14.2 and 14.3. 1. If it doesn't work, see [GitLab Pages logs](#how-to-see-gitlab-pages-logs), and if you see any errors there then search them on this page. -The most common problem is when using [`inplace_chroot`](#dial-tcp-lookup-gitlabexamplecom-and-x509-certificate-signed-by-unknown-authority). - -NOTE: -Starting from 14.1, the chroot/jailing mechanism is -[disabled by default for API-based configuration](#jailing-mechanism-disabled-by-default-for-api-based-configuration). - WARNING: -As the last resort you can temporarily enable legacy storage and configuration mechanisms. Support for them [will be removed in GitLab 14.3](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6166), so GitLab Pages will stop working if don't resolve the underlying issue. +In GitLab 14.0-14.2 you can temporarily enable legacy storage and configuration mechanisms. To do that: @@ -1414,3 +1390,25 @@ To do that: ``` 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +### GitLab Pages fails to start in Docker container + +WARNING: +This issue is fixed in GitLab 14.3 and above, try upgrading GitLab first. + +The GitLab Pages daemon doesn't have permissions to bind mounts when it runs +in a Docker container. To overcome this issue, you must change the `chroot` +behavior: + +1. Edit `/etc/gitlab/gitlab.rb`. +1. Set the `inplace_chroot` to `true` for GitLab Pages: + + ```ruby + gitlab_pages['inplace_chroot'] = true + ``` + +1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). + +NOTE: +`inplace_chroot` option might not work with the other features, such as [Pages Access Control](#access-control). +The [GitLab Pages README](https://gitlab.com/gitlab-org/gitlab-pages#caveats) has more information about caveats and workarounds. diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index b5c3330b2ce..278d792052a 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -473,7 +473,7 @@ The default for the maximum size of unpacked archives per project is 100 MB. To change this value: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Pages**. 1. Update the value for **Maximum size of pages (MB)**. diff --git a/doc/administration/polling.md b/doc/administration/polling.md index 5c4ee837057..8bd28824f83 100644 --- a/doc/administration/polling.md +++ b/doc/administration/polling.md @@ -26,7 +26,7 @@ The default value (`1`) is recommended for the majority of GitLab installations. To adjust the polling interval multiplier: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**. 1. Expand **Polling interval multiplier**. 1. Set a value for the polling interval multiplier. This multiplier is applied to all resources at diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index 7171e90949e..e215622bbc7 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.md @@ -173,7 +173,7 @@ ote_pid | tls Some database changes have to be done directly, and not through PgBouncer. Read more about the affected tasks: [database restores](../../raketasks/backup_restore.md#backup-and-restore-for-installations-using-pgbouncer) -and [GitLab upgrades](https://docs.gitlab.com/omnibus/update/README.html#use-postgresql-ha). +and [GitLab upgrades](../../update/zero_downtime.md#use-postgresql-ha). 1. To find the primary node, run the following on a database node: diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 1308697c16e..2e0820b69c9 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -72,13 +72,13 @@ the PgBouncer service. ### Connection flow -Each service in the package comes with a set of [default ports](https://docs.gitlab.com/omnibus/package-information/defaults.html#ports). You may need to make specific firewall rules for the connections listed below: +Each service in the package comes with a set of [default ports](../package_information/defaults.md#ports). You may need to make specific firewall rules for the connections listed below: -- Application servers connect to either PgBouncer directly via its [default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#pgbouncer) or via a configured Internal Load Balancer (TCP) that serves multiple PgBouncers. -- PgBouncer connects to the primary database servers [PostgreSQL default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#postgresql) +- Application servers connect to either PgBouncer directly via its [default port](../package_information/defaults.md) or via a configured Internal Load Balancer (TCP) that serves multiple PgBouncers. +- PgBouncer connects to the primary database servers [PostgreSQL default port](../package_information/defaults.md) - Patroni actively manages the running PostgreSQL processes and configuration. -- PostgreSQL secondaries connect to the primary database servers [PostgreSQL default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#postgresql) -- Consul servers and agents connect to each others [Consul default ports](https://docs.gitlab.com/omnibus/package-information/defaults.html#consul) +- PostgreSQL secondaries connect to the primary database servers [PostgreSQL default port](../package_information/defaults.md) +- Consul servers and agents connect to each others [Consul default ports](../package_information/defaults.md) ## Setting it up @@ -183,7 +183,7 @@ Few things to remember about the service itself: - The service runs as the same system account as the database - In the package, this is by default `gitlab-psql` -- If you use a non-default user account for PgBouncer service (by default `pgbouncer`), you need to specify this username. +- If you use a non-default user account for PgBouncer service (by default `pgbouncer`), you need to specify this username. - Passwords are stored in the following locations: - `/etc/gitlab/gitlab.rb`: hashed, and in plain text - `/var/opt/gitlab/pgbouncer/pg_auth`: hashed @@ -306,7 +306,7 @@ If you enable Monitoring, it must be enabled on **all** database servers. #### Enable TLS support for the Patroni API By default, Patroni's [REST API](https://patroni.readthedocs.io/en/latest/rest_api.html#rest-api) is served over HTTP. -You have the option to enable TLS and use HTTPS over the same [port](https://docs.gitlab.com/omnibus/package-information/defaults.html#patroni). +You have the option to enable TLS and use HTTPS over the same [port](../package_information/defaults.md). To enable TLS, you need PEM-formatted certificate and private key files. Both files must be readable by the PostgreSQL user (`gitlab-psql` by default, or the one set by `postgresql['username']`): @@ -789,7 +789,7 @@ You do not need any special consideration for Patroni while provisioning your da Patroni monitors the cluster and handles any failover. When the primary node fails it works with Consul to notify PgBouncer. On failure, Patroni handles the transitioning of the old primary to a replica and rejoins it to the cluster automatically. -With Patroni, the connection flow is slightly different. Patroni on each node connects to Consul agent to join the cluster. Only after this point it decides if the node is the primary or a replica. Based on this decision, it configures and starts PostgreSQL which it communicates with directly over a Unix socket. This means that if the Consul cluster is not functional or does not have a leader, Patroni and by extension PostgreSQL does not start. Patroni also exposes a REST API which can be accessed via its [default port](https://docs.gitlab.com/omnibus/package-information/defaults.html#patroni) +With Patroni, the connection flow is slightly different. Patroni on each node connects to Consul agent to join the cluster. Only after this point it decides if the node is the primary or a replica. Based on this decision, it configures and starts PostgreSQL which it communicates with directly over a Unix socket. This means that if the Consul cluster is not functional or does not have a leader, Patroni and by extension PostgreSQL does not start. Patroni also exposes a REST API which can be accessed via its [default port](../package_information/defaults.md) on each node. ### Check replication status diff --git a/doc/administration/pseudonymizer.md b/doc/administration/pseudonymizer.md index 533ebe0ad2f..da3a2e4b34c 100644 --- a/doc/administration/pseudonymizer.md +++ b/doc/administration/pseudonymizer.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Pseudonymizer **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5532) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5532) in GitLab 11.1. As the GitLab database hosts sensitive information, using it unfiltered for analytics implies high security requirements. To help alleviate this constraint, the Pseudonymizer diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md index 56bf711f187..7cd7ecc26f7 100644 --- a/doc/administration/raketasks/check.md +++ b/doc/administration/raketasks/check.md @@ -204,12 +204,20 @@ See [LDAP Rake Tasks - LDAP Check](ldap.md#check) for details. The following are solutions to problems you might discover using the Rake tasks documented above. -### Dangling commits +### Dangling objects -`gitlab:git:fsck` can find dangling commits. To fix them, try -[enabling housekeeping](../housekeeping.md). +The `gitlab:git:fsck` task can find dangling objects such as: -If the issue persists, try triggering `gc` via the +```plaintext +dangling blob a12... +dangling commit b34... +dangling tag c56... +dangling tree d78... +``` + +To delete them, try [running housekeeping](../housekeeping.md). + +If the issue persists, try triggering garbage collection via the [Rails Console](../operations/rails_console.md#starting-a-rails-console-session): ```ruby @@ -217,6 +225,13 @@ p = Project.find_by_path("project-name") Repositories::HousekeepingService.new(p, :gc).execute ``` +If the dangling objects are younger than the 2 weeks default grace period, +and you don't want to wait until they expire automatically, run: + +```ruby +Repositories::HousekeepingService.new(p, :prune).execute +``` + ### Delete references to missing remote uploads `gitlab-rake gitlab:uploads:check VERBOSE=1` detects remote objects that do not exist because they were @@ -271,7 +286,7 @@ To delete these references to missing local artifacts (`job.log` files): ```ruby artifacts_deleted = 0 - ::Ci::JobArtifact.all.each do |artifact| ### Iterate artifacts + ::Ci::JobArtifact.find_each do |artifact| ### Iterate artifacts # next if artifact.file.filename != "job.log" ### Uncomment if only `job.log` files' references are to be processed next if artifact.file.exists? ### Skip if the file reference is valid artifacts_deleted += 1 diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md index 0338732e886..f29e2a6c7f6 100644 --- a/doc/administration/raketasks/github_import.md +++ b/doc/administration/raketasks/github_import.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitHub import **(FREE SELF)** -> [Introduced]( https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10308) in GitLab 9.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10308) in GitLab 9.1. To retrieve and import GitHub repositories, you need a [GitHub personal access token](https://github.com/settings/tokens). A username should be passed as the second argument to the Rake task, diff --git a/doc/administration/raketasks/ldap.md b/doc/administration/raketasks/ldap.md index d7a37d1df3a..585d254e41d 100644 --- a/doc/administration/raketasks/ldap.md +++ b/doc/administration/raketasks/ldap.md @@ -44,7 +44,7 @@ waiting for the next scheduled group sync to be run. NOTE: If you'd like to change the frequency at which a group sync is performed, -[adjust the cron schedule](../auth/ldap/index.md#adjusting-ldap-group-sync-schedule) +[adjust the cron schedule](../auth/ldap/index.md#adjust-ldap-group-sync-schedule) instead. **Omnibus Installation** @@ -151,7 +151,8 @@ sudo gitlab-rake gitlab:ldap:rename_provider[old_provider,new_provider] force=ye ## Secrets -GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#using-encrypted-credentials) to read from an encrypted file. The following Rake tasks are provided for updating the contents of the encrypted file. +GitLab can use [LDAP configuration secrets](../auth/ldap/index.md#use-encrypted-credentials) to read from an encrypted file. +The following Rake tasks are provided for updating the contents of the encrypted file. ### Show secret diff --git a/doc/administration/raketasks/praefect.md b/doc/administration/raketasks/praefect.md index 5fe0546999b..d2fd4943c68 100644 --- a/doc/administration/raketasks/praefect.md +++ b/doc/administration/raketasks/praefect.md @@ -7,7 +7,7 @@ type: reference # Praefect Rake tasks **(FREE SELF)** -> [Introduced]( https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28369) in GitLab 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28369) in GitLab 12.10. Rake tasks are available for projects that have been created on Praefect storage. See the [Praefect documentation](../gitaly/praefect.md) for information on configuring Praefect. diff --git a/doc/administration/raketasks/project_import_export.md b/doc/administration/raketasks/project_import_export.md index 80321d75d66..e0ca7bfdeaf 100644 --- a/doc/administration/raketasks/project_import_export.md +++ b/doc/administration/raketasks/project_import_export.md @@ -52,7 +52,7 @@ Note the following: compatible as described in the [Version history](../../user/project/settings/import_export.md#version-history). - The project import option must be enabled: - 1. On the top bar, select **Menu >** **{admin}** **Admin**. + 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**. 1. Expand **Visibility and access controls**. 1. Under **Import sources**, check the "Project export enabled" option. diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md index cee63a6cae5..017565e1b39 100644 --- a/doc/administration/raketasks/storage.md +++ b/doc/administration/raketasks/storage.md @@ -109,7 +109,7 @@ sudo gitlab-rake gitlab:storage:migrate_to_hashed ID_FROM=50 ID_TO=100 To monitor the progress in GitLab: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Monitoring > Background Jobs**. 1. Watch how long the `hashed_storage:hashed_storage_project_migrate` queue will take to finish. After it reaches zero, you can confirm every project diff --git a/doc/administration/redis/replication_and_failover_external.md b/doc/administration/redis/replication_and_failover_external.md index 234b1aa7fb9..c19e42a5f14 100644 --- a/doc/administration/redis/replication_and_failover_external.md +++ b/doc/administration/redis/replication_and_failover_external.md @@ -349,7 +349,7 @@ or a failover promotes a different **Primary** node. ```yaml production: - url: redis://:redi-password-goes-here@gitlab-redis/ + url: redis://:redis-password-goes-here@gitlab-redis/ sentinels: - host: 10.0.0.1 diff --git a/doc/administration/redis/troubleshooting.md b/doc/administration/redis/troubleshooting.md index 0c1046ca22d..6ab3d55e06a 100644 --- a/doc/administration/redis/troubleshooting.md +++ b/doc/administration/redis/troubleshooting.md @@ -73,7 +73,7 @@ there may be something wrong with your configuration files or it can be related to [this issue](https://github.com/redis/redis-rb/issues/531). You must make sure you are defining the same value in `redis['master_name']` -and `redis['master_pasword']` as you defined for your sentinel node. +and `redis['master_password']` as you defined for your sentinel node. The way the Redis connector `redis-rb` works with sentinel is a bit non-intuitive. We try to hide the complexity in omnibus, but it still requires diff --git a/doc/administration/reference_architectures/10k_users.md b/doc/administration/reference_architectures/10k_users.md index f9397e6dbca..0fd597e6a2d 100644 --- a/doc/administration/reference_architectures/10k_users.md +++ b/doc/administration/reference_architectures/10k_users.md @@ -1550,7 +1550,7 @@ To configure the Praefect nodes, on each one: # Configure the Consul agent consul['enable'] = true ## Enable service discovery for Prometheus - consul['monitoring_service_discovery'] = true + consul['monitoring_service_discovery'] = true # START user configuration # Please set the real values as explained in Required Information section @@ -2390,7 +2390,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/1k_users.md b/doc/administration/reference_architectures/1k_users.md index 18e34711953..ea40e150e58 100644 --- a/doc/administration/reference_architectures/1k_users.md +++ b/doc/administration/reference_architectures/1k_users.md @@ -13,7 +13,7 @@ full list of reference architectures, see If you need to serve up to 1,000 users and you don't have strict availability requirements, a single-node solution with [frequent backups](index.md#automated-backups) is appropriate for -many organizations . +many organizations. > - **Supported users (approximate):** 1,000 > - **High Availability:** No. For a highly-available environment, you can diff --git a/doc/administration/reference_architectures/25k_users.md b/doc/administration/reference_architectures/25k_users.md index 65d59422da8..f500434d75b 100644 --- a/doc/administration/reference_architectures/25k_users.md +++ b/doc/administration/reference_architectures/25k_users.md @@ -2402,7 +2402,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/2k_users.md b/doc/administration/reference_architectures/2k_users.md index 0af4dbc8a7f..99dd29c3a83 100644 --- a/doc/administration/reference_architectures/2k_users.md +++ b/doc/administration/reference_architectures/2k_users.md @@ -995,7 +995,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/3k_users.md b/doc/administration/reference_architectures/3k_users.md index f4ae01c7442..da36968f053 100644 --- a/doc/administration/reference_architectures/3k_users.md +++ b/doc/administration/reference_architectures/3k_users.md @@ -2124,7 +2124,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/50k_users.md b/doc/administration/reference_architectures/50k_users.md index b262545b27d..b071b48cbd9 100644 --- a/doc/administration/reference_architectures/50k_users.md +++ b/doc/administration/reference_architectures/50k_users.md @@ -2413,7 +2413,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/5k_users.md b/doc/administration/reference_architectures/5k_users.md index 666d18a66fc..4dfe628039a 100644 --- a/doc/administration/reference_architectures/5k_users.md +++ b/doc/administration/reference_architectures/5k_users.md @@ -2094,7 +2094,7 @@ The following tables and diagram detail the hybrid environment using the same fo as the normal environment above. First are the components that run in Kubernetes. The recommendation at this time is to -use Google Cloud’s Kubernetes Engine (GKE) and associated machine types, but the memory +use Google Cloud's Kubernetes Engine (GKE) and associated machine types, but the memory and CPU requirements should translate to most other providers. We hope to update this in the future with further specific cloud provider details. diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 74d8bf39d03..4d95a61176b 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -139,8 +139,8 @@ to any of the [available reference architectures](#available-reference-architect > - Level of complexity: **Medium** > - Required domain knowledge: PostgreSQL, HAProxy, shared storage, distributed systems -GitLab supports [zero-downtime updates](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates). -Single GitLab nodes can be updated with only a [few minutes of downtime](https://docs.gitlab.com/omnibus/update/README.html#single-node-deployment). +GitLab supports [zero-downtime upgrades](../../update/zero_downtime.md). +Single GitLab nodes can be updated with only a [few minutes of downtime](../../update/zero_downtime.md#single-node-deployment). To avoid this, we recommend to separate GitLab into several application nodes. As long as at least one of each component is online and capable of handling the instance's usage load, your team's productivity will not be interrupted during the update. diff --git a/doc/administration/reference_architectures/troubleshooting.md b/doc/administration/reference_architectures/troubleshooting.md index 61d9dfea2a2..aabf4809b4a 100644 --- a/doc/administration/reference_architectures/troubleshooting.md +++ b/doc/administration/reference_architectures/troubleshooting.md @@ -158,7 +158,7 @@ there may be something wrong with your configuration files or it can be related to [this issue](https://github.com/redis/redis-rb/issues/531). You must make sure you are defining the same value in `redis['master_name']` -and `redis['master_pasword']` as you defined for your sentinel node. +and `redis['master_password']` as you defined for your sentinel node. The way the Redis connector `redis-rb` works with sentinel is a bit non-intuitive. We try to hide the complexity in omnibus, but it still requires diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index ab203bb7993..0591f5b3c40 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -11,7 +11,7 @@ You can use [`git fsck`](https://git-scm.com/docs/git-fsck) to verify the integr committed to a repository. GitLab administrators can trigger this check for a project using the GitLab UI: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Projects**. 1. Select the project to check. 1. In the **Repository check** section, select **Trigger repository check**. @@ -25,7 +25,7 @@ This setting is off by default, because it can cause many false alarms. Instead of checking repositories manually, GitLab can be configured to run the checks periodically: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`). 1. Expand the **Repository maintenance** section. 1. Enable **Enable repository checks**. @@ -50,7 +50,7 @@ disk at: If periodic repository checks cause false alarms, you can clear all repository check states: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository** (`/admin/application_settings/repository`). 1. Expand the **Repository maintenance** section. 1. Select **Clear all repository checks**. diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index f4aed0f6a0f..e7edfb9f338 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -146,7 +146,7 @@ Omnibus stores the repositories in a `repositories` subdirectory of the `git-dat After you [configure](#configure-repository-storage-paths) multiple repository storage paths, you can choose where new repositories are stored: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Repository** and expand the **Repository storage** section. 1. Enter values in the **Storage nodes for new repositories** fields. diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index f55bff1bf34..d2bab9a1e04 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -80,7 +80,7 @@ Administrators can look up a project's hashed path from its name or ID using: To look up a project's hash path in the Admin Area: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Projects** and select the project. The **Gitaly relative path** is displayed there and looks similar to: diff --git a/doc/administration/static_objects_external_storage.md b/doc/administration/static_objects_external_storage.md index 2f19a2e5058..21949388f19 100644 --- a/doc/administration/static_objects_external_storage.md +++ b/doc/administration/static_objects_external_storage.md @@ -16,8 +16,8 @@ storage such as a content delivery network (CDN). To configure external storage for static objects: -1. On the top bar, select **Menu >** **{admin}** **Admin**. -1. In the left sidebar, select **Settings > Repository**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings > Repository**. 1. Expand the **External storage for repository static objects** section. 1. Enter the base URL and an arbitrary token. When you [set up external storage](#set-up-external-storage), use a script that sets these values as `ORIGIN_HOSTNAME` and `STORAGE_TOKEN`. diff --git a/doc/administration/troubleshooting/diagnostics_tools.md b/doc/administration/troubleshooting/diagnostics_tools.md index fe85b5d5803..53d4810b920 100644 --- a/doc/administration/troubleshooting/diagnostics_tools.md +++ b/doc/administration/troubleshooting/diagnostics_tools.md @@ -23,8 +23,3 @@ running on. [strace-parser](https://gitlab.com/wchandler/strace-parser) is a small tool to analyze and summarize raw `strace` data. - -## Pritaly - -[Pritaly](https://gitlab.com/wchandler/pritaly) takes Gitaly logs and colorizes output -or converts the logs to JSON. diff --git a/doc/administration/troubleshooting/elasticsearch.md b/doc/administration/troubleshooting/elasticsearch.md index 79295856da8..cfce3b94554 100644 --- a/doc/administration/troubleshooting/elasticsearch.md +++ b/doc/administration/troubleshooting/elasticsearch.md @@ -196,7 +196,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. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > General**, and then confirm the integration is enabled. 1. Confirm searches use Elasticsearch by accessing the rails console diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index c55efe78216..491db37d9da 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -243,7 +243,7 @@ project.update!(repository_read_only: true) ### Transfer project from one namespace to another ```ruby - p= Project.find_by_full_path('') +p = Project.find_by_full_path('') # To set the owner of the project current_user= p.creator @@ -416,9 +416,9 @@ p.create_wiki ### creates the wiki project on the filesystem ### 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') +p = Project.find_by_full_path('PROJECT PATH') -IssueRebalancingService.new(p.issues.take).execute +Issues::RelativePositionRebalancingService.new(p.root_namespace.all_projects).execute ``` ## Imports / Exports @@ -596,6 +596,17 @@ curl --silent --header "Private-Token: ********************" \ "https://gitlab.example.com/api/v4/users?per_page=100&active" | jq --compact-output '.[] | [.id,.name,.username]' ``` +### Update Daily Billable & Historical users + +```ruby +# Forces recount of historical (max) users +::HistoricalDataWorker.new.perform + +# Forces recount of daily billable users +identifier = Analytics::UsageTrends::Measurement.identifiers[:billable_users] +::Analytics::UsageTrends::CounterJobWorker.new.perform(identifier, User.minimum(:id), User.maximum(:id), Time.zone.now) +``` + ### Block or Delete Users that have no projects or groups ```ruby @@ -999,8 +1010,8 @@ This content has been moved to the [Troubleshooting Sidekiq docs](sidekiq.md). ### Get information about LFS objects and associated project ```ruby -o=LfsObject.find_by(oid: "") -p=Project.find(LfsObjectsProject.find_by_lfs_object_id(o.id).project_id) +o = LfsObject.find_by(oid: "") +p = Project.find(LfsObjectsProject.find_by_lfs_object_id(o.id).project_id) ``` You can then delete these records from the database with: diff --git a/doc/administration/troubleshooting/log_parsing.md b/doc/administration/troubleshooting/log_parsing.md index 0a73c61ae94..c5443c564f4 100644 --- a/doc/administration/troubleshooting/log_parsing.md +++ b/doc/administration/troubleshooting/log_parsing.md @@ -55,6 +55,12 @@ zcat @400000006026b71d1a7af804.s | (head -1; tail -1) | jq '.time' zcat some_json.log.25.gz | (head -1; tail -1) | jq '.time' ``` +#### Get activity for correlation ID across multiple JSON logs in chronological order + +```shell +grep -hR | jq -c -R 'fromjson?' | jq -C -s 'sort_by(.time)' | less -R +``` + ### Parsing `production_json.log` and `api_json.log` #### Find all requests with a 5XX status code diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index 994c194c6db..3df957bacf9 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -116,7 +116,7 @@ References: ERROR: deadlock detected ``` -Three applicable timeouts are identified in the issue [#1](https://gitlab.com/gitlab-org/gitlab/-/issues/30528); our recommended settings are as follows: +Three applicable timeouts are identified in the issue [#30528](https://gitlab.com/gitlab-org/gitlab/-/issues/30528); our recommended settings are as follows: ```ini deadlock_timeout = 5s @@ -124,7 +124,7 @@ statement_timeout = 15s idle_in_transaction_session_timeout = 60s ``` -Quoting from issue [#1](https://gitlab.com/gitlab-org/gitlab/-/issues/30528): +Quoting from issue [#30528](https://gitlab.com/gitlab-org/gitlab/-/issues/30528): > "If a deadlock is hit, and we resolve it through aborting the transaction after a short period, then the retry mechanisms we already have will make the deadlocked piece of work try again, and it's unlikely we'll deadlock multiple times in a row." @@ -146,7 +146,7 @@ PostgresSQL defaults: - `statement_timeout = 0` (never) - `idle_in_transaction_session_timeout = 0` (never) -Comments in issue [#1](https://gitlab.com/gitlab-org/gitlab/-/issues/30528) +Comments in issue [#30528](https://gitlab.com/gitlab-org/gitlab/-/issues/30528) indicate that these should both be set to at least a number of minutes for all Omnibus GitLab installations (so they don't hang indefinitely). However, 15s for statement_timeout is very short, and will only be effective if the diff --git a/doc/administration/troubleshooting/tracing_correlation_id.md b/doc/administration/troubleshooting/tracing_correlation_id.md index 1bb10e72290..3518f52e6f6 100644 --- a/doc/administration/troubleshooting/tracing_correlation_id.md +++ b/doc/administration/troubleshooting/tracing_correlation_id.md @@ -27,7 +27,7 @@ activity with the site that you're visiting. See the links below for network mon documentation for some popular browsers. - [Network Monitor - Firefox Developer Tools](https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor) -- [Inspect Network Activity In Chrome DevTools](https://developer.chrome.com/docs/devtools/network) +- [Inspect Network Activity In Chrome DevTools](https://developer.chrome.com/docs/devtools/network/) - [Safari Web Development Tools](https://developer.apple.com/safari/tools/) - [Microsoft Edge Network panel](https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/) @@ -127,3 +127,11 @@ some sort of log aggregation software like Loki, ELK, Splunk, or others. 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. + +### Viewing the request in the Performance Bar + +You can use the [performance bar](../monitoring/performance/performance_bar.md) to view interesting data including calls made to SQL and Gitaly. + +To view the data, the correlation ID of the request must match the same session as the user +viewing the performance bar. For API requests, this means that you must perform the request +using the session cookie of the signed-in user. diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 949687cfa0a..15ef024647c 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -53,8 +53,8 @@ _The uploads are stored by default in > **Notes:** > -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3867) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17358) in [GitLab Free](https://about.gitlab.com/pricing/) 10.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3867) in GitLab 10.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17358) from GitLab Premium to GitLab Free in 10.7. > - Since version 11.1, we support direct_upload to S3. If you don't want to use the local disk where GitLab is installed to store the diff --git a/doc/administration/whats-new.md b/doc/administration/whats-new.md index d669d05e9f0..d3768907989 100644 --- a/doc/administration/whats-new.md +++ b/doc/administration/whats-new.md @@ -29,7 +29,7 @@ in the first patch release, such as `13.10.1`. You can configure the What's new variant: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > Preferences**, then expand **What's new**. 1. Choose one of the following options: diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 8ef3e882209..1634184a374 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, api --- -# Group and project access requests API +# Group and project access requests API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18583) in GitLab 8.11. diff --git a/doc/api/admin_sidekiq_queues.md b/doc/api/admin_sidekiq_queues.md index d0e310ab548..569dfd4c413 100644 --- a/doc/api/admin_sidekiq_queues.md +++ b/doc/api/admin_sidekiq_queues.md @@ -27,15 +27,16 @@ This API endpoint is only available to administrators. DELETE /admin/sidekiq/queues/:queue_name ``` -| Attribute | Type | Required | Description | -| --------- | -------------- | -------- | ----------- | -| `queue_name` | string | yes | The name of the queue to delete jobs from | -| `user` | string | no | The username of the user who scheduled the jobs | -| `project` | string | no | The full path of the project where the jobs were scheduled from | -| `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`) | +| Attribute | Type | Required | Description | +|---------------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `queue_name` | string | yes | The name of the queue to delete jobs from | +| `user` | string | no | The username of the user who scheduled the jobs | +| `project` | string | no | The full path of the project where the jobs were scheduled from | +| `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`) | +| `worker_class` | string | no | The class of the background job worker (for example: `PostReceive` or `MergeWorker`) | 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 aae76697841..8706b1e7e76 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -15,7 +15,7 @@ Available resources for the [GitLab REST API](index.md) can be grouped in the fo See also: - [V3 to V4](v3_to_v4.md). -- Adding [deploy keys for multiple projects](deploy_keys.md#adding-deploy-keys-to-multiple-projects). +- Adding [deploy keys for multiple projects](deploy_keys.md#add-deploy-keys-to-multiple-projects). - [API Resources for various templates](#templates-api-resources). ## Project resources @@ -129,7 +129,7 @@ The following API resources are available outside of project and group contexts | Resource | Available endpoints | |:---------------------------------------------------|:------------------------------------------------------------------------| -| [Instance-level CI/CD variables](instance_level_ci_variables.md) | `/admin/ci/variables` | +| [Instance-level CI/CD variables](instance_level_ci_variables.md) **(FREE SELF)** | `/admin/ci/variables` | | [Sidekiq queues administration](admin_sidekiq_queues.md) **(FREE SELF)** | `/admin/sidekiq/queues/:queue_name` | | [Appearance](appearance.md) **(FREE SELF)** | `/application/appearance` | | [Applications](applications.md) | `/applications` | @@ -145,7 +145,7 @@ The following API resources are available outside of project and group contexts | [Group Activity Analytics](group_activity_analytics.md) | `/analytics/group_activity/{issues_count | merge_requests_count | new_members_count }` | | [Group repository storage moves](group_repository_storage_moves.md) **(PREMIUM SELF)** | `/group_repository_storage_moves` | | [Import repository from GitHub](import.md) | `/import/github` | -| [Instance clusters](instance_clusters.md) | `/admin/clusters` | +| [Instance clusters](instance_clusters.md) **(FREE SELF)** | `/admin/clusters` | | [Issues](issues.md) | `/issues` (also available for groups and projects) | | [Issues Statistics](issues_statistics.md) | `/issues_statistics` (also available for groups and projects) | | [Jobs](jobs.md) | `/job` | diff --git a/doc/api/applications.md b/doc/api/applications.md index 7047dccea88..2b5eff68010 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Applications API +# Applications API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8160) in GitLab 10.5. diff --git a/doc/api/avatar.md b/doc/api/avatar.md index baa670f3e93..200d7524b7f 100644 --- a/doc/api/avatar.md +++ b/doc/api/avatar.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Avatar API +# Avatar API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19121) in GitLab 11.0. diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index dc3dc9fcaca..61f84dfb812 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -10,7 +10,7 @@ An [awarded emoji](../user/award_emojis.md) tells a thousand words. We call GitLab objects on which you can award an emoji "awardables". You can award emojis on the following: -- [Epics](../user/group/epics/index.md) ([API](epics.md)). +- [Epics](../user/group/epics/index.md) ([API](epics.md)). **(PREMIUM)** - [Issues](../user/project/issues/index.md) ([API](issues.md)). - [Merge requests](../user/project/merge_requests/index.md) ([API](merge_requests.md)). - [Snippets](../user/snippets.md) ([API](snippets.md)). diff --git a/doc/api/boards.md b/doc/api/boards.md index 3288aefb1cf..ab9bd4ea3f1 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -427,7 +427,7 @@ POST /projects/:id/boards/:board_id/lists NOTE: Label, assignee and milestone arguments are mutually exclusive, that is, only one of them are accepted in a request. -Check the [Issue Board documentation](../user/project/issue_board.md) +Check the [issue board documentation](../user/project/issue_board.md) for more information regarding the required license for each list type. ```shell diff --git a/doc/api/branches.md b/doc/api/branches.md index 15d1b6c2a18..7b9354f3264 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -47,7 +47,7 @@ Example response: "developers_can_push": false, "developers_can_merge": false, "can_push": true, - "web_url": "http://gitlab.example.com/my-group/my-project/-/tree/master", + "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/master", "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -103,7 +103,7 @@ Example response: "developers_can_push": false, "developers_can_merge": false, "can_push": true, - "web_url": "http://gitlab.example.com/my-group/my-project/-/tree/master", + "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/master", "commit": { "author_email": "john@example.com", "author_name": "John Smith", @@ -180,7 +180,7 @@ Example response: "developers_can_push": false, "developers_can_merge": false, "can_push": true, - "web_url": "http://gitlab.example.com/my-group/my-project/-/tree/newbranch" + "web_url": "https://gitlab.example.com/my-group/my-project/-/tree/newbranch" } ``` diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index b98373b5a58..5aca0667f31 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -13,7 +13,7 @@ As of GitLab 12.8, GET requests do not require authentication. All other broadca - Guests result in `401 Unauthorized`. - Regular users result in `403 Forbidden`. -## Get all broadcast messages +## Get all broadcast messages **(FREE)** List all broadcast messages. @@ -46,7 +46,7 @@ Example response: ] ``` -## Get a specific broadcast message +## Get a specific broadcast message **(FREE)** Get a specific broadcast message. diff --git a/doc/api/bulk_imports.md b/doc/api/bulk_imports.md index 2325f25e789..2b71c83b224 100644 --- a/doc/api/bulk_imports.md +++ b/doc/api/bulk_imports.md @@ -4,7 +4,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GitLab Migrations (Bulk Imports) API +# GitLab Migrations (Bulk Imports) API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/64335) in GitLab 14.1. diff --git a/doc/api/commits.md b/doc/api/commits.md index e164532e0eb..e91da23596f 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -289,11 +289,11 @@ Example response: ``` -## Cherry pick a commit +## Cherry-pick a commit > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8047) in GitLab 8.15. -Cherry picks a commit to a given branch. +Cherry-picks a commit to a given branch. ```plaintext POST /projects/:id/repository/commits/:sha/cherry_pick @@ -381,7 +381,7 @@ Parameters: | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | | `sha` | string | yes | Commit SHA to revert | | `branch` | string | yes | Target branch name | -| `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced in GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) | +| `dry_run` | boolean | no | Does not commit any changes. Default is false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/231032) in GitLab 13.3 | ```shell curl --request POST --header "PRIVATE-TOKEN: " --form "branch=master" \ diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 12bdeebca1d..2885cc7d803 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Container Registry API +# Container Registry API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/55978) in GitLab 11.8. > - The use of `CI_JOB_TOKEN` scoped to the current project was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49750) in GitLab 13.12. @@ -32,6 +32,8 @@ Feature.disable(:ci_job_token_scope) ## Change the visibility of the Container Registry +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18792) in GitLab 14.2. + This controls who can view the Container Registry. ```plaintext diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md index 9908c58de35..94f924c051d 100644 --- a/doc/api/custom_attributes.md +++ b/doc/api/custom_attributes.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Custom Attributes API +# Custom Attributes API **(FREE SELF)** Every API call to custom attributes must be authenticated as administrator. diff --git a/doc/api/dependency_proxy.md b/doc/api/dependency_proxy.md index e9ddc1e9df9..535c6607cad 100644 --- a/doc/api/dependency_proxy.md +++ b/doc/api/dependency_proxy.md @@ -4,19 +4,16 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Dependency Proxy API +# Dependency Proxy API **(FREE)** ## Purge the dependency proxy for a group > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11631) in GitLab 12.10. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) to [GitLab Free](https://about.gitlab.com/pricing/) in GitLab 13.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/273655) from GitLab Premium to GitLab Free in 13.6. Deletes the cached manifests and blobs for a group. This endpoint requires the [Owner role](../user/permissions.md) for the group. -WARNING: -[A bug exists](https://gitlab.com/gitlab-org/gitlab/-/issues/277161) for this API. - ```plaintext DELETE /groups/:id/dependency_proxy/cache ``` diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 3d6d680e3e4..bb719b5bc79 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -4,11 +4,12 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploy keys API +# Deploy keys API **(FREE)** -## List all deploy keys +## List all deploy keys **(FREE SELF)** -Get a list of all deploy keys across all projects of the GitLab instance. This endpoint requires administrator access and is not available on GitLab.com. +Get a list of all deploy keys across all projects of the GitLab instance. This +endpoint requires an administrator role and is not available on GitLab.com. ```plaintext GET /deploy_keys @@ -74,7 +75,7 @@ Example response: ] ``` -## Single deploy key +## Get a single deploy key Get a single key. @@ -213,10 +214,10 @@ Example response: } ``` -## Adding deploy keys to multiple projects +## Add deploy keys to multiple projects -If you want to easily add the same deploy key to multiple projects in the same -group, this can be achieved quite easily with the API. +If you want to add the same deploy key to multiple projects in the same +group, this can be achieved with the API. First, find the ID of the projects you're interested in, by either listing all projects: diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index 6ed8f76583f..3de7ff4ac44 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -4,9 +4,9 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Deploy Tokens API +# Deploy Tokens API **(FREE)** -## List all deploy tokens +## List all deploy tokens **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9. diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 3ed431cf63d..5f710271d60 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Deployments API +# Deployments API **(FREE)** ## List project deployments diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 1c22f261e57..18b74e1450f 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -15,7 +15,9 @@ Discussions are a set of related notes on: - Merge requests - Commits -This includes system notes, which are notes about changes to the object (for example, when a milestone changes, a corresponding system note is added). Label notes are not part of this API, but recorded as separate events in [resource label events](resource_label_events.md). +This includes system notes, which are notes about changes to the object (for example, +when a milestone changes, a corresponding system note is added). Label notes are +not part of this API, but recorded as separate events in [resource label events](resource_label_events.md). ## Discussions pagination @@ -118,7 +120,8 @@ GET /projects/:id/issues/:issue_iid/discussions ``` ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions" +curl --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions" ``` ### Get single issue discussion item @@ -138,7 +141,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7" +curl --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/" ``` ### Create new issue thread @@ -159,7 +163,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions?body=comment" ``` ### Add note to existing issue thread @@ -185,7 +190,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions//notes?body=comment" ``` ### Modify existing issue thread note @@ -207,7 +213,8 @@ Parameters: | `body` | string | yes | The content of the note/reply | ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions//notes/1108?body=comment" ``` ### Delete an issue thread note @@ -228,7 +235,8 @@ Parameters: | `note_id` | integer | yes | The ID of a discussion note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/issues/11/discussions/636" ``` ## Snippets @@ -326,7 +334,8 @@ GET /projects/:id/snippets/:snippet_id/discussions ``` ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions" +curl --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions" ``` ### Get single snippet discussion item @@ -346,7 +355,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/" ``` ### Create new snippet thread @@ -368,7 +378,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions?body=comment" ``` ### Add note to existing snippet thread @@ -391,7 +402,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions//notes?body=comment" ``` ### Modify existing snippet thread note @@ -413,7 +425,8 @@ Parameters: | `body` | string | yes | The content of the note/reply | ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions//notes/1108?body=comment" ``` ### Delete a snippet thread note @@ -434,7 +447,8 @@ Parameters: | `note_id` | integer | yes | The ID of a discussion note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/snippets/11/discussions/636" ``` ## Epics **(ULTIMATE)** @@ -533,7 +547,8 @@ GET /groups/:id/epics/:epic_id/discussions ``` ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions" +curl --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions" ``` ### Get single epic discussion item @@ -553,7 +568,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/" ``` ### Create new epic thread @@ -575,7 +591,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions?body=comment" ``` ### Add note to existing epic thread @@ -599,7 +616,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions//notes?body=comment" ``` ### Modify existing epic thread note @@ -621,7 +639,8 @@ Parameters: | `body` | string | yes | The content of note/reply | ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions//notes/1108?body=comment" ``` ### Delete an epic thread note @@ -642,7 +661,8 @@ Parameters: | `note_id` | integer | yes | The ID of a thread note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/groups/5/epics/11/discussions/636" ``` ## Merge requests @@ -805,7 +825,8 @@ Diff comments also contain position: ``` ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions" +curl --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions" ``` ### Get single merge request discussion item @@ -825,7 +846,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7 +curl --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/" ``` ### Create new merge request thread @@ -866,57 +888,67 @@ Parameters for all comments: #### Create a new thread on the overview page ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions?body=comment" ``` #### Create a new thread in the merge request diff -- Both `position[old_path]` and `position[new_path]` are required and must refer to the file path before and after the change. -- To create a thread on an added line (highlighted in green in the merge request diff), use `position[new_line]` and don't include `position[old_line]`. -- To create a thread on a removed line (highlighted in red in the merge request diff), use `position[old_line]` and don't include `position[new_line]`. -- To create a thread on an unchanged line, include both `position[new_line]` and `position[old_line]` for the line. These positions might not be the same if earlier changes in the file changed the line number. This is a bug that we plan to fix in [GraphQL `createDiffNote` forces clients to compute redundant information (#325161)](https://gitlab.com/gitlab-org/gitlab/-/issues/325161). -- If you specify incorrect `base`/`head`/`start` `SHA` parameters, you might run into the following bug: [Merge request comments receive "download" link instead of inline code (#296829)](https://gitlab.com/gitlab-org/gitlab/-/issues/296829). +- Both `position[old_path]` and `position[new_path]` are required and must refer + to the file path before and after the change. +- To create a thread on an added line (highlighted in green in the merge request diff), + use `position[new_line]` and don't include `position[old_line]`. +- To create a thread on a removed line (highlighted in red in the merge request diff), + use `position[old_line]` and don't include `position[new_line]`. +- To create a thread on an unchanged line, include both `position[new_line]` and + `position[old_line]` for the line. These positions might not be the same if earlier + changes in the file changed the line number. This is a bug that we plan to fix in + [GraphQL `createDiffNote` forces clients to compute redundant information (#325161)](https://gitlab.com/gitlab-org/gitlab/-/issues/325161). +- If you specify incorrect `base`/`head`/`start` `SHA` parameters, you might run + into the following bug: + [Merge request comments receive "download" link instead of inline code (#296829)](https://gitlab.com/gitlab-org/gitlab/-/issues/296829). To create a new thread: 1. [Get the latest merge request version](merge_requests.md#get-mr-diff-versions): - ```shell - curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/versions" - ```` + ```shell + curl --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/versions" + ``` 1. Note the details of the latest version, which is listed first in the response array. - ```json - [ - { - "id": 164560414, - "head_commit_sha": "f9ce7e16e56c162edbc9e480108041cf6b0291fe", - "base_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80", - "start_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80", - "created_at": "2021-03-30T09:18:27.351Z", - "merge_request_id": 93958054, - "state": "collected", - "real_size": "2" - }, - "previous versions are here" - ] - ``` + ```json + [ + { + "id": 164560414, + "head_commit_sha": "f9ce7e16e56c162edbc9e480108041cf6b0291fe", + "base_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80", + "start_commit_sha": "5e6dffa282c5129aa67cd227a0429be21bfdaf80", + "created_at": "2021-03-30T09:18:27.351Z", + "merge_request_id": 93958054, + "state": "collected", + "real_size": "2" + }, + "previous versions are here" + ] + ``` 1. Create a new diff thread. This example creates a thread on an added line: - ```shell - curl --request POST --header "PRIVATE-TOKEN: "\ - --form 'position[position_type]=text'\ - --form 'position[base_sha]='\ - --form 'position[head_sha]='\ - --form 'position[start_sha]='\ - --form 'position[new_path]=file.js'\ - --form 'position[old_path]=file.js'\ - --form 'position[new_line]=18'\ - --form 'body=test comment body'\ - "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions" - ``` + ```shell + curl --request POST --header "PRIVATE-TOKEN: "\ + --form 'position[position_type]=text'\ + --form 'position[base_sha]='\ + --form 'position[head_sha]='\ + --form 'position[start_sha]='\ + --form 'position[new_path]=file.js'\ + --form 'position[old_path]=file.js'\ + --form 'position[new_line]=18'\ + --form 'body=test comment body'\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions" + ``` #### Parameters for multiline comments @@ -933,14 +965,31 @@ Parameters for multiline comments only: #### Line code -A line code is of the form `__`: +A line code is of the form `__`, like this: `adc83b19e793491b1c6ea0fd8b46cd9f32e292fc_5_5` - `` is the SHA1 hash of the filename. - `` is the line number before the change. - `` is the line number after the change. -For example, when commenting on an added line number 5, the line code -looks like `adc83b19e793491b1c6ea0fd8b46cd9f32e292fc_5_5`. +For example, if a commit (``) deletes line 463 in the README, you can comment +on the deletion by referencing line 463 in the *old* file: + +```shell +curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]"\ + --form "note=Very clever to remove this unnecessary line!"\ + --form "path=README" --form "line=463" --form "line_type=old"\ + "https://gitlab.com/api/v4/projects/47/repository/commits//comments" +``` + +If a commit (``) adds line 157 to `hello.rb`, you can comment on the +addition by referencing line 157 in the *new* file: + +```shell +curl --request POST --header "PRIVATE-TOKEN: [ACCESS_TOKEN]"\ + --form "note=This is brilliant!" --form "path=hello.rb"\ + --form "line=157" --form "line_type=old"\ + "https://gitlab.com/api/v4/projects/47/repository/commits//comments" +``` ### Resolve a merge request thread @@ -960,7 +1009,8 @@ Parameters: | `resolved` | boolean | yes | Resolve/unresolve the discussion | ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true" +curl --request PUT --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/?resolved=true" ``` ### Add note to existing merge request thread @@ -984,7 +1034,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions//notes?body=comment" ``` ### Modify an existing merge request thread note @@ -1007,13 +1058,15 @@ Parameters: | `resolved` | boolean | no | Resolve/unresolve the note (exactly one of `body` or `resolved` must be set | ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions//notes/1108?body=comment" ``` Resolving a note: ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true" +curl --request PUT --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions//notes/1108?resolved=true" ``` ### Delete a merge request thread note @@ -1034,7 +1087,8 @@ Parameters: | `note_id` | integer | yes | The ID of a thread note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/636" ``` ## Commits @@ -1177,7 +1231,8 @@ Diff comments contain also position: ``` ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions" +curl --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions" ``` ### Get single commit discussion item @@ -1197,7 +1252,8 @@ Parameters: | `discussion_id` | integer | yes | The ID of a discussion item | ```shell -curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7" +curl --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/" ``` ### Create new commit thread @@ -1232,7 +1288,8 @@ Parameters: | `position[y]` | integer | no | Y coordinate (for `image` diff notes) | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment" +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions?body=comment" ``` The rules for creating the API request are the same as when @@ -1259,7 +1316,8 @@ Parameters: | `created_at` | string | no | Date time string, ISO 8601 formatted, such `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) | ```shell -curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes?body=comment +curl --request POST --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions//notes?body=comment ``` ### Modify an existing commit thread note @@ -1281,13 +1339,15 @@ Parameters: | `body` | string | no | The content of a note | ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?body=comment" +curl --request PUT --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions//notes/1108?body=comment" ``` Resolving a note: ```shell -curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7/notes/1108?resolved=true" +curl --request PUT --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions//notes/1108?resolved=true" ``` ### Delete a commit thread note @@ -1308,5 +1368,6 @@ Parameters: | `note_id` | integer | yes | The ID of a thread note | ```shell -curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636" +curl --request DELETE --header "PRIVATE-TOKEN: "\ + "https://gitlab.example.com/api/v4/projects/5/commits/11/discussions/636" ``` diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 38f1f50839e..8c82446db2e 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -7,7 +7,7 @@ type: reference, api # DevOps Research and Assessment (DORA) key metrics API **(ULTIMATE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab 13.10. > - The legacy key/value pair `{ "" => "" }` was removed from the payload in GitLab 14.0. All methods require [reporter permissions and above](../../user/permissions.md). @@ -52,7 +52,7 @@ Example response: ## Get group-level DORA metrics -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab 13.10. Get group-level DORA metrics. diff --git a/doc/api/dora4_project_analytics.md b/doc/api/dora4_project_analytics.md index efea9723ac4..5a6e1576a3d 100644 --- a/doc/api/dora4_project_analytics.md +++ b/doc/api/dora4_project_analytics.md @@ -7,7 +7,7 @@ type: reference, api # DORA4 Analytics Project API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/279039) in GitLab 13.7. WARNING: These endpoints are deprecated and will be removed in GitLab 14.0. Use the [DORA metrics API](dora/metrics.md) instead. diff --git a/doc/api/environments.md b/doc/api/environments.md index aa3697c54ac..5187ac7c1b2 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Environments API +# Environments API **(FREE)** ## List environments @@ -194,7 +194,7 @@ PUT /projects/:id/environments/:environments_id | --------------- | ------- | --------------------------------- | ------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `environment_id` | integer | yes | The ID of the environment | -| `name` | string | no | The new name of the environment | +| `name` | string | no | [Deprecated and will be removed in GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338897) | | `external_url` | string | no | The new `external_url` | ```shell diff --git a/doc/api/epic_links.md b/doc/api/epic_links.md index 5d8a92d0263..d87b44f43a7 100644 --- a/doc/api/epic_links.md +++ b/doc/api/epic_links.md @@ -15,7 +15,7 @@ Every API call to `epic_links` must be authenticated. If a user is not a member of a private group, a `GET` request on that group results in a `404` status code. -Multi-level Epics are available only in GitLab [Ultimate](https://about.gitlab.com/pricing/). +Multi-level Epics are available only in [GitLab Ultimate](https://about.gitlab.com/pricing/). If the Multi-level Epics feature is not available, a `403` status code is returned. ## List epics related to a given epic diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 0fbb30ef364..1abe5522840 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -51,7 +51,7 @@ PATCH /projects/:id/error_tracking/settings | ------------ | ------- | -------- | --------------------- | | `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `active` | boolean | yes | Pass `true` to enable the already configured error tracking settings or `false` to disable it. | -| `integrated` | boolean | no | Pass `true` to enable the integrated error tracking backend. Available in [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68260) and later. | +| `integrated` | boolean | no | Pass `true` to enable the integrated error tracking backend. [Available in](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68260) GitLab 14.2 and later. | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/1/error_tracking/settings?active=true" @@ -68,3 +68,87 @@ Example response: "integrated": false } ``` + +## Error Tracking client keys + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68384) in GitLab 14.3. + +For [integrated error tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) feature that is behind a disabled feature flag. Only for project maintainers. + +### List project client keys + +```plaintext +GET /projects/:id/error_tracking/client_keys +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | + +```shell +curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/error_tracking/client_keys" +``` + +Example response: + +```json +[ + { + "id": 1, + "active": true, + "public_key": "glet_aa77551d849c083f76d0bc545ed053a3", + "sentry_dsn": "https://glet_aa77551d849c083f76d0bc545ed053a3@gitlab.example.com/api/v4/error_tracking/collector/5" + }, + { + "id": 3, + "active": true, + "public_key": "glet_0ff98b1d849c083f76d0bc545ed053a3", + "sentry_dsn": "https://glet_0ff98b1d849c083f76d0bc545ed053a3@gitlab.example.com/api/v4/error_tracking/collector/5" + } +] +``` + +### Create a client key + +Creates a new client key for a project. The public key attribute is generated automatically. + +```plaintext +POST /projects/:id/error_tracking/client_keys +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | + +```shell +curl --request POST --header "PRIVATE-TOKEN: " --header "Content-Type: application/json" \ + "https://gitlab.example.com/api/v4/projects/5/error_tracking/client_keys" +``` + +Example response: + +```json +{ + "id": 3, + "active": true, + "public_key": "glet_0ff98b1d849c083f76d0bc545ed053a3", + "sentry_dsn": "https://glet_0ff98b1d849c083f76d0bc545ed053a3@gitlab.example.com/api/v4/error_tracking/collector/5" +} +``` + +### Delete a client key + +Removes a client key from the project. + +```plaintext +DELETE /projects/:id/error_tracking/client_keys/:key_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `key_id` | integer | yes | The ID of the client key. | + +```shell +curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/error_tracking/client_keys/13" +``` diff --git a/doc/api/events.md b/doc/api/events.md index 3fbbfa62e66..8800e7f7f9b 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -4,7 +4,7 @@ group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Events API +# Events API **(FREE)** ## Filter parameters @@ -15,7 +15,7 @@ Available types for the `action` parameter, and the resources that might be affe - `approved` - Merge request - `closed` - - Epic + - Epic **(PREMIUM)** - Issue - Merge request - Milestone @@ -28,7 +28,7 @@ Available types for the `action` parameter, and the resources that might be affe - Snippet - `created` - Design - - Epic + - Epic **(PREMIUM)** - Issue - Merge request - Milestone @@ -49,7 +49,7 @@ Available types for the `action` parameter, and the resources that might be affe - `pushed` commits to (or deleted commits from) a repository, individually or in bulk. - Project - `reopened` - - Epic + - Epic **(PREMIUM)** - Issue - Merge request - Milestone diff --git a/doc/api/feature_flag_specs.md b/doc/api/feature_flag_specs.md index 33e454d50c4..f2853efc5f2 100644 --- a/doc/api/feature_flag_specs.md +++ b/doc/api/feature_flag_specs.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Feature Flag Specs API **(PREMIUM)** -> [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 12.5. This API was removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369). Please use [the new API](feature_flags.md) instead. diff --git a/doc/api/features.md b/doc/api/features.md index 87bd565e2bd..30efacb1d00 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Features flags API +# Feature flags API **(FREE SELF)** This API is for managing Flipper-based [feature flags used in development of GitLab](../development/feature_flags/index.md). diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index a562423b2af..6ca69d047da 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts, howto --- -# Freeze Periods API +# Freeze Periods API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29382) in GitLab 13.0. diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index 42cf40d62b8..d9b23485fd5 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -393,6 +393,18 @@ Example response: "package_files_verification_failed_count": null, "package_files_synced_in_percentage": "0.00%", "package_files_verified_in_percentage": "0.00%", + "pages_deployments_count": 5, + "pages_deployments_checksum_total_count": 5, + "pages_deployments_checksummed_count": 5, + "pages_deployments_checksum_failed_count": 0, + "pages_deployments_synced_count": null, + "pages_deployments_failed_count": null, + "pages_deployments_registry_count": null, + "pages_deployments_verification_total_count": null, + "pages_deployments_verified_count": null, + "pages_deployments_verification_failed_count": null, + "pages_deployments_synced_in_percentage": "0.00%", + "pages_deployments_verified_in_percentage": "0.00%", "terraform_state_versions_count": 5, "terraform_state_versions_checksum_total_count": 5, "terraform_state_versions_checksummed_count": 5, @@ -441,6 +453,11 @@ Example response: "pipeline_artifacts_verification_failed_count": null, "pipeline_artifacts_synced_in_percentage": "0.00%", "pipeline_artifacts_verified_in_percentage": "0.00%", + "uploads_count": 5, + "uploads_synced_count": null, + "uploads_failed_count": 0, + "uploads_registry_count": null, + "uploads_synced_in_percentage": "0.00%", }, { "geo_node_id": 2, @@ -583,6 +600,11 @@ Example response: "pipeline_artifacts_verification_failed_count": 0, "pipeline_artifacts_synced_in_percentage": "100.00%", "pipeline_artifacts_verified_in_percentage": "100.00%", + "uploads_count": 5, + "uploads_synced_count": null, + "uploads_failed_count": 0, + "uploads_registry_count": null, + "uploads_synced_in_percentage": "0.00%", } ] ``` @@ -722,6 +744,11 @@ Example response: "pipeline_artifacts_verification_failed_count": 0, "pipeline_artifacts_synced_in_percentage": "100.00%", "pipeline_artifacts_verified_in_percentage": "100.00%", + "uploads_count": 5, + "uploads_synced_count": null, + "uploads_failed_count": 0, + "uploads_registry_count": null, + "uploads_synced_in_percentage": "0.00%", } ``` diff --git a/doc/api/graphql/audit_report.md b/doc/api/graphql/audit_report.md index ba9967f85f2..76f3da2d6ea 100644 --- a/doc/api/graphql/audit_report.md +++ b/doc/api/graphql/audit_report.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Set up an Audit Report with GraphQL +# Set up an Audit Report with GraphQL **(FREE)** This page describes how you can use the GraphiQL explorer to set up an audit report for a specific subset of users. diff --git a/doc/api/graphql/custom_emoji.md b/doc/api/graphql/custom_emoji.md index cb5c0275e08..7307abc0568 100644 --- a/doc/api/graphql/custom_emoji.md +++ b/doc/api/graphql/custom_emoji.md @@ -4,7 +4,7 @@ group: Project Management info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Use custom emojis with GraphQL **(FREE SELF)** +# Use custom emojis with GraphQL **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37911) in GitLab 13.6 > - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. @@ -93,7 +93,7 @@ For more information on: ## Enable or disable custom emoji API **(FREE SELF)** -Custom emoji is under development and but ready for production use. It is +Custom emoji is under development but ready for production use. It is deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) can enable it. diff --git a/doc/api/graphql/index.md b/doc/api/graphql/index.md index e77e6102594..3523276bdf5 100644 --- a/doc/api/graphql/index.md +++ b/doc/api/graphql/index.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# GraphQL API +# GraphQL API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19008) in GitLab 11.0 (enabled by feature flag `graphql`). > - [Always enabled](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30444) in GitLab 12.1. diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 54709f56eb8..c4e73f9c058 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -1,6 +1,6 @@ --- -stage: Plan -group: Project Management +stage: Ecosystem +group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- @@ -56,7 +56,7 @@ Returns [`CiConfig`](#ciconfig). ### `Query.ciMinutesUsage` -The monthly CI minutes usage data for the current user. +Monthly CI minutes usage data for the current user. Returns [`CiMinutesNamespaceMonthlyUsageConnection`](#ciminutesnamespacemonthlyusageconnection). @@ -74,7 +74,7 @@ Returns [`ContainerRepositoryDetails`](#containerrepositorydetails). | Name | Type | Description | | ---- | ---- | ----------- | -| `id` | [`ContainerRepositoryID!`](#containerrepositoryid) | The global ID of the container repository. | +| `id` | [`ContainerRepositoryID!`](#containerrepositoryid) | Global ID of the container repository. | ### `Query.currentLicense` @@ -132,7 +132,7 @@ Returns [`GeoNode`](#geonode). | Name | Type | Description | | ---- | ---- | ----------- | -| `name` | [`String`](#string) | The name of the Geo node. Defaults to the current Geo node name. | +| `name` | [`String`](#string) | Name of the Geo node. Defaults to the current Geo node name. | ### `Query.group` @@ -185,7 +185,7 @@ Returns [`Issue`](#issue). | Name | Type | Description | | ---- | ---- | ----------- | -| `id` | [`IssueID!`](#issueid) | The global ID of the issue. | +| `id` | [`IssueID!`](#issueid) | Global ID of the issue. | ### `Query.iteration` @@ -219,7 +219,7 @@ Returns [`MergeRequest`](#mergerequest). | Name | Type | Description | | ---- | ---- | ----------- | -| `id` | [`MergeRequestID!`](#mergerequestid) | The global ID of the merge request. | +| `id` | [`MergeRequestID!`](#mergerequestid) | Global ID of the merge request. | ### `Query.metadata` @@ -261,7 +261,7 @@ Returns [`PackageDetailsType`](#packagedetailstype). | Name | Type | Description | | ---- | ---- | ----------- | -| `id` | [`PackagesPackageID!`](#packagespackageid) | The global ID of the package. | +| `id` | [`PackagesPackageID!`](#packagespackageid) | Global ID of the package. | ### `Query.project` @@ -304,7 +304,7 @@ Returns [`QueryComplexity`](#querycomplexity). ### `Query.runner` -Find a runner. Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. +Find a runner. Returns [`CiRunner`](#cirunner). @@ -341,7 +341,7 @@ Returns [`RunnerSetup`](#runnersetup). ### `Query.runners` -Find runners visible to the current user. Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. +Find runners visible to the current user. Returns [`CiRunnerConnection`](#cirunnerconnection). @@ -373,11 +373,11 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `authorId` | [`UserID`](#userid) | The ID of an author. | +| `authorId` | [`UserID`](#userid) | ID of an author. | | `explore` | [`Boolean`](#boolean) | Explore personal snippets. | | `ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| `projectId` | [`ProjectID`](#projectid) | The ID of a project. | -| `type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| `projectId` | [`ProjectID`](#projectid) | ID of a project. | +| `type` | [`TypeEnum`](#typeenum) | Type of snippet. | | `visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ### `Query.timelogs` @@ -504,7 +504,7 @@ Returns [`Vulnerability`](#vulnerability). | Name | Type | Description | | ---- | ---- | ----------- | -| `id` | [`VulnerabilityID!`](#vulnerabilityid) | The Global ID of the Vulnerability. | +| `id` | [`VulnerabilityID!`](#vulnerabilityid) | Global ID of the Vulnerability. | ## `Mutation` type @@ -563,6 +563,7 @@ Input type: `AdminSidekiqQueuesDeleteJobsInput` | `rootNamespace` | [`String`](#string) | Delete jobs matching root_namespace in the context metadata. | | `subscriptionPlan` | [`String`](#string) | Delete jobs matching subscription_plan in the context metadata. | | `user` | [`String`](#string) | Delete jobs matching user in the context metadata. | +| `workerClass` | [`String`](#string) | Delete jobs with the given worker class. | #### Fields @@ -631,7 +632,7 @@ Input type: `ApiFuzzingCiConfigurationCreateInput` | `authUsername` | [`String`](#string) | CI variable containing the username for authenticating with the target API. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `projectPath` | [`ID!`](#id) | Full path of the project. | -| `scanMode` | [`ApiFuzzingScanMode!`](#apifuzzingscanmode) | The mode for API fuzzing scans. | +| `scanMode` | [`ApiFuzzingScanMode!`](#apifuzzingscanmode) | Mode for API fuzzing scans. | | `scanProfile` | [`String`](#string) | Name of a default profile to use for scanning. Ex: Quick-10. | | `target` | [`String!`](#string) | URL for the target of API fuzzing scans. | @@ -642,7 +643,7 @@ Input type: `ApiFuzzingCiConfigurationCreateInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `configurationYaml` | [`String`](#string) | A YAML snippet that can be inserted into the project's `.gitlab-ci.yml` to set up API fuzzing scans. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `gitlabCiYamlEditPath` | [`String`](#string) | The location at which the project's `.gitlab-ci.yml` file can be edited in the browser. | +| `gitlabCiYamlEditPath` | [`String`](#string) | Location at which the project's `.gitlab-ci.yml` file can be edited in the browser. | ### `Mutation.awardEmojiAdd` @@ -654,7 +655,7 @@ Input type: `AwardEmojiAddInput` | ---- | ---- | ----------- | | `awardableId` | [`AwardableID!`](#awardableid) | Global ID of the awardable resource. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `name` | [`String!`](#string) | The emoji name. | +| `name` | [`String!`](#string) | Emoji name. | #### Fields @@ -674,7 +675,7 @@ Input type: `AwardEmojiRemoveInput` | ---- | ---- | ----------- | | `awardableId` | [`AwardableID!`](#awardableid) | Global ID of the awardable resource. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `name` | [`String!`](#string) | The emoji name. | +| `name` | [`String!`](#string) | Emoji name. | #### Fields @@ -694,7 +695,7 @@ Input type: `AwardEmojiToggleInput` | ---- | ---- | ----------- | | `awardableId` | [`AwardableID!`](#awardableid) | Global ID of the awardable resource. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `name` | [`String!`](#string) | The emoji name. | +| `name` | [`String!`](#string) | Emoji name. | #### Fields @@ -760,10 +761,10 @@ Input type: `BoardListUpdateLimitMetricsInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `limitMetric` | [`ListLimitMetric`](#listlimitmetric) | The new limit metric type for the list. | -| `listId` | [`ListID!`](#listid) | The global ID of the list. | -| `maxIssueCount` | [`Int`](#int) | The new maximum issue count limit. | -| `maxIssueWeight` | [`Int`](#int) | The new maximum issue weight limit. | +| `limitMetric` | [`ListLimitMetric`](#listlimitmetric) | New limit metric type for the list. | +| `listId` | [`ListID!`](#listid) | Global ID of the list. | +| `maxIssueCount` | [`Int`](#int) | New maximum issue count limit. | +| `maxIssueWeight` | [`Int`](#int) | New maximum issue weight limit. | #### Fields @@ -771,7 +772,7 @@ Input type: `BoardListUpdateLimitMetricsInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `list` | [`BoardList`](#boardlist) | The updated list. | +| `list` | [`BoardList`](#boardlist) | Updated list. | ### `Mutation.bulkEnableDevopsAdoptionNamespaces` @@ -1074,6 +1075,7 @@ Input type: `CreateBoardInput` | `groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | | `hideBacklogList` | [`Boolean`](#boolean) | Whether or not backlog list is hidden. | | `hideClosedList` | [`Boolean`](#boolean) | Whether or not closed list is hidden. | +| `iterationCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | ID of iteration cadence to be assigned to the board. | | `iterationId` | [`IterationID`](#iterationid) | ID of iteration to be assigned to the board. | | `labelIds` | [`[LabelID!]`](#labelid) | IDs of labels to be added to the board. | | `labels` | [`[String!]`](#string) | Labels of the issue. | @@ -1149,7 +1151,7 @@ Input type: `CreateComplianceFrameworkInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `framework` | [`ComplianceFramework`](#complianceframework) | The created compliance framework. | +| `framework` | [`ComplianceFramework`](#complianceframework) | Created compliance framework. | ### `Mutation.createCustomEmoji` @@ -1186,7 +1188,7 @@ Input type: `CreateDiffNoteInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `confidential` | [`Boolean`](#boolean) | Confidentiality flag of a note. Default is false. | | `noteableId` | [`NoteableID!`](#noteableid) | Global ID of the resource to add a note to. | -| `position` | [`DiffPositionInput!`](#diffpositioninput) | The position of this note on a diff. | +| `position` | [`DiffPositionInput!`](#diffpositioninput) | Position of this note on a diff. | #### Fields @@ -1204,24 +1206,24 @@ Input type: `CreateEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `addLabelIds` | [`[ID!]`](#id) | The IDs of labels to be added to the epic. | +| `addLabelIds` | [`[ID!]`](#id) | IDs of labels to be added to the epic. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | -| `description` | [`String`](#string) | The description of the epic. | -| `dueDateFixed` | [`String`](#string) | The end date of the epic. | +| `description` | [`String`](#string) | Description of the epic. | +| `dueDateFixed` | [`String`](#string) | End date of the epic. | | `dueDateIsFixed` | [`Boolean`](#boolean) | Indicates end date should be sourced from due_date_fixed field not the issue milestones. | -| `groupPath` | [`ID!`](#id) | The group the epic to mutate is in. | -| `removeLabelIds` | [`[ID!]`](#id) | The IDs of labels to be removed from the epic. | -| `startDateFixed` | [`String`](#string) | The start date of the epic. | +| `groupPath` | [`ID!`](#id) | Group the epic to mutate is in. | +| `removeLabelIds` | [`[ID!]`](#id) | IDs of labels to be removed from the epic. | +| `startDateFixed` | [`String`](#string) | Start date of the epic. | | `startDateIsFixed` | [`Boolean`](#boolean) | Indicates start date should be sourced from start_date_fixed field not the issue milestones. | -| `title` | [`String`](#string) | The title of the epic. | +| `title` | [`String`](#string) | Title of the epic. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `epic` | [`Epic`](#epic) | The created epic. | +| `epic` | [`Epic`](#epic) | Created epic. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.createImageDiffNote` @@ -1236,7 +1238,7 @@ Input type: `CreateImageDiffNoteInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `confidential` | [`Boolean`](#boolean) | Confidentiality flag of a note. Default is false. | | `noteableId` | [`NoteableID!`](#noteableid) | Global ID of the resource to add a note to. | -| `position` | [`DiffImagePositionInput!`](#diffimagepositioninput) | The position of this note on a diff. | +| `position` | [`DiffImagePositionInput!`](#diffimagepositioninput) | Position of this note on a diff. | #### Fields @@ -1261,8 +1263,8 @@ Input type: `CreateIssueInput` | `description` | [`String`](#string) | Description of the issue. | | `discussionToResolve` | [`String`](#string) | ID of a discussion to resolve. Also pass `merge_request_to_resolve_discussions_of`. | | `dueDate` | [`ISO8601Date`](#iso8601date) | Due date of the issue. | -| `epicId` | [`EpicID`](#epicid) | The ID of an epic to associate the issue with. | -| `healthStatus` | [`HealthStatus`](#healthstatus) | The desired health status. | +| `epicId` | [`EpicID`](#epicid) | ID of an epic to associate the issue with. | +| `healthStatus` | [`HealthStatus`](#healthstatus) | Desired health status. | | `iid` | [`Int`](#int) | IID (internal ID) of a project issue. Only admins and project owners can modify. | | `labelIds` | [`[LabelID!]`](#labelid) | IDs of labels to be added to the issue. | | `labels` | [`[String!]`](#string) | Labels of the issue. | @@ -1272,7 +1274,7 @@ Input type: `CreateIssueInput` | `projectPath` | [`ID!`](#id) | Project full path the issue is associated with. | | `title` | [`String!`](#string) | Title of the issue. | | `type` | [`IssueType`](#issuetype) | Type of the issue. | -| `weight` | [`Int`](#int) | The weight of the issue. | +| `weight` | [`Int`](#int) | Weight of the issue. | #### Fields @@ -1295,13 +1297,13 @@ Input type: `CreateIterationInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `description` | [`String`](#string) | The description of the iteration. | -| `dueDate` | [`String`](#string) | The end date of the iteration. | +| `description` | [`String`](#string) | Description of the iteration. | +| `dueDate` | [`String`](#string) | End date of the iteration. | | `groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | | `iterationsCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | Global ID of the iterations cadence to be assigned to newly created iteration. | | `projectPath` | [`ID`](#id) | Full path of the project with which the resource is associated. | -| `startDate` | [`String`](#string) | The start date of the iteration. | -| `title` | [`String`](#string) | The title of the iteration. | +| `startDate` | [`String`](#string) | Start date of the iteration. | +| `title` | [`String`](#string) | Title of the iteration. | #### Fields @@ -1309,7 +1311,7 @@ Input type: `CreateIterationInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `iteration` | [`Iteration`](#iteration) | The created iteration. | +| `iteration` | [`Iteration`](#iteration) | Created iteration. | ### `Mutation.createNote` @@ -1393,10 +1395,10 @@ Input type: `CreateTestCaseInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `description` | [`String`](#string) | The test case description. | -| `labelIds` | [`[ID!]`](#id) | The IDs of labels to be added to the test case. | -| `projectPath` | [`ID!`](#id) | The project full path to create the test case. | -| `title` | [`String!`](#string) | The test case title. | +| `description` | [`String`](#string) | Test case description. | +| `labelIds` | [`[ID!]`](#id) | IDs of labels to be added to the test case. | +| `projectPath` | [`ID!`](#id) | Project full path to create the test case in. | +| `title` | [`String!`](#string) | Test case title. | #### Fields @@ -1404,7 +1406,51 @@ Input type: `CreateTestCaseInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `testCase` | [`Issue`](#issue) | The test case created. | +| `testCase` | [`Issue`](#issue) | Test case created. | + +### `Mutation.customerRelationsOrganizationCreate` + +Input type: `CustomerRelationsOrganizationCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `defaultRate` | [`Float`](#float) | Standard billing rate for the organization. | +| `description` | [`String`](#string) | Description or notes for the organization. | +| `groupId` | [`GroupID!`](#groupid) | Group for the organization. | +| `name` | [`String!`](#string) | Name of the organization. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `organization` | [`CustomerRelationsOrganization`](#customerrelationsorganization) | Organization after the mutation. | + +### `Mutation.customerRelationsOrganizationUpdate` + +Input type: `CustomerRelationsOrganizationUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `defaultRate` | [`Float`](#float) | Standard billing rate for the organization. | +| `description` | [`String`](#string) | Description or notes for the organization. | +| `id` | [`CustomerRelationsOrganizationID!`](#customerrelationsorganizationid) | Global ID of the organization. | +| `name` | [`String`](#string) | Name of the organization. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `organization` | [`CustomerRelationsOrganization!`](#customerrelationsorganization) | Organization after the mutation. | ### `Mutation.dastOnDemandScanCreate` @@ -1417,7 +1463,7 @@ Input type: `DastOnDemandScanCreateInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `dastScannerProfileId` | [`DastScannerProfileID`](#dastscannerprofileid) | ID of the scanner profile to be used for the scan. | | `dastSiteProfileId` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be used for the scan. | -| `fullPath` | [`ID!`](#id) | The project the site profile belongs to. | +| `fullPath` | [`ID!`](#id) | Project the site profile belongs to. | #### Fields @@ -1435,13 +1481,14 @@ Input type: `DastProfileCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `branchName` | [`String`](#string) | The associated branch. | +| `branchName` | [`String`](#string) | Associated branch. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `dastProfileSchedule` | [`DastProfileScheduleInput`](#dastprofilescheduleinput) | Represents a DAST Profile Schedule. Results in an error if `dast_on_demand_scans_scheduler` feature flag is disabled. | | `dastScannerProfileId` | [`DastScannerProfileID!`](#dastscannerprofileid) | ID of the scanner profile to be associated. | | `dastSiteProfileId` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be associated. | -| `description` | [`String`](#string) | The description of the profile. Defaults to an empty string. | -| `fullPath` | [`ID!`](#id) | The project the profile belongs to. | -| `name` | [`String!`](#string) | The name of the profile. | +| `description` | [`String`](#string) | Description of the profile. Defaults to an empty string. | +| `fullPath` | [`ID!`](#id) | Project the profile belongs to. | +| `name` | [`String!`](#string) | Name of the profile. | | `runAfterCreate` | [`Boolean`](#boolean) | Run scan using profile after creation. Defaults to false. | #### Fields @@ -1449,9 +1496,9 @@ Input type: `DastProfileCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `dastProfile` | [`DastProfile`](#dastprofile) | The created profile. | +| `dastProfile` | [`DastProfile`](#dastprofile) | Created profile. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `pipelineUrl` | [`String`](#string) | The URL of the pipeline that was created. Requires `runAfterCreate` to be set to `true`. | +| `pipelineUrl` | [`String`](#string) | URL of the pipeline that was created. Requires `runAfterCreate` to be set to `true`. | ### `Mutation.dastProfileDelete` @@ -1499,14 +1546,15 @@ Input type: `DastProfileUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `branchName` | [`String`](#string) | The associated branch. | +| `branchName` | [`String`](#string) | Associated branch. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `dastProfileSchedule` | [`DastProfileScheduleInput`](#dastprofilescheduleinput) | Represents a DAST profile schedule. Results in an error if `dast_on_demand_scans_scheduler` feature flag is disabled. | | `dastScannerProfileId` | [`DastScannerProfileID`](#dastscannerprofileid) | ID of the scanner profile to be associated. | | `dastSiteProfileId` | [`DastSiteProfileID`](#dastsiteprofileid) | ID of the site profile to be associated. | -| `description` | [`String`](#string) | The description of the profile. Defaults to an empty string. | -| `fullPath` | [`ID!`](#id) | The project the profile belongs to. | +| `description` | [`String`](#string) | Description of the profile. Defaults to an empty string. | +| `fullPath` | [`ID!`](#id) | Project the profile belongs to. | | `id` | [`DastProfileID!`](#dastprofileid) | ID of the profile to be deleted. | -| `name` | [`String`](#string) | The name of the profile. | +| `name` | [`String`](#string) | Name of the profile. | | `runAfterUpdate` | [`Boolean`](#boolean) | Run scan using profile after update. Defaults to false. | #### Fields @@ -1514,7 +1562,7 @@ Input type: `DastProfileUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `dastProfile` | [`DastProfile`](#dastprofile) | The updated profile. | +| `dastProfile` | [`DastProfile`](#dastprofile) | Updated profile. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | `pipelineUrl` | [`String`](#string) | The URL of the pipeline that was created. Requires the input argument `runAfterUpdate` to be set to `true` when calling the mutation, otherwise no pipeline will be created. | @@ -1527,12 +1575,12 @@ Input type: `DastScannerProfileCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `fullPath` | [`ID!`](#id) | The project the scanner profile belongs to. | -| `profileName` | [`String!`](#string) | The name of the scanner profile. | +| `fullPath` | [`ID!`](#id) | Project the scanner profile belongs to. | +| `profileName` | [`String!`](#string) | Name of the scanner profile. | | `scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | `showDebugMessages` | [`Boolean`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | -| `spiderTimeout` | [`Int`](#int) | The maximum number of minutes allowed for the spider to traverse the site. | -| `targetTimeout` | [`Int`](#int) | The maximum number of seconds allowed for the site under test to respond to a request. | +| `spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | +| `targetTimeout` | [`Int`](#int) | Maximum number of seconds allowed for the site under test to respond to a request. | | `useAjaxSpider` | [`Boolean`](#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. | #### Fields @@ -1571,13 +1619,13 @@ Input type: `DastScannerProfileUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `fullPath` | [`ID!`](#id) | The project the scanner profile belongs to. | +| `fullPath` | [`ID!`](#id) | Project the scanner profile belongs to. | | `id` | [`DastScannerProfileID!`](#dastscannerprofileid) | ID of the scanner profile to be updated. | -| `profileName` | [`String!`](#string) | The name of the scanner profile. | +| `profileName` | [`String!`](#string) | Name of the scanner profile. | | `scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | `showDebugMessages` | [`Boolean`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | -| `spiderTimeout` | [`Int!`](#int) | The maximum number of minutes allowed for the spider to traverse the site. | -| `targetTimeout` | [`Int!`](#int) | The maximum number of seconds allowed for the site under test to respond to a request. | +| `spiderTimeout` | [`Int!`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | +| `targetTimeout` | [`Int!`](#int) | Maximum number of seconds allowed for the site under test to respond to a request. | | `useAjaxSpider` | [`Boolean`](#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. | #### Fields @@ -1598,12 +1646,12 @@ Input type: `DastSiteProfileCreateInput` | ---- | ---- | ----------- | | `auth` | [`DastSiteProfileAuthInput`](#dastsiteprofileauthinput) | Parameters for authentication. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. Defaults to `[]`. | -| `fullPath` | [`ID!`](#id) | The project the site profile belongs to. | -| `profileName` | [`String!`](#string) | The name of the site profile. | +| `excludedUrls` | [`[String!]`](#string) | URLs to skip during an authenticated scan. Defaults to `[]`. | +| `fullPath` | [`ID!`](#id) | Project the site profile belongs to. | +| `profileName` | [`String!`](#string) | Name of the site profile. | | `requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | -| `targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. | -| `targetUrl` | [`String`](#string) | The URL of the target to be scanned. | +| `targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | Type of target to be scanned. | +| `targetUrl` | [`String`](#string) | URL of the target to be scanned. | #### Fields @@ -1622,7 +1670,7 @@ Input type: `DastSiteProfileDeleteInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `fullPath` | [`ID!`](#id) | The project the site profile belongs to. | +| `fullPath` | [`ID!`](#id) | Project the site profile belongs to. | | `id` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be deleted. | #### Fields @@ -1642,13 +1690,13 @@ Input type: `DastSiteProfileUpdateInput` | ---- | ---- | ----------- | | `auth` | [`DastSiteProfileAuthInput`](#dastsiteprofileauthinput) | Parameters for authentication. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. | -| `fullPath` | [`ID!`](#id) | The project the site profile belongs to. | +| `excludedUrls` | [`[String!]`](#string) | URLs to skip during an authenticated scan. | +| `fullPath` | [`ID!`](#id) | Project the site profile belongs to. | | `id` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile to be updated. | -| `profileName` | [`String!`](#string) | The name of the site profile. | +| `profileName` | [`String!`](#string) | Name of the site profile. | | `requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | -| `targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. | -| `targetUrl` | [`String`](#string) | The URL of the target to be scanned. | +| `targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | Type of target to be scanned. | +| `targetUrl` | [`String`](#string) | URL of the target to be scanned. | #### Fields @@ -1667,8 +1715,8 @@ Input type: `DastSiteTokenCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `fullPath` | [`ID!`](#id) | The project the site token belongs to. | -| `targetUrl` | [`String`](#string) | The URL of the target to be validated. | +| `fullPath` | [`ID!`](#id) | Project the site token belongs to. | +| `targetUrl` | [`String`](#string) | URL of the target to be validated. | #### Fields @@ -1677,7 +1725,7 @@ Input type: `DastSiteTokenCreateInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | `id` | [`DastSiteTokenID`](#dastsitetokenid) | ID of the site token. | -| `status` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | The current validation status of the target. | +| `status` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | Current validation status of the target. | | `token` | [`String`](#string) | Token string. | ### `Mutation.dastSiteValidationCreate` @@ -1690,9 +1738,9 @@ Input type: `DastSiteValidationCreateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `dastSiteTokenId` | [`DastSiteTokenID!`](#dastsitetokenid) | ID of the site token. | -| `fullPath` | [`ID!`](#id) | The project the site profile belongs to. | -| `strategy` | [`DastSiteValidationStrategyEnum`](#dastsitevalidationstrategyenum) | The validation strategy to be used. | -| `validationPath` | [`String!`](#string) | The path to be requested during validation. | +| `fullPath` | [`ID!`](#id) | Project the site profile belongs to. | +| `strategy` | [`DastSiteValidationStrategyEnum`](#dastsitevalidationstrategyenum) | Validation strategy to be used. | +| `validationPath` | [`String!`](#string) | Path to be requested during validation. | #### Fields @@ -1701,7 +1749,7 @@ Input type: `DastSiteValidationCreateInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | `id` | [`DastSiteValidationID`](#dastsitevalidationid) | ID of the site validation. | -| `status` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | The current validation status. | +| `status` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | Current validation status. | ### `Mutation.dastSiteValidationRevoke` @@ -1712,7 +1760,7 @@ Input type: `DastSiteValidationRevokeInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `fullPath` | [`ID!`](#id) | The project the site validation belongs to. | +| `fullPath` | [`ID!`](#id) | Project the site validation belongs to. | | `normalizedTargetUrl` | [`String!`](#string) | Normalized URL of the target to be revoked. | #### Fields @@ -1851,7 +1899,7 @@ Input type: `DestroyComplianceFrameworkInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `id` | [`ComplianceManagementFrameworkID!`](#compliancemanagementframeworkid) | The global ID of the compliance framework to destroy. | +| `id` | [`ComplianceManagementFrameworkID!`](#compliancemanagementframeworkid) | Global ID of the compliance framework to destroy. | #### Fields @@ -1899,6 +1947,27 @@ Input type: `DestroyContainerRepositoryTagsInput` | `deletedTagNames` | [`[String!]!`](#string) | Deleted container repository tags. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.destroyCustomEmoji` + +Available only when feature flag `custom_emoji` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. + +Input type: `DestroyCustomEmojiInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `id` | [`CustomEmojiID!`](#customemojiid) | Global ID of the custom emoji to destroy. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `customEmoji` | [`CustomEmoji`](#customemoji) | Deleted custom emoji. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.destroyEpicBoard` Input type: `DestroyEpicBoardInput` @@ -2109,18 +2178,18 @@ Input type: `EpicAddIssueInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `groupPath` | [`ID!`](#id) | The group the epic to mutate belongs to. | -| `iid` | [`ID!`](#id) | The IID of the epic to mutate. | -| `issueIid` | [`String!`](#string) | The IID of the issue to be added. | -| `projectPath` | [`ID!`](#id) | The full path of the project the issue belongs to. | +| `groupPath` | [`ID!`](#id) | Group the epic to mutate belongs to. | +| `iid` | [`ID!`](#id) | IID of the epic to mutate. | +| `issueIid` | [`String!`](#string) | IID of the issue to be added. | +| `projectPath` | [`ID!`](#id) | Full path of the project the issue belongs to. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `epic` | [`Epic`](#epic) | The epic after mutation. | -| `epicIssue` | [`EpicIssue`](#epicissue) | The epic-issue relation. | +| `epic` | [`Epic`](#epic) | Epic after mutation. | +| `epicIssue` | [`EpicIssue`](#epicissue) | Epic-issue relationship. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicBoardCreate` @@ -2144,7 +2213,7 @@ Input type: `EpicBoardCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `epicBoard` | [`EpicBoard`](#epicboard) | The created epic board. | +| `epicBoard` | [`EpicBoard`](#epicboard) | Created epic board. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicBoardListCreate` @@ -2187,7 +2256,7 @@ Input type: `EpicBoardListDestroyInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `list` | [`EpicList`](#epiclist) | The epic board list. `null` if the board was destroyed successfully. | +| `list` | [`EpicList`](#epiclist) | Epic board list. `null` if the board was destroyed successfully. | ### `Mutation.epicBoardUpdate` @@ -2200,7 +2269,7 @@ Input type: `EpicBoardUpdateInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `hideBacklogList` | [`Boolean`](#boolean) | Whether or not backlog list is hidden. | | `hideClosedList` | [`Boolean`](#boolean) | Whether or not closed list is hidden. | -| `id` | [`BoardsEpicBoardID!`](#boardsepicboardid) | The epic board global ID. | +| `id` | [`BoardsEpicBoardID!`](#boardsepicboardid) | Epic board global ID. | | `labelIds` | [`[LabelID!]`](#labelid) | IDs of labels to be added to the board. | | `labels` | [`[String!]`](#string) | Labels of the issue. | | `name` | [`String`](#string) | Board name. | @@ -2210,7 +2279,7 @@ Input type: `EpicBoardUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `epicBoard` | [`EpicBoard`](#epicboard) | The updated epic board. | +| `epicBoard` | [`EpicBoard`](#epicboard) | Updated epic board. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicMoveList` @@ -2234,7 +2303,7 @@ Input type: `EpicMoveListInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `epic` | [`Epic`](#epic) | The epic after mutation. | +| `epic` | [`Epic`](#epic) | Epic after mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicSetSubscription` @@ -2246,16 +2315,16 @@ Input type: `EpicSetSubscriptionInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `groupPath` | [`ID!`](#id) | The group the epic to mutate belongs to. | -| `iid` | [`ID!`](#id) | The IID of the epic to mutate. | -| `subscribedState` | [`Boolean!`](#boolean) | The desired state of the subscription. | +| `groupPath` | [`ID!`](#id) | Group the epic to mutate belongs to. | +| `iid` | [`ID!`](#id) | IID of the epic to mutate. | +| `subscribedState` | [`Boolean!`](#boolean) | Desired state of the subscription. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `epic` | [`Epic`](#epic) | The epic after mutation. | +| `epic` | [`Epic`](#epic) | Epic after mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.epicTreeReorder` @@ -2266,7 +2335,7 @@ Input type: `EpicTreeReorderInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `baseEpicId` | [`EpicID!`](#epicid) | The ID of the base epic of the tree. | +| `baseEpicId` | [`EpicID!`](#epicid) | ID of the base epic of the tree. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `moved` | [`EpicTreeNodeFieldsInputType!`](#epictreenodefieldsinputtype) | Parameters for updating the tree positions. | @@ -2286,10 +2355,10 @@ Input type: `EscalationPolicyCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `description` | [`String`](#string) | The description of the escalation policy. | -| `name` | [`String!`](#string) | The name of the escalation policy. | -| `projectPath` | [`ID!`](#id) | The project to create the escalation policy for. | -| `rules` | [`[EscalationRuleInput!]!`](#escalationruleinput) | The steps of the escalation policy. | +| `description` | [`String`](#string) | Description of the escalation policy. | +| `name` | [`String!`](#string) | Name of the escalation policy. | +| `projectPath` | [`ID!`](#id) | Project to create the escalation policy for. | +| `rules` | [`[EscalationRuleInput!]!`](#escalationruleinput) | Steps of the escalation policy. | #### Fields @@ -2297,7 +2366,7 @@ Input type: `EscalationPolicyCreateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | The escalation policy. | +| `escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy. | ### `Mutation.escalationPolicyDestroy` @@ -2308,7 +2377,7 @@ Input type: `EscalationPolicyDestroyInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | The escalation policy internal ID to remove. | +| `id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | Escalation policy internal ID to remove. | #### Fields @@ -2316,7 +2385,7 @@ Input type: `EscalationPolicyDestroyInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | The escalation policy. | +| `escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy. | ### `Mutation.escalationPolicyUpdate` @@ -2327,10 +2396,10 @@ Input type: `EscalationPolicyUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `description` | [`String`](#string) | The description of the escalation policy. | -| `id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | The ID of the on-call schedule to create the on-call rotation in. | -| `name` | [`String`](#string) | The name of the escalation policy. | -| `rules` | [`[EscalationRuleInput!]`](#escalationruleinput) | The steps of the escalation policy. | +| `description` | [`String`](#string) | Description of the escalation policy. | +| `id` | [`IncidentManagementEscalationPolicyID!`](#incidentmanagementescalationpolicyid) | ID of the on-call schedule to create the on-call rotation in. | +| `name` | [`String`](#string) | Name of the escalation policy. | +| `rules` | [`[EscalationRuleInput!]`](#escalationruleinput) | Steps of the escalation policy. | #### Fields @@ -2338,7 +2407,7 @@ Input type: `EscalationPolicyUpdateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | The escalation policy. | +| `escalationPolicy` | [`EscalationPolicyType`](#escalationpolicytype) | Escalation policy. | ### `Mutation.exportRequirements` @@ -2380,7 +2449,7 @@ Input type: `GitlabSubscriptionActivateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `license` | [`CurrentLicense`](#currentlicense) | The current license. | +| `license` | [`CurrentLicense`](#currentlicense) | Current license. | ### `Mutation.groupUpdate` @@ -2413,8 +2482,8 @@ Input type: `HttpIntegrationCreateInput` | `active` | [`Boolean!`](#boolean) | Whether the integration is receiving alerts. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `name` | [`String!`](#string) | Name of the integration. | -| `payloadAttributeMappings` | [`[AlertManagementPayloadAlertFieldInput!]`](#alertmanagementpayloadalertfieldinput) | The custom mapping of GitLab alert attributes to fields from the payload_example. | -| `payloadExample` | [`JsonString`](#jsonstring) | The example of an alert payload. | +| `payloadAttributeMappings` | [`[AlertManagementPayloadAlertFieldInput!]`](#alertmanagementpayloadalertfieldinput) | Custom mapping of GitLab alert attributes to fields from the payload example. | +| `payloadExample` | [`JsonString`](#jsonstring) | Example of an alert payload. | | `projectPath` | [`ID!`](#id) | Project to create the integration in. | #### Fields @@ -2475,8 +2544,8 @@ Input type: `HttpIntegrationUpdateInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `id` | [`AlertManagementHttpIntegrationID!`](#alertmanagementhttpintegrationid) | ID of the integration to mutate. | | `name` | [`String`](#string) | Name of the integration. | -| `payloadAttributeMappings` | [`[AlertManagementPayloadAlertFieldInput!]`](#alertmanagementpayloadalertfieldinput) | The custom mapping of GitLab alert attributes to fields from the payload_example. | -| `payloadExample` | [`JsonString`](#jsonstring) | The example of an alert payload. | +| `payloadAttributeMappings` | [`[AlertManagementPayloadAlertFieldInput!]`](#alertmanagementpayloadalertfieldinput) | Custom mapping of GitLab alert attributes to fields from the payload example. | +| `payloadExample` | [`JsonString`](#jsonstring) | Example of an alert payload. | #### Fields @@ -2628,7 +2697,7 @@ Input type: `IssueSetIterationInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `iid` | [`String!`](#string) | IID of the issue to mutate. | -| `iterationId` | [`IterationID`](#iterationid) | The iteration to assign to the issue. | +| `iterationId` | [`IterationID`](#iterationid) | Iteration to assign to the issue. | | `projectPath` | [`ID!`](#id) | Project the issue to mutate is in. | #### Fields @@ -2736,7 +2805,7 @@ Input type: `IterationCadenceCreateInput` | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `description` | [`String`](#string) | Description of the iteration cadence. Maximum length is 5000 characters. | | `durationInWeeks` | [`Int`](#int) | Duration in weeks of the iterations within this cadence. | -| `groupPath` | [`ID!`](#id) | The group where the iteration cadence is created. | +| `groupPath` | [`ID!`](#id) | Group where the iteration cadence is created. | | `iterationsInAdvance` | [`Int`](#int) | Future iterations to be created when iteration cadence is set to automatic. | | `rollOver` | [`Boolean`](#boolean) | Whether the iteration cadence should roll over issues to the next iteration or not. | | `startDate` | [`Time`](#time) | Timestamp of the iteration cadence start date. | @@ -2748,7 +2817,7 @@ Input type: `IterationCadenceCreateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `iterationCadence` | [`IterationCadence`](#iterationcadence) | The created iteration cadence. | +| `iterationCadence` | [`IterationCadence`](#iterationcadence) | Created iteration cadence. | ### `Mutation.iterationCadenceDestroy` @@ -2794,7 +2863,7 @@ Input type: `IterationCadenceUpdateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `iterationCadence` | [`IterationCadence`](#iterationcadence) | The updated iteration cadence. | +| `iterationCadence` | [`IterationCadence`](#iterationcadence) | Updated iteration cadence. | ### `Mutation.iterationCreate` @@ -2805,13 +2874,13 @@ Input type: `iterationCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `description` | [`String`](#string) | The description of the iteration. | -| `dueDate` | [`String`](#string) | The end date of the iteration. | +| `description` | [`String`](#string) | Description of the iteration. | +| `dueDate` | [`String`](#string) | End date of the iteration. | | `groupPath` | [`ID`](#id) | Full path of the group with which the resource is associated. | | `iterationsCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | Global ID of the iterations cadence to be assigned to newly created iteration. | | `projectPath` | [`ID`](#id) | Full path of the project with which the resource is associated. | -| `startDate` | [`String`](#string) | The start date of the iteration. | -| `title` | [`String`](#string) | The title of the iteration. | +| `startDate` | [`String`](#string) | Start date of the iteration. | +| `title` | [`String`](#string) | Title of the iteration. | #### Fields @@ -2819,7 +2888,7 @@ Input type: `iterationCreateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `iteration` | [`Iteration`](#iteration) | The created iteration. | +| `iteration` | [`Iteration`](#iteration) | Created iteration. | ### `Mutation.iterationDelete` @@ -3263,7 +3332,7 @@ Input type: `NamespaceIncreaseStorageTemporarilyInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `id` | [`NamespaceID!`](#namespaceid) | The global ID of the namespace to mutate. | +| `id` | [`NamespaceID!`](#namespaceid) | Global ID of the namespace to mutate. | #### Fields @@ -3271,7 +3340,7 @@ Input type: `NamespaceIncreaseStorageTemporarilyInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `namespace` | [`Namespace`](#namespace) | The namespace after mutation. | +| `namespace` | [`Namespace`](#namespace) | Namespace after mutation. | ### `Mutation.oncallRotationCreate` @@ -3281,15 +3350,15 @@ Input type: `OncallRotationCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `activePeriod` | [`OncallRotationActivePeriodInputType`](#oncallrotationactiveperiodinputtype) | The active period of time that the on-call rotation should take place. | +| `activePeriod` | [`OncallRotationActivePeriodInputType`](#oncallrotationactiveperiodinputtype) | Active period of time that the on-call rotation should take place. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `endsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | The end date and time of the on-call rotation, in the timezone of the on-call schedule. | -| `name` | [`String!`](#string) | The name of the on-call rotation. | -| `participants` | [`[OncallUserInputType!]!`](#oncalluserinputtype) | The usernames of users participating in the on-call rotation. A maximum limit of 100 participants applies. | -| `projectPath` | [`ID!`](#id) | The project to create the on-call schedule in. | -| `rotationLength` | [`OncallRotationLengthInputType!`](#oncallrotationlengthinputtype) | The rotation length of the on-call rotation. | -| `scheduleIid` | [`String!`](#string) | The IID of the on-call schedule to create the on-call rotation in. | -| `startsAt` | [`OncallRotationDateInputType!`](#oncallrotationdateinputtype) | The start date and time of the on-call rotation, in the timezone of the on-call schedule. | +| `endsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | End date and time of the on-call rotation, in the timezone of the on-call schedule. | +| `name` | [`String!`](#string) | Name of the on-call rotation. | +| `participants` | [`[OncallUserInputType!]!`](#oncalluserinputtype) | Usernames of users participating in the on-call rotation. A maximum limit of 100 participants applies. | +| `projectPath` | [`ID!`](#id) | Project to create the on-call schedule in. | +| `rotationLength` | [`OncallRotationLengthInputType!`](#oncallrotationlengthinputtype) | Rotation length of the on-call rotation. | +| `scheduleIid` | [`String!`](#string) | IID of the on-call schedule to create the on-call rotation in. | +| `startsAt` | [`OncallRotationDateInputType!`](#oncallrotationdateinputtype) | Start date and time of the on-call rotation, in the timezone of the on-call schedule. | #### Fields @@ -3297,7 +3366,7 @@ Input type: `OncallRotationCreateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | The on-call rotation. | +| `oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | On-call rotation. | ### `Mutation.oncallRotationDestroy` @@ -3308,9 +3377,9 @@ Input type: `OncallRotationDestroyInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `id` | [`IncidentManagementOncallRotationID!`](#incidentmanagementoncallrotationid) | The ID of the on-call rotation to remove. | -| `projectPath` | [`ID!`](#id) | The project to remove the on-call schedule from. | -| `scheduleIid` | [`String!`](#string) | The IID of the on-call schedule to the on-call rotation belongs to. | +| `id` | [`IncidentManagementOncallRotationID!`](#incidentmanagementoncallrotationid) | ID of the on-call rotation to remove. | +| `projectPath` | [`ID!`](#id) | Project to remove the on-call schedule from. | +| `scheduleIid` | [`String!`](#string) | IID of the on-call schedule to the on-call rotation belongs to. | #### Fields @@ -3318,7 +3387,7 @@ Input type: `OncallRotationDestroyInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | The on-call rotation. | +| `oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | On-call rotation. | ### `Mutation.oncallRotationUpdate` @@ -3328,14 +3397,14 @@ Input type: `OncallRotationUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `activePeriod` | [`OncallRotationActivePeriodInputType`](#oncallrotationactiveperiodinputtype) | The active period of time that the on-call rotation should take place. | +| `activePeriod` | [`OncallRotationActivePeriodInputType`](#oncallrotationactiveperiodinputtype) | Active period of time that the on-call rotation should take place. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `endsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | The end date and time of the on-call rotation, in the timezone of the on-call schedule. | -| `id` | [`IncidentManagementOncallRotationID!`](#incidentmanagementoncallrotationid) | The ID of the on-call schedule to create the on-call rotation in. | -| `name` | [`String`](#string) | The name of the on-call rotation. | -| `participants` | [`[OncallUserInputType!]`](#oncalluserinputtype) | The usernames of users participating in the on-call rotation. A maximum limit of 100 participants applies. | -| `rotationLength` | [`OncallRotationLengthInputType`](#oncallrotationlengthinputtype) | The rotation length of the on-call rotation. | -| `startsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | The start date and time of the on-call rotation, in the timezone of the on-call schedule. | +| `endsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | End date and time of the on-call rotation, in the timezone of the on-call schedule. | +| `id` | [`IncidentManagementOncallRotationID!`](#incidentmanagementoncallrotationid) | ID of the on-call schedule to create the on-call rotation in. | +| `name` | [`String`](#string) | Name of the on-call rotation. | +| `participants` | [`[OncallUserInputType!]`](#oncalluserinputtype) | Usernames of users participating in the on-call rotation. A maximum limit of 100 participants applies. | +| `rotationLength` | [`OncallRotationLengthInputType`](#oncallrotationlengthinputtype) | Rotation length of the on-call rotation. | +| `startsAt` | [`OncallRotationDateInputType`](#oncallrotationdateinputtype) | Start date and time of the on-call rotation, in the timezone of the on-call schedule. | #### Fields @@ -3343,7 +3412,7 @@ Input type: `OncallRotationUpdateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | The on-call rotation. | +| `oncallRotation` | [`IncidentManagementOncallRotation`](#incidentmanagementoncallrotation) | On-call rotation. | ### `Mutation.oncallScheduleCreate` @@ -3354,10 +3423,10 @@ Input type: `OncallScheduleCreateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `description` | [`String`](#string) | The description of the on-call schedule. | -| `name` | [`String!`](#string) | The name of the on-call schedule. | -| `projectPath` | [`ID!`](#id) | The project to create the on-call schedule in. | -| `timezone` | [`String!`](#string) | The timezone of the on-call schedule. | +| `description` | [`String`](#string) | Description of the on-call schedule. | +| `name` | [`String!`](#string) | Name of the on-call schedule. | +| `projectPath` | [`ID!`](#id) | Project to create the on-call schedule in. | +| `timezone` | [`String!`](#string) | Timezone of the on-call schedule. | #### Fields @@ -3365,7 +3434,7 @@ Input type: `OncallScheduleCreateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | The on-call schedule. | +| `oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | On-call schedule. | ### `Mutation.oncallScheduleDestroy` @@ -3376,8 +3445,8 @@ Input type: `OncallScheduleDestroyInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `iid` | [`String!`](#string) | The on-call schedule internal ID to remove. | -| `projectPath` | [`ID!`](#id) | The project to remove the on-call schedule from. | +| `iid` | [`String!`](#string) | On-call schedule internal ID to remove. | +| `projectPath` | [`ID!`](#id) | Project to remove the on-call schedule from. | #### Fields @@ -3385,7 +3454,7 @@ Input type: `OncallScheduleDestroyInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | The on-call schedule. | +| `oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | On-call schedule. | ### `Mutation.oncallScheduleUpdate` @@ -3396,11 +3465,11 @@ Input type: `OncallScheduleUpdateInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `description` | [`String`](#string) | The description of the on-call schedule. | -| `iid` | [`String!`](#string) | The on-call schedule internal ID to update. | -| `name` | [`String`](#string) | The name of the on-call schedule. | -| `projectPath` | [`ID!`](#id) | The project to update the on-call schedule in. | -| `timezone` | [`String`](#string) | The timezone of the on-call schedule. | +| `description` | [`String`](#string) | Description of the on-call schedule. | +| `iid` | [`String!`](#string) | On-call schedule internal ID to update. | +| `name` | [`String`](#string) | Name of the on-call schedule. | +| `projectPath` | [`ID!`](#id) | Project to update the on-call schedule in. | +| `timezone` | [`String`](#string) | Timezone of the on-call schedule. | #### Fields @@ -3408,7 +3477,7 @@ Input type: `OncallScheduleUpdateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | The on-call schedule. | +| `oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | On-call schedule. | ### `Mutation.pipelineCancel` @@ -3578,7 +3647,7 @@ Input type: `PromoteToEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `groupPath` | [`ID`](#id) | The group the promoted epic will belong to. | +| `groupPath` | [`ID`](#id) | Group the promoted epic will belong to. | | `iid` | [`String!`](#string) | IID of the issue to mutate. | | `projectPath` | [`ID!`](#id) | Project the issue to mutate is in. | @@ -3587,7 +3656,7 @@ Input type: `PromoteToEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `epic` | [`Epic`](#epic) | The epic after issue promotion. | +| `epic` | [`Epic`](#epic) | Epic after issue promotion. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | `issue` | [`Issue`](#issue) | Issue after mutation. | @@ -3601,7 +3670,7 @@ Input type: `ReleaseAssetLinkCreateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `directAssetPath` | [`String`](#string) | Relative path for a direct asset link. | -| `linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | The type of the asset link. | +| `linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | Type of the asset link. | | `name` | [`String!`](#string) | Name of the asset link. | | `projectPath` | [`ID!`](#id) | Full path of the project the asset link is associated with. | | `tagName` | [`String!`](#string) | Name of the associated release's tag. | @@ -3757,7 +3826,7 @@ Input type: `RepositionImageDiffNoteInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `id` | [`DiffNoteID!`](#diffnoteid) | Global ID of the DiffNote to update. | -| `position` | [`UpdateDiffImagePositionInput!`](#updatediffimagepositioninput) | The position of this note on a diff. | +| `position` | [`UpdateDiffImagePositionInput!`](#updatediffimagepositioninput) | Position of this note on a diff. | #### Fields @@ -3769,8 +3838,6 @@ Input type: `RepositionImageDiffNoteInput` ### `Mutation.runnerDelete` -Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. - Input type: `RunnerDeleteInput` #### Arguments @@ -3789,8 +3856,6 @@ Input type: `RunnerDeleteInput` ### `Mutation.runnerUpdate` -Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. - Input type: `RunnerUpdateInput` #### Arguments @@ -3819,8 +3884,6 @@ Input type: `RunnerUpdateInput` ### `Mutation.runnersRegistrationTokenReset` -Available only when feature flag `runner_graphql_query` is enabled. This flag is enabled by default. - Input type: `RunnersRegistrationTokenResetInput` #### Arguments @@ -4082,6 +4145,7 @@ Input type: `UpdateBoardInput` | `hideBacklogList` | [`Boolean`](#boolean) | Whether or not backlog list is hidden. | | `hideClosedList` | [`Boolean`](#boolean) | Whether or not closed list is hidden. | | `id` | [`BoardID!`](#boardid) | Board global ID. | +| `iterationCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | ID of iteration cadence to be assigned to the board. | | `iterationId` | [`IterationID`](#iterationid) | ID of iteration to be assigned to the board. | | `labelIds` | [`[LabelID!]`](#labelid) | IDs of labels to be added to the board. | | `labels` | [`[String!]`](#string) | Labels of the issue. | @@ -4105,7 +4169,7 @@ Input type: `UpdateBoardEpicUserPreferencesInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `boardId` | [`BoardID!`](#boardid) | The board global ID. | +| `boardId` | [`BoardID!`](#boardid) | Board global ID. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `collapsed` | [`Boolean!`](#boolean) | Whether the epic should be collapsed in the board. | | `epicId` | [`EpicID!`](#epicid) | ID of an epic to set preferences for. | @@ -4148,7 +4212,7 @@ Input type: `UpdateComplianceFrameworkInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `id` | [`ComplianceManagementFrameworkID!`](#compliancemanagementframeworkid) | The global ID of the compliance framework to update. | +| `id` | [`ComplianceManagementFrameworkID!`](#compliancemanagementframeworkid) | Global ID of the compliance framework to update. | | `params` | [`ComplianceFrameworkInput!`](#complianceframeworkinput) | Parameters to update the compliance framework with. | #### Fields @@ -4156,7 +4220,7 @@ Input type: `UpdateComplianceFrameworkInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `complianceFramework` | [`ComplianceFramework`](#complianceframework) | The compliance framework after mutation. | +| `complianceFramework` | [`ComplianceFramework`](#complianceframework) | Compliance framework after mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.updateContainerExpirationPolicy` @@ -4184,6 +4248,27 @@ Input type: `UpdateContainerExpirationPolicyInput` | `containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy after mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.updateDependencyProxyImageTtlGroupPolicy` + +Input type: `UpdateDependencyProxyImageTtlGroupPolicyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `enabled` | [`Boolean`](#boolean) | Indicates whether the policy is enabled or disabled. | +| `groupPath` | [`ID!`](#id) | Group path for the group dependency proxy image TTL policy. | +| `ttl` | [`Int`](#int) | Number of days to retain a cached image file. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `dependencyProxyImageTtlPolicy` | [`DependencyProxyImageTtlGroupPolicy`](#dependencyproxyimagettlgrouppolicy) | Group image TTL policy after mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.updateEpic` Input type: `UpdateEpicInput` @@ -4192,26 +4277,26 @@ Input type: `UpdateEpicInput` | Name | Type | Description | | ---- | ---- | ----------- | -| `addLabelIds` | [`[ID!]`](#id) | The IDs of labels to be added to the epic. | +| `addLabelIds` | [`[ID!]`](#id) | IDs of labels to be added to the epic. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | -| `description` | [`String`](#string) | The description of the epic. | -| `dueDateFixed` | [`String`](#string) | The end date of the epic. | +| `description` | [`String`](#string) | Description of the epic. | +| `dueDateFixed` | [`String`](#string) | End date of the epic. | | `dueDateIsFixed` | [`Boolean`](#boolean) | Indicates end date should be sourced from due_date_fixed field not the issue milestones. | -| `groupPath` | [`ID!`](#id) | The group the epic to mutate is in. | -| `iid` | [`ID!`](#id) | The IID of the epic to mutate. | -| `removeLabelIds` | [`[ID!]`](#id) | The IDs of labels to be removed from the epic. | -| `startDateFixed` | [`String`](#string) | The start date of the epic. | +| `groupPath` | [`ID!`](#id) | Group the epic to mutate is in. | +| `iid` | [`ID!`](#id) | IID of the epic to mutate. | +| `removeLabelIds` | [`[ID!]`](#id) | IDs of labels to be removed from the epic. | +| `startDateFixed` | [`String`](#string) | Start date of the epic. | | `startDateIsFixed` | [`Boolean`](#boolean) | Indicates start date should be sourced from start_date_fixed field not the issue milestones. | | `stateEvent` | [`EpicStateEvent`](#epicstateevent) | State event for the epic. | -| `title` | [`String`](#string) | The title of the epic. | +| `title` | [`String`](#string) | Title of the epic. | #### Fields | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `epic` | [`Epic`](#epic) | The epic after mutation. | +| `epic` | [`Epic`](#epic) | Epic after mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | ### `Mutation.updateEpicBoardList` @@ -4251,7 +4336,7 @@ Input type: `UpdateImageDiffNoteInput` | `body` | [`String`](#string) | Content of the note. | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `id` | [`NoteID!`](#noteid) | Global ID of the note to update. | -| `position` | [`UpdateDiffImagePositionInput`](#updatediffimagepositioninput) | The position of this note on a diff. | +| `position` | [`UpdateDiffImagePositionInput`](#updatediffimagepositioninput) | Position of this note on a diff. | #### Fields @@ -4274,8 +4359,8 @@ Input type: `UpdateIssueInput` | `confidential` | [`Boolean`](#boolean) | Indicates the issue is confidential. | | `description` | [`String`](#string) | Description of the issue. | | `dueDate` | [`ISO8601Date`](#iso8601date) | Due date of the issue. | -| `epicId` | [`EpicID`](#epicid) | The ID of the parent epic. NULL when removing the association. | -| `healthStatus` | [`HealthStatus`](#healthstatus) | The desired health status. | +| `epicId` | [`EpicID`](#epicid) | ID of the parent epic. NULL when removing the association. | +| `healthStatus` | [`HealthStatus`](#healthstatus) | Desired health status. | | `iid` | [`String!`](#string) | IID of the issue to mutate. | | `labelIds` | [`[ID!]`](#id) | IDs of labels to be set. Replaces existing issue labels. | | `locked` | [`Boolean`](#boolean) | Indicates discussion is locked on the issue. | @@ -4285,7 +4370,7 @@ Input type: `UpdateIssueInput` | `stateEvent` | [`IssueStateEvent`](#issuestateevent) | Close or reopen an issue. | | `title` | [`String`](#string) | Title of the issue. | | `type` | [`IssueType`](#issuetype) | Type of the issue. | -| `weight` | [`Int`](#int) | The weight of the issue. | +| `weight` | [`Int`](#int) | Weight of the issue. | #### Fields @@ -4378,7 +4463,7 @@ Input type: `UpdateRequirementInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `description` | [`String`](#string) | Description of the requirement. | -| `iid` | [`String!`](#string) | The IID of the requirement to update. | +| `iid` | [`String!`](#string) | IID of the requirement to update. | | `lastTestReportState` | [`TestReportState`](#testreportstate) | Creates a test report for the requirement with the given state. | | `projectPath` | [`ID!`](#id) | Full project path the requirement is associated with. | | `state` | [`RequirementState`](#requirementstate) | State of the requirement. | @@ -4457,7 +4542,39 @@ Input type: `VulnerabilityConfirmInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after state change. | +| `vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after state change. | + +### `Mutation.vulnerabilityCreate` + +Input type: `VulnerabilityCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `confidence` | [`VulnerabilityConfidence`](#vulnerabilityconfidence) | Confidence of the vulnerability (defaults to `unknown`). | +| `confirmedAt` | [`Time`](#time) | Timestamp of when the vulnerability state changed to confirmed (defaults to creation time if status is `confirmed`). | +| `description` | [`String!`](#string) | Description of the vulnerability. | +| `detectedAt` | [`Time`](#time) | Timestamp of when the vulnerability was first detected (defaults to creation time). | +| `dismissedAt` | [`Time`](#time) | Timestamp of when the vulnerability state changed to dismissed (defaults to creation time if status is `dismissed`). | +| `identifiers` | [`[VulnerabilityIdentifierInput!]!`](#vulnerabilityidentifierinput) | Array of CVE or CWE identifiers for the vulnerability. | +| `message` | [`String`](#string) | Additional information about the vulnerability. | +| `project` | [`ProjectID!`](#projectid) | ID of the project to attach the vulnerability to. | +| `resolvedAt` | [`Time`](#time) | Timestamp of when the vulnerability state changed to resolved (defaults to creation time if status is `resolved`). | +| `scannerName` | [`String!`](#string) | Name of the security scanner used to discover the vulnerability. | +| `severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability (defaults to `unknown`). | +| `solution` | [`String`](#string) | How to fix this vulnerability. | +| `state` | [`VulnerabilityState`](#vulnerabilitystate) | State of the vulnerability (defaults to `detected`). | +| `title` | [`String!`](#string) | Title of the vulnerability. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| `vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability created. | ### `Mutation.vulnerabilityDismiss` @@ -4478,7 +4595,7 @@ Input type: `VulnerabilityDismissInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after dismissal. | +| `vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after dismissal. | ### `Mutation.vulnerabilityExternalIssueLinkCreate` @@ -4499,7 +4616,7 @@ Input type: `VulnerabilityExternalIssueLinkCreateInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `externalIssueLink` | [`VulnerabilityExternalIssueLink`](#vulnerabilityexternalissuelink) | The created external issue link. | +| `externalIssueLink` | [`VulnerabilityExternalIssueLink`](#vulnerabilityexternalissuelink) | Created external issue link. | ### `Mutation.vulnerabilityExternalIssueLinkDestroy` @@ -4510,7 +4627,7 @@ Input type: `VulnerabilityExternalIssueLinkDestroyInput` | Name | Type | Description | | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | -| `id` | [`VulnerabilitiesExternalIssueLinkID!`](#vulnerabilitiesexternalissuelinkid) | The global ID of the vulnerability external issue link. | +| `id` | [`VulnerabilitiesExternalIssueLinkID!`](#vulnerabilitiesexternalissuelinkid) | Global ID of the vulnerability external issue link. | #### Fields @@ -4536,7 +4653,7 @@ Input type: `VulnerabilityResolveInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after state change. | +| `vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after state change. | ### `Mutation.vulnerabilityRevertToDetected` @@ -4555,7 +4672,7 @@ Input type: `VulnerabilityRevertToDetectedInput` | ---- | ---- | ----------- | | `clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | `errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | -| `vulnerability` | [`Vulnerability`](#vulnerability) | The vulnerability after revert. | +| `vulnerability` | [`Vulnerability`](#vulnerability) | Vulnerability after revert. | ## Connections @@ -5221,6 +5338,29 @@ The edge type for [`ComplianceFramework`](#complianceframework). | `cursor` | [`String!`](#string) | A cursor for use in pagination. | | `node` | [`ComplianceFramework`](#complianceframework) | The item at the end of the edge. | +#### `ConnectedAgentConnection` + +The connection type for [`ConnectedAgent`](#connectedagent). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `edges` | [`[ConnectedAgentEdge]`](#connectedagentedge) | A list of edges. | +| `nodes` | [`[ConnectedAgent]`](#connectedagent) | A list of nodes. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ConnectedAgentEdge` + +The edge type for [`ConnectedAgent`](#connectedagent). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `cursor` | [`String!`](#string) | A cursor for use in pagination. | +| `node` | [`ConnectedAgent`](#connectedagent) | The item at the end of the edge. | + #### `ContainerRepositoryConnection` The connection type for [`ContainerRepository`](#containerrepository). @@ -5290,6 +5430,52 @@ The edge type for [`CustomEmoji`](#customemoji). | `cursor` | [`String!`](#string) | A cursor for use in pagination. | | `node` | [`CustomEmoji`](#customemoji) | The item at the end of the edge. | +#### `CustomerRelationsContactConnection` + +The connection type for [`CustomerRelationsContact`](#customerrelationscontact). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `edges` | [`[CustomerRelationsContactEdge]`](#customerrelationscontactedge) | A list of edges. | +| `nodes` | [`[CustomerRelationsContact]`](#customerrelationscontact) | A list of nodes. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `CustomerRelationsContactEdge` + +The edge type for [`CustomerRelationsContact`](#customerrelationscontact). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `cursor` | [`String!`](#string) | A cursor for use in pagination. | +| `node` | [`CustomerRelationsContact`](#customerrelationscontact) | The item at the end of the edge. | + +#### `CustomerRelationsOrganizationConnection` + +The connection type for [`CustomerRelationsOrganization`](#customerrelationsorganization). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `edges` | [`[CustomerRelationsOrganizationEdge]`](#customerrelationsorganizationedge) | A list of edges. | +| `nodes` | [`[CustomerRelationsOrganization]`](#customerrelationsorganization) | A list of nodes. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `CustomerRelationsOrganizationEdge` + +The edge type for [`CustomerRelationsOrganization`](#customerrelationsorganization). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `cursor` | [`String!`](#string) | A cursor for use in pagination. | +| `node` | [`CustomerRelationsOrganization`](#customerrelationsorganization) | The item at the end of the edge. | + #### `DastProfileConnection` The connection type for [`DastProfile`](#dastprofile). @@ -5382,6 +5568,52 @@ The edge type for [`DastSiteValidation`](#dastsitevalidation). | `cursor` | [`String!`](#string) | A cursor for use in pagination. | | `node` | [`DastSiteValidation`](#dastsitevalidation) | The item at the end of the edge. | +#### `DependencyProxyBlobConnection` + +The connection type for [`DependencyProxyBlob`](#dependencyproxyblob). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `edges` | [`[DependencyProxyBlobEdge]`](#dependencyproxyblobedge) | A list of edges. | +| `nodes` | [`[DependencyProxyBlob]`](#dependencyproxyblob) | A list of nodes. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `DependencyProxyBlobEdge` + +The edge type for [`DependencyProxyBlob`](#dependencyproxyblob). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `cursor` | [`String!`](#string) | A cursor for use in pagination. | +| `node` | [`DependencyProxyBlob`](#dependencyproxyblob) | The item at the end of the edge. | + +#### `DependencyProxyManifestConnection` + +The connection type for [`DependencyProxyManifest`](#dependencyproxymanifest). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `edges` | [`[DependencyProxyManifestEdge]`](#dependencyproxymanifestedge) | A list of edges. | +| `nodes` | [`[DependencyProxyManifest]`](#dependencyproxymanifest) | A list of nodes. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `DependencyProxyManifestEdge` + +The edge type for [`DependencyProxyManifest`](#dependencyproxymanifest). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `cursor` | [`String!`](#string) | A cursor for use in pagination. | +| `node` | [`DependencyProxyManifest`](#dependencyproxymanifest) | The item at the end of the edge. | + #### `DesignAtVersionConnection` The connection type for [`DesignAtVersion`](#designatversion). @@ -6378,6 +6610,29 @@ The edge type for [`PackageTag`](#packagetag). | `cursor` | [`String!`](#string) | A cursor for use in pagination. | | `node` | [`PackageTag`](#packagetag) | The item at the end of the edge. | +#### `PagesDeploymentRegistryConnection` + +The connection type for [`PagesDeploymentRegistry`](#pagesdeploymentregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `edges` | [`[PagesDeploymentRegistryEdge]`](#pagesdeploymentregistryedge) | A list of edges. | +| `nodes` | [`[PagesDeploymentRegistry]`](#pagesdeploymentregistry) | A list of nodes. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `PagesDeploymentRegistryEdge` + +The edge type for [`PagesDeploymentRegistry`](#pagesdeploymentregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `cursor` | [`String!`](#string) | A cursor for use in pagination. | +| `node` | [`PagesDeploymentRegistry`](#pagesdeploymentregistry) | The item at the end of the edge. | + #### `PathLockConnection` The connection type for [`PathLock`](#pathlock). @@ -7188,6 +7443,29 @@ The edge type for [`TreeEntry`](#treeentry). | `cursor` | [`String!`](#string) | A cursor for use in pagination. | | `node` | [`TreeEntry`](#treeentry) | The item at the end of the edge. | +#### `UploadRegistryConnection` + +The connection type for [`UploadRegistry`](#uploadregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `edges` | [`[UploadRegistryEdge]`](#uploadregistryedge) | A list of edges. | +| `nodes` | [`[UploadRegistry]`](#uploadregistry) | A list of nodes. | +| `pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `UploadRegistryEdge` + +The edge type for [`UploadRegistry`](#uploadregistry). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `cursor` | [`String!`](#string) | A cursor for use in pagination. | +| `node` | [`UploadRegistry`](#uploadregistry) | The item at the end of the edge. | + #### `UsageTrendsMeasurementConnection` The connection type for [`UsageTrendsMeasurement`](#usagetrendsmeasurement). @@ -7406,6 +7684,19 @@ Configuration details for an Agent. | ---- | ---- | ----------- | | `agentName` | [`String`](#string) | Name of the agent. | +### `AgentMetadata` + +Information about a connected Agent. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `commit` | [`String`](#string) | Agent version commit. | +| `podName` | [`String`](#string) | Name of the pod running the Agent. | +| `podNamespace` | [`String`](#string) | Namespace of the pod running the Agent. | +| `version` | [`String`](#string) | Agent version tag. | + ### `AlertManagementAlert` Describes an alert from the project's Alert Management. @@ -7418,7 +7709,7 @@ Describes an alert from the project's Alert Management. | `createdAt` | [`Time`](#time) | Timestamp the alert was created. | | `description` | [`String`](#string) | Description of the alert. | | `details` | [`JSON`](#json) | Alert details. | -| `detailsUrl` | [`String!`](#string) | The URL of the alert detail page. | +| `detailsUrl` | [`String!`](#string) | URL of the alert detail page. | | `discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | `endedAt` | [`Time`](#time) | Timestamp the alert ended. | | `environment` | [`Environment`](#environment) | Environment for the alert. | @@ -7430,7 +7721,7 @@ Describes an alert from the project's Alert Management. | `metricsDashboardUrl` | [`String`](#string) | URL for metrics embed for the alert. | | `monitoringTool` | [`String`](#string) | Monitoring tool the alert came from. | | `notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | -| `prometheusAlert` | [`PrometheusAlert`](#prometheusalert) | The alert condition for Prometheus. | +| `prometheusAlert` | [`PrometheusAlert`](#prometheusalert) | Alert condition for Prometheus. | | `runbook` | [`String`](#string) | Runbook for the alert as defined in alert details. | | `service` | [`String`](#string) | Service the alert came from. | | `severity` | [`AlertManagementSeverity`](#alertmanagementseverity) | Severity of the alert. | @@ -7455,12 +7746,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| `authorId` | [`[ID!]`](#id) | The ID of an author. | -| `groupId` | [`[ID!]`](#id) | The ID of a group. | -| `projectId` | [`[ID!]`](#id) | The ID of a project. | -| `state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| `action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| `authorId` | [`[ID!]`](#id) | ID of an author. | +| `groupId` | [`[ID!]`](#id) | ID of a group. | +| `projectId` | [`[ID!]`](#id) | ID of a project. | +| `state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ### `AlertManagementAlertStatusCountsType` @@ -7491,7 +7782,7 @@ An endpoint and credentials used to accept alerts for a project. | `name` | [`String`](#string) | Name of the integration. | | `payloadAlertFields` | [`[AlertManagementPayloadAlertField!]`](#alertmanagementpayloadalertfield) | Extract alert fields from payload example for custom mapping. | | `payloadAttributeMappings` | [`[AlertManagementPayloadAlertMappingField!]`](#alertmanagementpayloadalertmappingfield) | The custom mapping of GitLab alert attributes to fields from the payload_example. | -| `payloadExample` | [`JsonString`](#jsonstring) | The example of an alert payload. | +| `payloadExample` | [`JsonString`](#jsonstring) | Example of an alert payload. | | `token` | [`String`](#string) | Token used to authenticate alert notification requests. | | `type` | [`AlertManagementIntegrationType!`](#alertmanagementintegrationtype) | Type of integration. | | `url` | [`String`](#string) | Endpoint which accepts alert notifications. | @@ -7516,7 +7807,7 @@ Parsed field (with its name) from an alert used for custom mappings. | Name | Type | Description | | ---- | ---- | ----------- | -| `fieldName` | [`AlertManagementPayloadAlertFieldName`](#alertmanagementpayloadalertfieldname) | A GitLab alert field name. | +| `fieldName` | [`AlertManagementPayloadAlertFieldName`](#alertmanagementpayloadalertfieldname) | GitLab alert field name. | | `label` | [`String`](#string) | Human-readable label of the payload path. | | `path` | [`[PayloadAlertFieldPathSegment!]`](#payloadalertfieldpathsegment) | Path to value inside payload JSON. | | `type` | [`AlertManagementPayloadAlertFieldType`](#alertmanagementpayloadalertfieldtype) | Type of the parsed value. | @@ -7556,9 +7847,9 @@ An API Fuzzing scan profile. | Name | Type | Description | | ---- | ---- | ----------- | -| `description` | [`String`](#string) | A short description of the profile. | -| `name` | [`String`](#string) | The unique name of the profile. | -| `yaml` | [`String`](#string) | A syntax highlit HTML representation of the YAML. | +| `description` | [`String`](#string) | Short description of the profile. | +| `name` | [`String`](#string) | Unique name of the profile. | +| `yaml` | [`String`](#string) | Syntax highlighted HTML representation of the YAML. | ### `ApprovalRule` @@ -7568,9 +7859,19 @@ Describes a rule for who can approve merge requests. | Name | Type | Description | | ---- | ---- | ----------- | +| `approvalsRequired` | [`Int`](#int) | Number of required approvals. | +| `approved` | [`Boolean`](#boolean) | Indicates if the rule is satisfied. | +| `approvedBy` | [`UserCoreConnection`](#usercoreconnection) | List of users defined in the rule that approved the merge request. (see [Connections](#connections)) | +| `containsHiddenGroups` | [`Boolean`](#boolean) | Indicates if the rule contains approvers from a hidden group. | +| `eligibleApprovers` | [`[UserCore!]`](#usercore) | List of all users eligible to approve the merge request (defined explicitly and from associated groups). | +| `groups` | [`GroupConnection`](#groupconnection) | List of groups added as approvers for the rule. (see [Connections](#connections)) | | `id` | [`GlobalID!`](#globalid) | ID of the rule. | | `name` | [`String`](#string) | Name of the rule. | +| `overridden` | [`Boolean`](#boolean) | Indicates if the rule was overridden for the merge request. | +| `section` | [`String`](#string) | Named section of the Code Owners file that the rule applies to. | +| `sourceRule` | [`ApprovalRule`](#approvalrule) | Source rule used to create the rule. | | `type` | [`ApprovalRuleType`](#approvalruletype) | Type of the rule. | +| `users` | [`UserCoreConnection`](#usercoreconnection) | List of users added as approvers for the rule. (see [Connections](#connections)) | ### `AwardEmoji` @@ -7580,12 +7881,12 @@ An emoji awarded by a user. | Name | Type | Description | | ---- | ---- | ----------- | -| `description` | [`String!`](#string) | The emoji description. | -| `emoji` | [`String!`](#string) | The emoji as an icon. | -| `name` | [`String!`](#string) | The emoji name. | -| `unicode` | [`String!`](#string) | The emoji in Unicode. | -| `unicodeVersion` | [`String!`](#string) | The Unicode version for this emoji. | -| `user` | [`UserCore!`](#usercore) | The user who awarded the emoji. | +| `description` | [`String!`](#string) | Emoji description. | +| `emoji` | [`String!`](#string) | Emoji as an icon. | +| `name` | [`String!`](#string) | Emoji name. | +| `unicode` | [`String!`](#string) | Emoji in Unicode. | +| `unicodeVersion` | [`String!`](#string) | Unicode version for this emoji. | +| `user` | [`UserCore!`](#usercore) | User who awarded the emoji. | ### `BaseService` @@ -7637,14 +7938,15 @@ Represents a project or group issue board. | Name | Type | Description | | ---- | ---- | ----------- | -| `assignee` | [`UserCore`](#usercore) | The board assignee. | +| `assignee` | [`UserCore`](#usercore) | Board assignee. | | `createdAt` | [`Time!`](#time) | Timestamp of when the board was created. | | `hideBacklogList` | [`Boolean`](#boolean) | Whether or not backlog list is hidden. | | `hideClosedList` | [`Boolean`](#boolean) | Whether or not closed list is hidden. | | `id` | [`ID!`](#id) | ID (global ID) of the board. | -| `iteration` | [`Iteration`](#iteration) | The board iteration. | +| `iteration` | [`Iteration`](#iteration) | Board iteration. | +| `iterationCadence` | [`IterationCadence`](#iterationcadence) | Board iteration cadence. | | `labels` | [`LabelConnection`](#labelconnection) | Labels of the board. (see [Connections](#connections)) | -| `milestone` | [`Milestone`](#milestone) | The board milestone. | +| `milestone` | [`Milestone`](#milestone) | Board milestone. | | `name` | [`String`](#string) | Name of the board. | | `updatedAt` | [`Time!`](#time) | Timestamp of when the board was last updated. | | `webPath` | [`String!`](#string) | Web path of the board. | @@ -7695,7 +7997,7 @@ Represents an epic on an issue board. | Name | Type | Description | | ---- | ---- | ----------- | | `author` | [`UserCore!`](#usercore) | Author of the epic. | -| `awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | A list of award emojis associated with the epic. (see [Connections](#connections)) | +| `awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of award emojis associated with the epic. (see [Connections](#connections)) | | `closedAt` | [`Time`](#time) | Timestamp of when the epic was closed. | | `confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | | `createdAt` | [`Time`](#time) | Timestamp of when the epic was created. | @@ -7709,7 +8011,7 @@ Represents an epic on an issue board. | `dueDateFixed` | [`Time`](#time) | Fixed due date of the epic. | | `dueDateFromMilestones` | [`Time`](#time) | Inherited due date of the epic from milestones. | | `dueDateIsFixed` | [`Boolean`](#boolean) | Indicates if the due date has been manually set. | -| `events` | [`EventConnection`](#eventconnection) | A list of events associated with the object. (see [Connections](#connections)) | +| `events` | [`EventConnection`](#eventconnection) | List of events associated with the object. (see [Connections](#connections)) | | `group` | [`Group!`](#group) | Group to which the epic belongs. | | `hasChildren` | [`Boolean!`](#boolean) | Indicates if the epic has children. | | `hasIssues` | [`Boolean!`](#boolean) | Indicates if the epic has direct issues. | @@ -7723,7 +8025,7 @@ Represents an epic on an issue board. | `parent` | [`Epic`](#epic) | Parent epic of the epic. | | `participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants for the epic. (see [Connections](#connections)) | | `relationPath` | [`String`](#string) | URI path of the epic-issue relationship. | -| `relativePosition` | [`Int`](#int) | The relative position of the epic in the epic tree. | +| `relativePosition` | [`Int`](#int) | Relative position of the epic in the epic tree. | | `startDate` | [`Time`](#time) | Start date of the epic. | | `startDateFixed` | [`Time`](#time) | Fixed start date of the epic. | | `startDateFromMilestones` | [`Time`](#time) | Inherited start date of the epic from milestones. | @@ -7861,7 +8163,7 @@ Represents a list for an issue board. | `issuesCount` | [`Int`](#int) | Count of issues in the list. | | `iteration` | [`Iteration`](#iteration) | Iteration of the list. | | `label` | [`Label`](#label) | Label of the list. | -| `limitMetric` | [`ListLimitMetric`](#listlimitmetric) | The current limit metric for the list. | +| `limitMetric` | [`ListLimitMetric`](#listlimitmetric) | Current limit metric for the list. | | `listType` | [`String!`](#string) | Type of the list. | | `maxIssueCount` | [`Int`](#int) | Maximum number of issues in the list. | | `maxIssueWeight` | [`Int`](#int) | Maximum weight of issues in the list. | @@ -7975,7 +8277,7 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | -| `refs` | [`[String!]`](#string) | The Git refs the job restriction applies to. | +| `refs` | [`[String!]`](#string) | Git refs the job restriction applies to. | ### `CiConfigNeed` @@ -8068,8 +8370,8 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | -| `minutes` | [`Int`](#int) | The total number of minutes used by all projects in the namespace. | -| `month` | [`String`](#string) | The month related to the usage data. | +| `minutes` | [`Int`](#int) | Total number of minutes used by all projects in the namespace. | +| `month` | [`String`](#string) | Month related to the usage data. | | `projects` | [`CiMinutesProjectMonthlyUsageConnection`](#ciminutesprojectmonthlyusageconnection) | CI minutes usage data for projects in the namespace. (see [Connections](#connections)) | ### `CiMinutesProjectMonthlyUsage` @@ -8078,8 +8380,8 @@ Represents the total number of issues and their weights for a particular day. | Name | Type | Description | | ---- | ---- | ----------- | -| `minutes` | [`Int`](#int) | The number of CI minutes used by the project in the month. | -| `name` | [`String`](#string) | The name of the project. | +| `minutes` | [`Int`](#int) | Number of CI minutes used by the project in the month. | +| `name` | [`String`](#string) | Name of the project. | ### `CiRunner` @@ -8137,11 +8439,12 @@ GitLab CI/CD configuration template. | Name | Type | Description | | ---- | ---- | ----------- | +| `connections` | [`ConnectedAgentConnection`](#connectedagentconnection) | Active connections for the cluster agent. (see [Connections](#connections)) | | `createdAt` | [`Time`](#time) | Timestamp the cluster agent was created. | | `createdByUser` | [`UserCore`](#usercore) | User object, containing information about the person who created the agent. | | `id` | [`ID!`](#id) | ID of the cluster agent. | | `name` | [`String`](#string) | Name of the cluster agent. | -| `project` | [`Project`](#project) | The project this cluster agent is associated with. | +| `project` | [`Project`](#project) | Project this cluster agent is associated with. | | `tokens` | [`ClusterAgentTokenConnection`](#clusteragenttokenconnection) | Tokens associated with the cluster agent. (see [Connections](#connections)) | | `updatedAt` | [`Time`](#time) | Timestamp the cluster agent was updated. | | `webPath` | [`String`](#string) | Web path of the cluster agent. | @@ -8154,7 +8457,7 @@ GitLab CI/CD configuration template. | ---- | ---- | ----------- | | `clusterAgent` | [`ClusterAgent`](#clusteragent) | Cluster agent this token is associated with. | | `createdAt` | [`Time`](#time) | Timestamp the token was created. | -| `createdByUser` | [`UserCore`](#usercore) | The user who created the token. | +| `createdByUser` | [`UserCore`](#usercore) | User who created the token. | | `description` | [`String`](#string) | Description of the token. | | `id` | [`ClustersAgentTokenID!`](#clustersagenttokenid) | Global ID of the token. | | `lastUsedAt` | [`Time`](#time) | Timestamp the token was last used. | @@ -8193,10 +8496,10 @@ Represents a code quality degradation on the pipeline. | Name | Type | Description | | ---- | ---- | ----------- | -| `description` | [`String!`](#string) | A description of the code quality degradation. | -| `fingerprint` | [`String!`](#string) | A unique fingerprint to identify the code quality degradation. For example, an MD5 hash. | -| `line` | [`Int!`](#int) | The line on which the code quality degradation occurred. | -| `path` | [`String!`](#string) | The relative path to the file containing the code quality degradation. | +| `description` | [`String!`](#string) | Description of the code quality degradation. | +| `fingerprint` | [`String!`](#string) | Unique fingerprint to identify the code quality degradation. For example, an MD5 hash. | +| `line` | [`Int!`](#int) | Line on which the code quality degradation occurred. | +| `path` | [`String!`](#string) | Relative path to the file containing the code quality degradation. | | `severity` | [`CodeQualityDegradationSeverity!`](#codequalitydegradationseverity) | Status of the degradation (BLOCKER, CRITICAL, MAJOR, MINOR, INFO). | ### `Commit` @@ -8239,6 +8542,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | | `sha` | [`String`](#string) | Filter pipelines by the sha of the commit they are run for. | +| `source` | [`String`](#string) | Filter pipelines by their source. Will be ignored if `dast_view_scans` feature flag is disabled. | | `status` | [`PipelineStatusEnum`](#pipelinestatusenum) | Filter pipelines by their status. | ### `ComplianceFramework` @@ -8298,6 +8602,18 @@ Conan metadata. | `recipePath` | [`String!`](#string) | Recipe path of the Conan package. | | `updatedAt` | [`Time!`](#time) | Date of most recent update. | +### `ConnectedAgent` + +Connection details for an Agent. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `connectedAt` | [`Time`](#time) | When the connection was established. | +| `connectionId` | [`BigInt`](#bigint) | ID of the connection. | +| `metadata` | [`AgentMetadata`](#agentmetadata) | Information about the Agent. | + ### `ContainerExpirationPolicy` A tag expiration policy designed to keep only the images that matter most. @@ -8326,7 +8642,7 @@ A container repository. | ---- | ---- | ----------- | | `canDelete` | [`Boolean!`](#boolean) | Can the current user delete the container repository. | | `createdAt` | [`Time!`](#time) | Timestamp when the container repository was created. | -| `expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | The tags cleanup status for the container repository. | +| `expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | Tags cleanup status for the container repository. | | `expirationPolicyStartedAt` | [`Time`](#time) | Timestamp when the cleanup done by the expiration policy was started on the container repository. | | `id` | [`ID!`](#id) | ID of the container repository. | | `location` | [`String!`](#string) | URL of the container repository. | @@ -8347,7 +8663,7 @@ Details of a container repository. | ---- | ---- | ----------- | | `canDelete` | [`Boolean!`](#boolean) | Can the current user delete the container repository. | | `createdAt` | [`Time!`](#time) | Timestamp when the container repository was created. | -| `expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | The tags cleanup status for the container repository. | +| `expirationPolicyCleanupStatus` | [`ContainerRepositoryCleanupStatus`](#containerrepositorycleanupstatus) | Tags cleanup status for the container repository. | | `expirationPolicyStartedAt` | [`Time`](#time) | Timestamp when the cleanup done by the expiration policy was started on the container repository. | | `id` | [`ID!`](#id) | ID of the container repository. | | `location` | [`String!`](#string) | URL of the container repository. | @@ -8375,7 +8691,7 @@ A tag from a container repository. | `path` | [`String!`](#string) | Path of the tag. | | `revision` | [`String`](#string) | Revision of the tag. | | `shortRevision` | [`String`](#string) | Short revision of the tag. | -| `totalSize` | [`BigInt`](#bigint) | The size of the tag. | +| `totalSize` | [`BigInt`](#bigint) | Size of the tag. | ### `CurrentLicense` @@ -8410,9 +8726,38 @@ A custom emoji uploaded by user. | Name | Type | Description | | ---- | ---- | ----------- | | `external` | [`Boolean!`](#boolean) | Whether the emoji is an external link. | -| `id` | [`CustomEmojiID!`](#customemojiid) | The ID of the emoji. | -| `name` | [`String!`](#string) | The name of the emoji. | -| `url` | [`String!`](#string) | The link to file of the emoji. | +| `id` | [`CustomEmojiID!`](#customemojiid) | ID of the emoji. | +| `name` | [`String!`](#string) | Name of the emoji. | +| `url` | [`String!`](#string) | Link to file of the emoji. | + +### `CustomerRelationsContact` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `createdAt` | [`Time!`](#time) | Timestamp the contact was created. | +| `description` | [`String`](#string) | Description or notes for the contact. | +| `email` | [`String`](#string) | Email address of the contact. | +| `firstName` | [`String!`](#string) | First name of the contact. | +| `id` | [`ID!`](#id) | Internal ID of the contact. | +| `lastName` | [`String!`](#string) | Last name of the contact. | +| `organization` | [`CustomerRelationsOrganization`](#customerrelationsorganization) | Organization of the contact. | +| `phone` | [`String`](#string) | Phone number of the contact. | +| `updatedAt` | [`Time!`](#time) | Timestamp the contact was last updated. | + +### `CustomerRelationsOrganization` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `createdAt` | [`Time!`](#time) | Timestamp the organization was created. | +| `defaultRate` | [`Float`](#float) | Standard billing rate for the organization. | +| `description` | [`String`](#string) | Description or notes for the organization. | +| `id` | [`ID!`](#id) | Internal ID of the organization. | +| `name` | [`String!`](#string) | Name of the organization. | +| `updatedAt` | [`Time!`](#time) | Timestamp the organization was last updated. | ### `DastProfile` @@ -8422,13 +8767,14 @@ Represents a DAST Profile. | Name | Type | Description | | ---- | ---- | ----------- | -| `branch` | [`DastProfileBranch`](#dastprofilebranch) | The associated branch. | -| `dastScannerProfile` | [`DastScannerProfile`](#dastscannerprofile) | The associated scanner profile. | -| `dastSiteProfile` | [`DastSiteProfile`](#dastsiteprofile) | The associated site profile. | -| `description` | [`String`](#string) | The description of the scan. | +| `branch` | [`DastProfileBranch`](#dastprofilebranch) | Associated branch. | +| `dastProfileSchedule` | [`DastProfileSchedule`](#dastprofileschedule) | Associated profile schedule. Will always return `null` if `dast_on_demand_scans_scheduler` feature flag is disabled. | +| `dastScannerProfile` | [`DastScannerProfile`](#dastscannerprofile) | Associated scanner profile. | +| `dastSiteProfile` | [`DastSiteProfile`](#dastsiteprofile) | Associated site profile. | +| `description` | [`String`](#string) | Description of the scan. | | `editPath` | [`String`](#string) | Relative web path to the edit page of a profile. | | `id` | [`DastProfileID!`](#dastprofileid) | ID of the profile. | -| `name` | [`String`](#string) | The name of the profile. | +| `name` | [`String`](#string) | Name of the profile. | ### `DastProfileBranch` @@ -8439,7 +8785,33 @@ Represents a DAST Profile Branch. | Name | Type | Description | | ---- | ---- | ----------- | | `exists` | [`Boolean`](#boolean) | Indicates whether or not the branch exists. | -| `name` | [`String`](#string) | The name of the branch. | +| `name` | [`String`](#string) | Name of the branch. | + +### `DastProfileCadence` + +Represents DAST Profile Cadence. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `duration` | [`Int`](#int) | Duration of the DAST profile cadence. | +| `unit` | [`DastProfileCadenceUnit`](#dastprofilecadenceunit) | Unit for the duration of DAST profile cadence. | + +### `DastProfileSchedule` + +Represents a DAST profile schedule. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `active` | [`Boolean`](#boolean) | Status of the DAST profile schedule. | +| `cadence` | [`DastProfileCadence`](#dastprofilecadence) | Cadence of the DAST profile schedule. | +| `id` | [`DastProfileScheduleID!`](#dastprofilescheduleid) | ID of the DAST profile schedule. | +| `nextRunAt` | [`Time`](#time) | Next run time of the DAST profile schedule in the given timezone. | +| `startsAt` | [`Time`](#time) | Start time of the DAST profile schedule in the given timezone. | +| `timezone` | [`String`](#string) | Time zone of the start time of the DAST profile schedule. | ### `DastScannerProfile` @@ -8455,8 +8827,8 @@ Represents a DAST scanner profile. | `referencedInSecurityPolicies` | [`[String!]`](#string) | List of security policy names that are referencing given project. | | `scanType` | [`DastScanTypeEnum`](#dastscantypeenum) | Indicates the type of DAST scan that will run. Either a Passive Scan or an Active Scan. | | `showDebugMessages` | [`Boolean!`](#boolean) | Indicates if debug messages should be included in DAST console output. True to include the debug messages. | -| `spiderTimeout` | [`Int`](#int) | The maximum number of minutes allowed for the spider to traverse the site. | -| `targetTimeout` | [`Int`](#int) | The maximum number of seconds allowed for the site under test to respond to a request. | +| `spiderTimeout` | [`Int`](#int) | Maximum number of minutes allowed for the spider to traverse the site. | +| `targetTimeout` | [`Int`](#int) | Maximum number of seconds allowed for the site under test to respond to a request. | | `useAjaxSpider` | [`Boolean!`](#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. | ### `DastSiteProfile` @@ -8469,16 +8841,16 @@ Represents a DAST Site Profile. | ---- | ---- | ----------- | | `auth` | [`DastSiteProfileAuth`](#dastsiteprofileauth) | Target authentication details. | | `editPath` | [`String`](#string) | Relative web path to the edit page of a site profile. | -| `excludedUrls` | [`[String!]`](#string) | The URLs to skip during an authenticated scan. | +| `excludedUrls` | [`[String!]`](#string) | URLs to skip during an authenticated scan. | | `id` | [`DastSiteProfileID!`](#dastsiteprofileid) | ID of the site profile. | | `normalizedTargetUrl` | [`String`](#string) | Normalized URL of the target to be scanned. | -| `profileName` | [`String`](#string) | The name of the site profile. | +| `profileName` | [`String`](#string) | Name of the site profile. | | `referencedInSecurityPolicies` | [`[String!]`](#string) | List of security policy names that are referencing given project. | | `requestHeaders` | [`String`](#string) | Comma-separated list of request header names and values to be added to every request made by DAST. | -| `targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | The type of target to be scanned. | -| `targetUrl` | [`String`](#string) | The URL of the target to be scanned. | +| `targetType` | [`DastTargetTypeEnum`](#dasttargettypeenum) | Type of target to be scanned. | +| `targetUrl` | [`String`](#string) | URL of the target to be scanned. | | `userPermissions` | [`DastSiteProfilePermissions!`](#dastsiteprofilepermissions) | Permissions for the current user on the resource. | -| `validationStatus` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | The current validation status of the site profile. | +| `validationStatus` | [`DastSiteProfileValidationStatusEnum`](#dastsiteprofilevalidationstatusenum) | Current validation status of the site profile. | ### `DastSiteProfileAuth` @@ -8490,10 +8862,10 @@ Input type for DastSiteProfile authentication. | ---- | ---- | ----------- | | `enabled` | [`Boolean`](#boolean) | Indicates whether authentication is enabled. | | `password` | [`String`](#string) | Redacted password to authenticate with on the target website. | -| `passwordField` | [`String`](#string) | The name of password field at the sign-in HTML form. | +| `passwordField` | [`String`](#string) | Name of password field at the sign-in HTML form. | | `url` | [`String`](#string) | The URL of the page containing the sign-in HTML form on the target website. | -| `username` | [`String`](#string) | The username to authenticate with on the target website. | -| `usernameField` | [`String`](#string) | The name of username field at the sign-in HTML form. | +| `username` | [`String`](#string) | Username to authenticate with on the target website. | +| `usernameField` | [`String`](#string) | Name of username field at the sign-in HTML form. | ### `DastSiteProfilePermissions` @@ -8526,8 +8898,59 @@ The response from the AdminSidekiqQueuesDeleteJobs mutation. | Name | Type | Description | | ---- | ---- | ----------- | | `completed` | [`Boolean`](#boolean) | Whether or not the entire queue was processed in time; if not, retrying the same request is safe. | -| `deletedJobs` | [`Int`](#int) | The number of matching jobs deleted. | -| `queueSize` | [`Int`](#int) | The queue size after processing. | +| `deletedJobs` | [`Int`](#int) | Number of matching jobs deleted. | +| `queueSize` | [`Int`](#int) | Queue size after processing. | + +### `DependencyProxyBlob` + +Dependency proxy blob. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `createdAt` | [`Time!`](#time) | Date of creation. | +| `fileName` | [`String!`](#string) | Name of the blob. | +| `size` | [`String!`](#string) | Size of the blob file. | +| `updatedAt` | [`Time!`](#time) | Date of most recent update. | + +### `DependencyProxyImageTtlGroupPolicy` + +Group-level Dependency Proxy TTL policy settings. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `createdAt` | [`Time`](#time) | Timestamp of creation. | +| `enabled` | [`Boolean!`](#boolean) | Indicates whether the policy is enabled or disabled. | +| `ttl` | [`Int`](#int) | Number of days to retain a cached image file. | +| `updatedAt` | [`Time`](#time) | Timestamp of the most recent update. | + +### `DependencyProxyManifest` + +Dependency proxy manifest. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `createdAt` | [`Time!`](#time) | Date of creation. | +| `digest` | [`String!`](#string) | Digest of the manifest. | +| `fileName` | [`String!`](#string) | Name of the manifest. | +| `imageName` | [`String!`](#string) | Name of the image. | +| `size` | [`String!`](#string) | Size of the manifest file. | +| `updatedAt` | [`Time!`](#time) | Date of most recent update. | + +### `DependencyProxySetting` + +Group-level Dependency Proxy settings. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `enabled` | [`Boolean!`](#boolean) | Indicates whether the dependency proxy is enabled for the group. | ### `Design` @@ -8537,18 +8960,18 @@ A single design. | Name | Type | Description | | ---- | ---- | ----------- | -| `diffRefs` | [`DiffRefs!`](#diffrefs) | The diff refs for this design. | +| `diffRefs` | [`DiffRefs!`](#diffrefs) | Diff refs for this design. | | `discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | `event` | [`DesignVersionEvent!`](#designversionevent) | How this design was changed in the current version. | -| `filename` | [`String!`](#string) | The filename of the design. | -| `fullPath` | [`String!`](#string) | The full path to the design file. | -| `id` | [`ID!`](#id) | The ID of this design. | -| `image` | [`String!`](#string) | The URL of the full-sized image. | +| `filename` | [`String!`](#string) | Filename of the design. | +| `fullPath` | [`String!`](#string) | Full path to the design file. | +| `id` | [`ID!`](#id) | ID of this design. | +| `image` | [`String!`](#string) | URL of the full-sized image. | | `imageV432x230` | [`String`](#string) | The URL of the design resized to fit within the bounds of 432x230. This will be `null` if the image has not been generated. | -| `issue` | [`Issue!`](#issue) | The issue the design belongs to. | +| `issue` | [`Issue!`](#issue) | Issue the design belongs to. | | `notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | -| `notesCount` | [`Int!`](#int) | The total count of user-created notes for this design. | -| `project` | [`Project!`](#project) | The project the design belongs to. | +| `notesCount` | [`Int!`](#int) | Total count of user-created notes for this design. | +| `project` | [`Project!`](#project) | Project the design belongs to. | #### Fields with arguments @@ -8593,18 +9016,18 @@ A design pinned to a specific version. The image field reflects the design as of | Name | Type | Description | | ---- | ---- | ----------- | -| `design` | [`Design!`](#design) | The underlying design. | -| `diffRefs` | [`DiffRefs!`](#diffrefs) | The diff refs for this design. | +| `design` | [`Design!`](#design) | Underlying design. | +| `diffRefs` | [`DiffRefs!`](#diffrefs) | Diff refs for this design. | | `event` | [`DesignVersionEvent!`](#designversionevent) | How this design was changed in the current version. | -| `filename` | [`String!`](#string) | The filename of the design. | -| `fullPath` | [`String!`](#string) | The full path to the design file. | -| `id` | [`ID!`](#id) | The ID of this design. | -| `image` | [`String!`](#string) | The URL of the full-sized image. | +| `filename` | [`String!`](#string) | Filename of the design. | +| `fullPath` | [`String!`](#string) | Full path to the design file. | +| `id` | [`ID!`](#id) | ID of this design. | +| `image` | [`String!`](#string) | URL of the full-sized image. | | `imageV432x230` | [`String`](#string) | The URL of the design resized to fit within the bounds of 432x230. This will be `null` if the image has not been generated. | -| `issue` | [`Issue!`](#issue) | The issue the design belongs to. | -| `notesCount` | [`Int!`](#int) | The total count of user-created notes for this design. | -| `project` | [`Project!`](#project) | The project the design belongs to. | -| `version` | [`DesignVersion!`](#designversion) | The version this design-at-versions is pinned to. | +| `issue` | [`Issue!`](#issue) | Issue the design belongs to. | +| `notesCount` | [`Int!`](#int) | Total count of user-created notes for this design. | +| `project` | [`Project!`](#project) | Project the design belongs to. | +| `version` | [`DesignVersion!`](#designversion) | Version this design-at-versions is pinned to. | ### `DesignCollection` @@ -8830,16 +9253,16 @@ Snapshot. | `dastEnabledCount` | [`Int`](#int) | Total number of projects with enabled DAST. | | `dependencyScanningEnabledCount` | [`Int`](#int) | Total number of projects with enabled dependency scanning. | | `deploySucceeded` | [`Boolean!`](#boolean) | At least one deployment succeeded. | -| `endTime` | [`Time!`](#time) | The end time for the snapshot where the data points were collected. | +| `endTime` | [`Time!`](#time) | End time for the snapshot where the data points were collected. | | `issueOpened` | [`Boolean!`](#boolean) | At least one issue was opened. | | `mergeRequestApproved` | [`Boolean!`](#boolean) | At least one merge request was approved. | | `mergeRequestOpened` | [`Boolean!`](#boolean) | At least one merge request was opened. | | `pipelineSucceeded` | [`Boolean!`](#boolean) | At least one pipeline succeeded. | -| `recordedAt` | [`Time!`](#time) | The time the snapshot was recorded. | +| `recordedAt` | [`Time!`](#time) | Time the snapshot was recorded. | | `runnerConfigured` | [`Boolean!`](#boolean) | At least one runner was used. | | `sastEnabledCount` | [`Int`](#int) | Total number of projects with enabled SAST. | | `securityScanSucceeded` **{warning-solid}** | [`Boolean!`](#boolean) | **Deprecated** in 14.1. Substituted with specific security metrics. Always false. | -| `startTime` | [`Time!`](#time) | The start time for the snapshot where the data points were collected. | +| `startTime` | [`Time!`](#time) | Start time for the snapshot where the data points were collected. | | `totalProjectsCount` | [`Int`](#int) | Total number of projects. | | `vulnerabilityManagementUsedCount` | [`Int`](#int) | Total number of projects with vulnerability management used at least once. | @@ -8929,9 +9352,9 @@ Returns [`[DoraMetric!]`](#dorametric). | Name | Type | Description | | ---- | ---- | ----------- | | `endDate` | [`Date`](#date) | Date range to end at. Default is the current date. | -| `environmentTier` | [`DeploymentTier`](#deploymenttier) | The deployment tier of the environments to return. Defaults to `PRODUCTION`. | +| `environmentTier` | [`DeploymentTier`](#deploymenttier) | Deployment tier of the environments to return. Defaults to `PRODUCTION`. | | `interval` | [`DoraMetricBucketingInterval`](#dorametricbucketinginterval) | How the metric should be aggregrated. Defaults to `DAILY`. In the case of `ALL`, the `date` field in the response will be `null`. | -| `metric` | [`DoraMetricType!`](#dorametrictype) | The type of metric to return. | +| `metric` | [`DoraMetricType!`](#dorametrictype) | Type of metric to return. | | `startDate` | [`Date`](#date) | Date range to start from. Default is 3 months ago. | ### `DoraMetric` @@ -8952,9 +9375,9 @@ Describes where code is deployed for a project. | Name | Type | Description | | ---- | ---- | ----------- | | `id` | [`ID!`](#id) | ID of the environment. | -| `latestOpenedMostSevereAlert` | [`AlertManagementAlert`](#alertmanagementalert) | The most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. | +| `latestOpenedMostSevereAlert` | [`AlertManagementAlert`](#alertmanagementalert) | Most severe open alert for the environment. If multiple alerts have equal severity, the most recent is returned. | | `name` | [`String!`](#string) | Human-readable name of the environment. | -| `path` | [`String!`](#string) | The path to the environment. | +| `path` | [`String!`](#string) | Path to the environment. | | `state` | [`String!`](#string) | State of the environment, for example: available/stopped. | #### Fields with arguments @@ -8980,7 +9403,7 @@ Represents an epic. | Name | Type | Description | | ---- | ---- | ----------- | | `author` | [`UserCore!`](#usercore) | Author of the epic. | -| `awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | A list of award emojis associated with the epic. (see [Connections](#connections)) | +| `awardEmoji` | [`AwardEmojiConnection`](#awardemojiconnection) | List of award emojis associated with the epic. (see [Connections](#connections)) | | `closedAt` | [`Time`](#time) | Timestamp of when the epic was closed. | | `confidential` | [`Boolean`](#boolean) | Indicates if the epic is confidential. | | `createdAt` | [`Time`](#time) | Timestamp of when the epic was created. | @@ -8994,7 +9417,7 @@ Represents an epic. | `dueDateFixed` | [`Time`](#time) | Fixed due date of the epic. | | `dueDateFromMilestones` | [`Time`](#time) | Inherited due date of the epic from milestones. | | `dueDateIsFixed` | [`Boolean`](#boolean) | Indicates if the due date has been manually set. | -| `events` | [`EventConnection`](#eventconnection) | A list of events associated with the object. (see [Connections](#connections)) | +| `events` | [`EventConnection`](#eventconnection) | List of events associated with the object. (see [Connections](#connections)) | | `group` | [`Group!`](#group) | Group to which the epic belongs. | | `hasChildren` | [`Boolean!`](#boolean) | Indicates if the epic has children. | | `hasIssues` | [`Boolean!`](#boolean) | Indicates if the epic has direct issues. | @@ -9008,7 +9431,7 @@ Represents an epic. | `parent` | [`Epic`](#epic) | Parent epic of the epic. | | `participants` | [`UserCoreConnection`](#usercoreconnection) | List of participants for the epic. (see [Connections](#connections)) | | `relationPath` | [`String`](#string) | URI path of the epic-issue relationship. | -| `relativePosition` | [`Int`](#int) | The relative position of the epic in the epic tree. | +| `relativePosition` | [`Int`](#int) | Relative position of the epic in the epic tree. | | `startDate` | [`Time`](#time) | Start date of the epic. | | `startDateFixed` | [`Time`](#time) | Fixed start date of the epic. | | `startDateFromMilestones` | [`Time`](#time) | Inherited start date of the epic from milestones. | @@ -9222,6 +9645,7 @@ Relationship between an epic and an issue. | `epic` | [`Epic`](#epic) | Epic to which this issue belongs. | | `epicIssueId` | [`ID!`](#id) | ID of the epic-issue relation. | | `healthStatus` | [`HealthStatus`](#healthstatus) | Current health status. | +| `hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. Will always return `null` if `ban_user_feature_flag` feature flag is disabled. | | `humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the issue. | | `humanTotalTimeSpent` | [`String`](#string) | Human-readable total time reported as spent on the issue. | | `id` | [`ID`](#id) | Global ID of the epic-issue relation. | @@ -9349,9 +9773,9 @@ Represents an escalation policy. | Name | Type | Description | | ---- | ---- | ----------- | -| `description` | [`String`](#string) | The description of the escalation policy. | +| `description` | [`String`](#string) | Description of the escalation policy. | | `id` | [`IncidentManagementEscalationPolicyID`](#incidentmanagementescalationpolicyid) | ID of the escalation policy. | -| `name` | [`String`](#string) | The name of the escalation policy. | +| `name` | [`String`](#string) | Name of the escalation policy. | | `rules` | [`[EscalationRuleType!]`](#escalationruletype) | Steps of the escalation policy. | ### `EscalationRuleType` @@ -9362,11 +9786,11 @@ Represents an escalation rule for an escalation policy. | Name | Type | Description | | ---- | ---- | ----------- | -| `elapsedTimeSeconds` | [`Int`](#int) | The time in seconds before the rule is activated. | +| `elapsedTimeSeconds` | [`Int`](#int) | Time in seconds before the rule is activated. | | `id` | [`IncidentManagementEscalationRuleID`](#incidentmanagementescalationruleid) | ID of the escalation policy. | -| `oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | The on-call schedule to notify. | -| `status` | [`EscalationRuleStatus`](#escalationrulestatus) | The status required to prevent the rule from activating. | -| `user` | [`UserCore`](#usercore) | The user to notify. | +| `oncallSchedule` | [`IncidentManagementOncallSchedule`](#incidentmanagementoncallschedule) | On-call schedule to notify. | +| `status` | [`EscalationRuleStatus`](#escalationrulestatus) | Status required to prevent the rule from activating. | +| `user` | [`UserCore`](#usercore) | User to notify. | ### `Event` @@ -9404,21 +9828,21 @@ Represents an external issue. | Name | Type | Description | | ---- | ---- | ----------- | -| `containerRepositoriesMaxCapacity` | [`Int`](#int) | The maximum concurrency of container repository sync for this secondary node. | +| `containerRepositoriesMaxCapacity` | [`Int`](#int) | Maximum concurrency of container repository sync for this secondary node. | | `enabled` | [`Boolean`](#boolean) | Indicates whether this Geo node is enabled. | -| `filesMaxCapacity` | [`Int`](#int) | The maximum concurrency of LFS/attachment backfill for this secondary node. | +| `filesMaxCapacity` | [`Int`](#int) | Maximum concurrency of LFS/attachment backfill for this secondary node. | | `id` | [`ID!`](#id) | ID of this GeoNode. | -| `internalUrl` | [`String`](#string) | The URL defined on the primary node that secondary nodes should use to contact it. | -| `minimumReverificationInterval` | [`Int`](#int) | The interval (in days) in which the repository verification is valid. Once expired, it will be reverified. | -| `name` | [`String`](#string) | The unique identifier for this Geo node. | +| `internalUrl` | [`String`](#string) | URL defined on the primary node secondary nodes should use to contact it. | +| `minimumReverificationInterval` | [`Int`](#int) | Interval (in days) in which the repository verification is valid. After expiry, it is reverted. | +| `name` | [`String`](#string) | Unique identifier for this Geo node. | | `primary` | [`Boolean`](#boolean) | Indicates whether this Geo node is the primary. | -| `reposMaxCapacity` | [`Int`](#int) | The maximum concurrency of repository backfill for this secondary node. | -| `selectiveSyncNamespaces` | [`NamespaceConnection`](#namespaceconnection) | The namespaces that should be synced, if `selective_sync_type` == `namespaces`. (see [Connections](#connections)) | -| `selectiveSyncShards` | [`[String!]`](#string) | The repository storages whose projects should be synced, if `selective_sync_type` == `shards`. | +| `reposMaxCapacity` | [`Int`](#int) | Maximum concurrency of repository backfill for this secondary node. | +| `selectiveSyncNamespaces` | [`NamespaceConnection`](#namespaceconnection) | Namespaces that should be synced, if `selective_sync_type` == `namespaces`. (see [Connections](#connections)) | +| `selectiveSyncShards` | [`[String!]`](#string) | Repository storages whose projects should be synced, if `selective_sync_type` == `shards`. | | `selectiveSyncType` | [`String`](#string) | Indicates if syncing is limited to only specific groups, or shards. | | `syncObjectStorage` | [`Boolean`](#boolean) | Indicates if this secondary node will replicate blobs in Object Storage. | -| `url` | [`String`](#string) | The user-facing URL for this Geo node. | -| `verificationMaxCapacity` | [`Int`](#int) | The maximum concurrency of repository verification for this secondary node. | +| `url` | [`String`](#string) | User-facing URL for this Geo node. | +| `verificationMaxCapacity` | [`Int`](#int) | Maximum concurrency of repository verification for this secondary node. | #### Fields with arguments @@ -9486,6 +9910,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `ids` | [`[ID!]`](#id) | Filters registries by their ID. | +##### `GeoNode.pagesDeploymentRegistries` + +Find Pages Deployment registries on this Geo node. + +Returns [`PagesDeploymentRegistryConnection`](#pagesdeploymentregistryconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `ids` | [`[ID!]`](#id) | Filters registries by their ID. | + ##### `GeoNode.pipelineArtifactRegistries` Find pipeline artifact registries on this Geo node. @@ -9534,6 +9974,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `ids` | [`[ID!]`](#id) | Filters registries by their ID. | +##### `GeoNode.uploadRegistries` + +Find Upload registries on this Geo node Available only when feature flag `geo_upload_replication` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. + +Returns [`UploadRegistryConnection`](#uploadregistryconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `ids` | [`[ID!]`](#id) | Filters registries by their ID. | + ### `GrafanaIntegration` #### Fields @@ -9556,13 +10012,22 @@ four standard [pagination arguments](#connection-pagination-arguments): | `additionalPurchasedStorageSize` | [`Float`](#float) | Additional storage purchased for the root namespace in bytes. | | `autoDevopsEnabled` | [`Boolean`](#boolean) | Indicates whether Auto DevOps is enabled for all projects within this group. | | `avatarUrl` | [`String`](#string) | Avatar URL of the group. | -| `billableMembersCount` | [`Int`](#int) | The number of billable users in the group. | +| `billableMembersCount` | [`Int`](#int) | Number of billable users in the group. | +| `contacts` | [`CustomerRelationsContactConnection`](#customerrelationscontactconnection) | Find contacts of this group. (see [Connections](#connections)) | | `containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the group. | | `containsLockedProjects` | [`Boolean!`](#boolean) | Includes at least one project where the repository size exceeds the limit. | | `customEmoji` | [`CustomEmojiConnection`](#customemojiconnection) | Custom emoji within this namespace. Available only when feature flag `custom_emoji` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) | +| `dependencyProxyBlobCount` | [`Int!`](#int) | Number of dependency proxy blobs cached in the group. | +| `dependencyProxyBlobs` | [`DependencyProxyBlobConnection`](#dependencyproxyblobconnection) | Dependency Proxy blobs. (see [Connections](#connections)) | +| `dependencyProxyImageCount` | [`Int!`](#int) | Number of dependency proxy images cached in the group. | +| `dependencyProxyImagePrefix` | [`String!`](#string) | Prefix for pulling images when using the dependency proxy. | +| `dependencyProxyImageTtlPolicy` | [`DependencyProxyImageTtlGroupPolicy`](#dependencyproxyimagettlgrouppolicy) | Dependency proxy TTL policy for the group. | +| `dependencyProxyManifests` | [`DependencyProxyManifestConnection`](#dependencyproxymanifestconnection) | Dependency Proxy manifests. (see [Connections](#connections)) | +| `dependencyProxySetting` | [`DependencyProxySetting`](#dependencyproxysetting) | Dependency Proxy settings for the group. | +| `dependencyProxyTotalSize` | [`String!`](#string) | Total size of the dependency proxy cached images. | | `description` | [`String`](#string) | Description of the namespace. | | `descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | -| `dora` | [`Dora`](#dora) | The group's DORA metrics. | +| `dora` | [`Dora`](#dora) | Group's DORA metrics. | | `emailsDisabled` | [`Boolean`](#boolean) | Indicates if a group has email notifications disabled. | | `epicBoards` | [`EpicBoardConnection`](#epicboardconnection) | Find epic boards. (see [Connections](#connections)) | | `epicsEnabled` | [`Boolean`](#boolean) | Indicates if Epics are enabled for namespace. | @@ -9573,10 +10038,11 @@ four standard [pagination arguments](#connection-pagination-arguments): | `lfsEnabled` | [`Boolean`](#boolean) | Indicates if Large File Storage (LFS) is enabled for namespace. | | `mentionsDisabled` | [`Boolean`](#boolean) | Indicates if a group is disabled from getting mentioned. | | `name` | [`String!`](#string) | Name of the namespace. | -| `packageSettings` | [`PackageSettings`](#packagesettings) | The package settings for the namespace. | +| `organizations` | [`CustomerRelationsOrganizationConnection`](#customerrelationsorganizationconnection) | Find organizations of this group. (see [Connections](#connections)) | +| `packageSettings` | [`PackageSettings`](#packagesettings) | Package settings for the namespace. | | `parent` | [`Group`](#group) | Parent group. | | `path` | [`String!`](#string) | Path of the namespace. | -| `projectCreationLevel` | [`String`](#string) | The permission level required to create projects in the group. | +| `projectCreationLevel` | [`String`](#string) | Permission level required to create projects in the group. | | `repositorySizeExcessProjectCount` | [`Int!`](#int) | Number of projects in the root namespace where the repository size exceeds the limit. | | `requestAccessEnabled` | [`Boolean`](#boolean) | Indicates if users can request access to namespace. | | `requireTwoFactorAuthentication` | [`Boolean`](#boolean) | Indicates if all users in this group are required to set up two-factor authentication. | @@ -9585,7 +10051,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `sharedRunnersSetting` | [`SharedRunnersSetting`](#sharedrunnerssetting) | Shared runners availability for the namespace and its descendants. | | `stats` | [`GroupStats`](#groupstats) | Group statistics. | | `storageSizeLimit` | [`Float`](#float) | Total storage limit of the root namespace in bytes. | -| `subgroupCreationLevel` | [`String`](#string) | The permission level required to create subgroups within the group. | +| `subgroupCreationLevel` | [`String`](#string) | Permission level required to create subgroups within the group. | | `temporaryStorageIncreaseEndsOn` | [`Time`](#time) | Date until the temporary storage increase is active. | | `totalRepositorySize` | [`Float`](#float) | Total repository size of all projects in the root namespace in bytes. | | `totalRepositorySizeExcess` | [`Float`](#float) | Total excess repository size of all projects in the root namespace in bytes. | @@ -9797,7 +10263,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `assigneeId` | [`String`](#string) | ID of a user assigned to the issues, "none" and "any" values are supported. | +| `assigneeId` | [`String`](#string) | ID of a user assigned to the issues. Wildcard values "NONE" and "ANY" are supported. | | `assigneeUsername` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.11. Use `assigneeUsernames`. | | `assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the issue. | | `authorUsername` | [`String`](#string) | Username of the author of the issue. | @@ -9814,6 +10280,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `labelName` | [`[String]`](#string) | Labels applied to this issue. | | `milestoneTitle` | [`[String]`](#string) | Milestone applied to this issue. | | `milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | +| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | `not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | | `search` | [`String`](#string) | Search query for issue title or description. | | `sort` | [`IssueSort`](#issuesort) | Sort issues by this criteria. | @@ -9870,7 +10337,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `Group.label` -A label available on this group. +Label available on this group. Returns [`Label`](#label). @@ -9897,7 +10364,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `includeAncestorGroups` | [`Boolean`](#boolean) | Include labels from ancestor groups. | | `includeDescendantGroups` | [`Boolean`](#boolean) | Include labels from descendant groups. | | `onlyGroupLabels` | [`Boolean`](#boolean) | Include only group level labels. | -| `searchTerm` | [`String`](#string) | A search term to find labels with. | +| `searchTerm` | [`String`](#string) | Search term to find labels with. | ##### `Group.mergeRequests` @@ -9924,7 +10391,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `not` | [`MergeRequestsResolverNegatedParams`](#mergerequestsresolvernegatedparams) | List of negated arguments. Warning: this argument is experimental and a subject to change in future. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `Group.milestones` @@ -9941,17 +10408,17 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `containingDate` | [`Time`](#time) | A date that the milestone contains. | +| `containingDate` | [`Time`](#time) | Date the milestone contains. | | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `ids` | [`[ID!]`](#id) | Array of global milestone IDs, e.g., `"gid://gitlab/Milestone/1"`. | | `includeAncestors` | [`Boolean`](#boolean) | Include milestones from all parent groups. | | `includeDescendants` | [`Boolean`](#boolean) | Include milestones from all subgroups and subprojects. | -| `searchTitle` | [`String`](#string) | A search string for the title. | +| `searchTitle` | [`String`](#string) | Search string for the title. | | `sort` | [`MilestoneSort`](#milestonesort) | Sort milestones by this criteria. | | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`MilestoneStateEnum`](#milestonestateenum) | Filter milestones by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | -| `title` | [`String`](#string) | The title of the milestone. | +| `title` | [`String`](#string) | Title of the milestone. | ##### `Group.packages` @@ -9994,6 +10461,27 @@ four standard [pagination arguments](#connection-pagination-arguments): | `search` | [`String`](#string) | Search project with most similar names or paths. | | `sort` | [`NamespaceProjectSort`](#namespaceprojectsort) | Sort projects by this criteria. | +##### `Group.runners` + +Find runners visible to the current user. + +Returns [`CiRunnerConnection`](#cirunnerconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `membership` | [`RunnerMembershipFilter`](#runnermembershipfilter) | Control which runners to include in the results. | +| `search` | [`String`](#string) | Filter by full token or partial text in description field. | +| `sort` | [`CiRunnerSort`](#cirunnersort) | Sort order of results. | +| `status` | [`CiRunnerStatus`](#cirunnerstatus) | Filter runners by status. | +| `tagList` | [`[String!]`](#string) | Filter by tags associated with the runner (comma-separated or array). | +| `type` | [`CiRunnerType`](#cirunnertype) | Filter runners by type. | + ##### `Group.timelogs` Time logged on issues and merge requests in the group and its subgroups. @@ -10112,6 +10600,7 @@ Represents a Group Membership. | Name | Type | Description | | ---- | ---- | ----------- | +| `createProjects` | [`Boolean!`](#boolean) | Indicates the user can perform `create_projects` on this resource. | | `readGroup` | [`Boolean!`](#boolean) | Indicates the user can perform `read_group` on this resource. | ### `GroupReleaseStats` @@ -10199,6 +10688,7 @@ Describes an incident management on-call schedule. | `description` | [`String`](#string) | Description of the on-call schedule. | | `iid` | [`ID!`](#id) | Internal ID of the on-call schedule. | | `name` | [`String!`](#string) | Name of the on-call schedule. | +| `oncallUsers` | [`[UserCore!]`](#usercore) | | | `rotations` | [`IncidentManagementOncallRotationConnection!`](#incidentmanagementoncallrotationconnection) | On-call rotations for the on-call schedule. (see [Connections](#connections)) | | `timezone` | [`String!`](#string) | Time zone of the on-call schedule. | @@ -10301,6 +10791,7 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | `emailsDisabled` | [`Boolean!`](#boolean) | Indicates if a project has email notifications disabled: `true` if email notifications are disabled. | | `epic` | [`Epic`](#epic) | Epic to which this issue belongs. | | `healthStatus` | [`HealthStatus`](#healthstatus) | Current health status. | +| `hidden` | [`Boolean`](#boolean) | Indicates the issue is hidden because the author has been banned. Will always return `null` if `ban_user_feature_flag` feature flag is disabled. | | `humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the issue. | | `humanTotalTimeSpent` | [`String`](#string) | Human-readable total time reported as spent on the issue. | | `id` | [`ID!`](#id) | ID of the issue. | @@ -10521,7 +11012,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | `enabled` | [`Boolean!`](#boolean) | Indicates whether the Kubernetes Agent Server is enabled. | -| `externalUrl` | [`String`](#string) | The URL used by the Agents to communicate with KAS. | +| `externalUrl` | [`String`](#string) | URL used by the Agents to communicate with KAS. | | `version` | [`String`](#string) | KAS version. | ### `Label` @@ -10599,6 +11090,7 @@ Maven metadata. | Name | Type | Description | | ---- | ---- | ----------- | | `allowCollaboration` | [`Boolean`](#boolean) | Indicates if members of the target project can push to the fork. | +| `approvalState` | [`MergeRequestApprovalState!`](#mergerequestapprovalstate) | Information relating to rules that must be satisfied to merge this merge request. | | `approvalsLeft` | [`Int`](#int) | Number of approvals left. | | `approvalsRequired` | [`Int`](#int) | Number of approvals required. | | `approved` | [`Boolean!`](#boolean) | Indicates if the merge request has all the required approvals. Returns true if no required approvals are configured. | @@ -10628,7 +11120,7 @@ Maven metadata. | `forceRemoveSourceBranch` | [`Boolean`](#boolean) | Indicates if the project settings will lead to source branch deletion after merge. | | `hasCi` | [`Boolean!`](#boolean) | Indicates if the merge request has CI. | | `hasSecurityReports` | [`Boolean!`](#boolean) | Indicates if the source branch has any security reports. | -| `headPipeline` | [`Pipeline`](#pipeline) | The pipeline running on the branch HEAD of the merge request. | +| `headPipeline` | [`Pipeline`](#pipeline) | Pipeline running on the branch HEAD of the merge request. | | `humanTimeEstimate` | [`String`](#string) | Human-readable time estimate of the merge request. | | `humanTotalTimeSpent` | [`String`](#string) | Human-readable total time reported as spent on the merge request. | | `id` | [`ID!`](#id) | ID of the merge request. | @@ -10646,7 +11138,7 @@ Maven metadata. | `mergeable` | [`Boolean!`](#boolean) | Indicates if the merge request is mergeable. | | `mergeableDiscussionsState` | [`Boolean`](#boolean) | Indicates if all discussions in the merge request have been resolved, allowing the merge request to be merged. | | `mergedAt` | [`Time`](#time) | Timestamp of when the merge request was merged, null if not merged. | -| `milestone` | [`Milestone`](#milestone) | The milestone of the merge request. | +| `milestone` | [`Milestone`](#milestone) | Milestone of the merge request. | | `notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | `participants` | [`UserCoreConnection`](#usercoreconnection) | Participants in the merge request. This includes the author, assignees, reviewers, and users mentioned in notes. (see [Connections](#connections)) | | `project` | [`Project!`](#project) | Alias for target_project. | @@ -10713,7 +11205,7 @@ Returns [`[DiffStats!]`](#diffstats). | Name | Type | Description | | ---- | ---- | ----------- | -| `path` | [`String`](#string) | A specific file-path. | +| `path` | [`String`](#string) | Specific file path. | ##### `MergeRequest.pipelines` @@ -10731,6 +11223,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | | `sha` | [`String`](#string) | Filter pipelines by the sha of the commit they are run for. | +| `source` | [`String`](#string) | Filter pipelines by their source. Will be ignored if `dast_view_scans` feature flag is disabled. | | `status` | [`PipelineStatusEnum`](#pipelinestatusenum) | Filter pipelines by their status. | ##### `MergeRequest.reference` @@ -10745,6 +11238,17 @@ Returns [`String!`](#string). | ---- | ---- | ----------- | | `full` | [`Boolean`](#boolean) | Boolean option specifying whether the reference should be returned in full. | +### `MergeRequestApprovalState` + +Information relating to rules that must be satisfied to merge this merge request. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `approvalRulesOverwritten` | [`Boolean`](#boolean) | Indicates if the merge request approval rules are overwritten for the merge request. | +| `rules` | [`[ApprovalRule!]`](#approvalrule) | List of approval rules associated with the merge request. | + ### `MergeRequestAssignee` A user assigned to a merge request. @@ -10760,7 +11264,7 @@ A user assigned to a merge request. | `groupCount` | [`Int`](#int) | Group count for the user. | | `groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | `id` | [`ID!`](#id) | ID of the user. | -| `location` | [`String`](#string) | The location of the user. | +| `location` | [`String`](#string) | Location of the user. | | `mergeRequestInteraction` | [`UserMergeRequestInteraction`](#usermergerequestinteraction) | Details of this user's interactions with the merge request. | | `name` | [`String!`](#string) | Human-readable name of the user. | | `namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | @@ -10801,7 +11305,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `reviewerUsername` | [`String`](#string) | Username of the reviewer. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `MergeRequestAssignee.authoredMergeRequests` @@ -10830,9 +11334,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | `reviewerUsername` | [`String`](#string) | Username of the reviewer. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +##### `MergeRequestAssignee.groups` + +Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. + +Returns [`GroupConnection`](#groupconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| `search` | [`String`](#string) | Search by group name or path. | + ##### `MergeRequestAssignee.reviewRequestedMergeRequests` Merge requests assigned to the user for review. @@ -10859,7 +11380,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `MergeRequestAssignee.snippets` @@ -10877,7 +11398,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | `ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| `type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| `type` | [`TypeEnum`](#typeenum) | Type of snippet. | | `visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ##### `MergeRequestAssignee.starredProjects` @@ -10932,12 +11453,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| `authorId` | [`[ID!]`](#id) | The ID of an author. | -| `groupId` | [`[ID!]`](#id) | The ID of a group. | -| `projectId` | [`[ID!]`](#id) | The ID of a project. | -| `state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| `action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| `authorId` | [`[ID!]`](#id) | ID of an author. | +| `groupId` | [`[ID!]`](#id) | ID of a group. | +| `projectId` | [`[ID!]`](#id) | ID of a project. | +| `state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ### `MergeRequestDiffRegistry` @@ -10989,7 +11510,7 @@ A user assigned to a merge request as a reviewer. | `groupCount` | [`Int`](#int) | Group count for the user. | | `groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | `id` | [`ID!`](#id) | ID of the user. | -| `location` | [`String`](#string) | The location of the user. | +| `location` | [`String`](#string) | Location of the user. | | `mergeRequestInteraction` | [`UserMergeRequestInteraction`](#usermergerequestinteraction) | Details of this user's interactions with the merge request. | | `name` | [`String!`](#string) | Human-readable name of the user. | | `namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | @@ -11030,7 +11551,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `reviewerUsername` | [`String`](#string) | Username of the reviewer. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `MergeRequestReviewer.authoredMergeRequests` @@ -11059,9 +11580,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | `reviewerUsername` | [`String`](#string) | Username of the reviewer. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +##### `MergeRequestReviewer.groups` + +Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. + +Returns [`GroupConnection`](#groupconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| `search` | [`String`](#string) | Search by group name or path. | + ##### `MergeRequestReviewer.reviewRequestedMergeRequests` Merge requests assigned to the user for review. @@ -11088,7 +11626,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `MergeRequestReviewer.snippets` @@ -11106,7 +11644,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | `ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| `type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| `type` | [`TypeEnum`](#typeenum) | Type of snippet. | | `visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ##### `MergeRequestReviewer.starredProjects` @@ -11161,12 +11699,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| `authorId` | [`[ID!]`](#id) | The ID of an author. | -| `groupId` | [`[ID!]`](#id) | The ID of a group. | -| `projectId` | [`[ID!]`](#id) | The ID of a project. | -| `state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| `action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| `authorId` | [`[ID!]`](#id) | ID of an author. | +| `groupId` | [`[ID!]`](#id) | ID of a group. | +| `projectId` | [`[ID!]`](#id) | ID of a project. | +| `state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ### `Metadata` @@ -11285,7 +11823,7 @@ Contains statistics about a milestone. | `isTemporaryStorageIncreaseEnabled` | [`Boolean!`](#boolean) | Status of the temporary storage increase. | | `lfsEnabled` | [`Boolean`](#boolean) | Indicates if Large File Storage (LFS) is enabled for namespace. | | `name` | [`String!`](#string) | Name of the namespace. | -| `packageSettings` | [`PackageSettings`](#packagesettings) | The package settings for the namespace. | +| `packageSettings` | [`PackageSettings`](#packagesettings) | Package settings for the namespace. | | `path` | [`String!`](#string) | Path of the namespace. | | `repositorySizeExcessProjectCount` | [`Int!`](#int) | Number of projects in the root namespace where the repository size exceeds the limit. | | `requestAccessEnabled` | [`Boolean`](#boolean) | Indicates if users can request access to namespace. | @@ -11364,9 +11902,9 @@ Represents the network policy. | `bodyHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `note`. | | `confidential` | [`Boolean`](#boolean) | Indicates if this note is confidential. | | `createdAt` | [`Time!`](#time) | Timestamp of the note creation. | -| `discussion` | [`Discussion`](#discussion) | The discussion this note is a part of. | +| `discussion` | [`Discussion`](#discussion) | Discussion this note is a part of. | | `id` | [`NoteID!`](#noteid) | ID of the note. | -| `position` | [`DiffPosition`](#diffposition) | The position of this note on a diff. | +| `position` | [`DiffPosition`](#diffposition) | Position of this note on a diff. | | `project` | [`Project`](#project) | Project associated with the note. | | `resolvable` | [`Boolean!`](#boolean) | Indicates if the object can be resolved. | | `resolved` | [`Boolean!`](#boolean) | Indicates if the object is resolved. | @@ -11423,10 +11961,10 @@ The rotation participant and color palette. | Name | Type | Description | | ---- | ---- | ----------- | -| `colorPalette` | [`String`](#string) | The color palette to assign to the on-call user. For example "blue". | -| `colorWeight` | [`String`](#string) | The color weight to assign to for the on-call user, for example "500". Max 4 chars. For easy identification of the user. | +| `colorPalette` | [`String`](#string) | Color palette to assign to the on-call user. For example "blue". | +| `colorWeight` | [`String`](#string) | Color weight to assign to for the on-call user, for example "500". Max 4 chars. For easy identification of the user. | | `id` | [`IncidentManagementOncallParticipantID!`](#incidentmanagementoncallparticipantid) | ID of the on-call participant. | -| `user` | [`UserCore!`](#usercore) | The user who is participating. | +| `user` | [`UserCore!`](#usercore) | User who is participating. | ### `OncallRotationActivePeriodType` @@ -11436,8 +11974,8 @@ Active period time range for on-call rotation. | Name | Type | Description | | ---- | ---- | ----------- | -| `endTime` | [`String`](#string) | The end of the rotation active period. | -| `startTime` | [`String`](#string) | The start of the rotation active period. | +| `endTime` | [`String`](#string) | End of the rotation active period. | +| `startTime` | [`String`](#string) | Start of the rotation active period. | ### `Package` @@ -11468,10 +12006,10 @@ Represents a composer JSON file. | Name | Type | Description | | ---- | ---- | ----------- | -| `license` | [`String`](#string) | The license set in the Composer JSON file. | -| `name` | [`String`](#string) | The name set in the Composer JSON file. | -| `type` | [`String`](#string) | The type set in the Composer JSON file. | -| `version` | [`String`](#string) | The version set in the Composer JSON file. | +| `license` | [`String`](#string) | License set in the Composer JSON file. | +| `name` | [`String`](#string) | Name set in the Composer JSON file. | +| `type` | [`String`](#string) | Type set in the Composer JSON file. | +| `version` | [`String`](#string) | Version set in the Composer JSON file. | ### `PackageDependency` @@ -11519,7 +12057,7 @@ Represents a package details in the Package Registry. Note that this type is in | `tags` | [`PackageTagConnection`](#packagetagconnection) | Package tags. (see [Connections](#connections)) | | `updatedAt` | [`Time!`](#time) | Date of most recent update. | | `version` | [`String`](#string) | Version string. | -| `versions` | [`PackageConnection`](#packageconnection) | The other versions of the package. (see [Connections](#connections)) | +| `versions` | [`PackageConnection`](#packageconnection) | Other versions of the package. (see [Connections](#connections)) | ### `PackageFile` @@ -11529,7 +12067,7 @@ Represents a package file. | Name | Type | Description | | ---- | ---- | ----------- | -| `createdAt` | [`Time!`](#time) | The created date. | +| `createdAt` | [`Time!`](#time) | Created date. | | `downloadPath` | [`String!`](#string) | Download path of the package file. | | `fileMd5` | [`String`](#string) | Md5 of the package file. | | `fileMetadata` | [`PackageFileMetadata`](#packagefilemetadata) | File metadata. | @@ -11538,7 +12076,7 @@ Represents a package file. | `fileSha256` | [`String`](#string) | Sha256 of the package file. | | `id` | [`PackagesPackageFileID!`](#packagespackagefileid) | ID of the file. | | `size` | [`String!`](#string) | Size of the package file. | -| `updatedAt` | [`Time!`](#time) | The updated date. | +| `updatedAt` | [`Time!`](#time) | Updated date. | ### `PackageFileRegistry` @@ -11578,10 +12116,10 @@ Represents a package tag. | Name | Type | Description | | ---- | ---- | ----------- | -| `createdAt` | [`Time!`](#time) | The created date. | -| `id` | [`ID!`](#id) | The ID of the tag. | -| `name` | [`String!`](#string) | The name of the tag. | -| `updatedAt` | [`Time!`](#time) | The updated date. | +| `createdAt` | [`Time!`](#time) | Created date. | +| `id` | [`ID!`](#id) | ID of the tag. | +| `name` | [`String!`](#string) | Name of the tag. | +| `updatedAt` | [`Time!`](#time) | Updated date. | ### `PageInfo` @@ -11596,6 +12134,23 @@ Information about pagination in a connection. | `hasPreviousPage` | [`Boolean!`](#boolean) | When paginating backwards, are there more items?. | | `startCursor` | [`String`](#string) | When paginating backwards, the cursor to continue. | +### `PagesDeploymentRegistry` + +Represents the Geo replication and verification state of a pages_deployment. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `createdAt` | [`Time`](#time) | Timestamp when the PagesDeploymentRegistry was created. | +| `id` | [`ID!`](#id) | ID of the PagesDeploymentRegistry. | +| `lastSyncFailure` | [`String`](#string) | Error message during sync of the PagesDeploymentRegistry. | +| `lastSyncedAt` | [`Time`](#time) | Timestamp of the most recent successful sync of the PagesDeploymentRegistry. | +| `pagesDeploymentId` | [`ID!`](#id) | ID of the Pages Deployment. | +| `retryAt` | [`Time`](#time) | Timestamp after which the PagesDeploymentRegistry should be resynced. | +| `retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the PagesDeploymentRegistry. | +| `state` | [`RegistryState`](#registrystate) | Sync state of the PagesDeploymentRegistry. | + ### `PathLock` Represents a file or directory in the project repository that has been locked. @@ -11605,8 +12160,8 @@ Represents a file or directory in the project repository that has been locked. | Name | Type | Description | | ---- | ---- | ----------- | | `id` | [`PathLockID!`](#pathlockid) | ID of the path lock. | -| `path` | [`String`](#string) | The locked path. | -| `user` | [`UserCore`](#usercore) | The user that has locked this path. | +| `path` | [`String`](#string) | Locked path. | +| `user` | [`UserCore`](#usercore) | User that has locked this path. | ### `Pipeline` @@ -11653,7 +12208,7 @@ Represents a file or directory in the project repository that has been locked. ##### `Pipeline.job` -A specific job in this pipeline, either by name or ID. +Specific job in this pipeline, either by name or ID. Returns [`CiJob`](#cijob). @@ -11767,17 +12322,17 @@ Represents vulnerability finding of a security report on the pipeline. | ---- | ---- | ----------- | | `confidence` | [`String`](#string) | Type of the security report that found the vulnerability. | | `description` | [`String`](#string) | Description of the vulnerability finding. | -| `falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. Available only when feature flag `vulnerability_flags` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | +| `falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. | | `identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerabilit finding. | | `location` | [`VulnerabilityLocation`](#vulnerabilitylocation) | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability. | | `name` | [`String`](#string) | Name of the vulnerability finding. | -| `project` | [`Project`](#project) | The project on which the vulnerability finding was found. | +| `project` | [`Project`](#project) | Project on which the vulnerability finding was found. | | `projectFingerprint` | [`String`](#string) | Name of the vulnerability finding. | | `reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability finding. | | `scanner` | [`VulnerabilityScanner`](#vulnerabilityscanner) | Scanner metadata for the vulnerability. | | `severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability finding. | | `solution` | [`String`](#string) | URL to the vulnerability's details page. | -| `state` | [`VulnerabilityState`](#vulnerabilitystate) | The finding status. | +| `state` | [`VulnerabilityState`](#vulnerabilitystate) | Finding status. | | `uuid` | [`String`](#string) | Name of the vulnerability finding. | ### `Project` @@ -11798,16 +12353,16 @@ Represents vulnerability finding of a security report on the pipeline. | `clusterAgents` | [`ClusterAgentConnection`](#clusteragentconnection) | Cluster agents associated with the project. (see [Connections](#connections)) | | `codeCoverageSummary` | [`CodeCoverageSummary`](#codecoveragesummary) | Code coverage summary associated with the project. | | `complianceFrameworks` | [`ComplianceFrameworkConnection`](#complianceframeworkconnection) | Compliance frameworks associated with the project. (see [Connections](#connections)) | -| `containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | The container expiration policy of the project. | +| `containerExpirationPolicy` | [`ContainerExpirationPolicy`](#containerexpirationpolicy) | Container expiration policy of the project. | | `containerRegistryEnabled` | [`Boolean`](#boolean) | Indicates if Container Registry is enabled for the current user. | | `containerRepositoriesCount` | [`Int!`](#int) | Number of container repositories in the project. | | `createdAt` | [`Time`](#time) | Timestamp of the project creation. | | `dastProfiles` | [`DastProfileConnection`](#dastprofileconnection) | DAST Profiles associated with the project. (see [Connections](#connections)) | -| `dastScannerProfiles` | [`DastScannerProfileConnection`](#dastscannerprofileconnection) | The DAST scanner profiles associated with the project. (see [Connections](#connections)) | +| `dastScannerProfiles` | [`DastScannerProfileConnection`](#dastscannerprofileconnection) | DAST scanner profiles associated with the project. (see [Connections](#connections)) | | `dastSiteProfiles` | [`DastSiteProfileConnection`](#dastsiteprofileconnection) | DAST Site Profiles associated with the project. (see [Connections](#connections)) | | `description` | [`String`](#string) | Short description of the project. | | `descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | -| `dora` | [`Dora`](#dora) | The project's DORA metrics. | +| `dora` | [`Dora`](#dora) | Project's DORA metrics. | | `forksCount` | [`Int!`](#int) | Number of times the project has been forked. | | `fullPath` | [`ID!`](#id) | Full path of the project. | | `grafanaIntegration` | [`GrafanaIntegration`](#grafanaintegration) | Grafana integration details for the project. | @@ -11835,7 +12390,7 @@ Represents vulnerability finding of a security report on the pipeline. | `pipelineAnalytics` | [`PipelineAnalytics`](#pipelineanalytics) | Pipeline analytics. | | `printingMergeRequestLinkEnabled` | [`Boolean`](#boolean) | Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line. | | `publicJobs` | [`Boolean`](#boolean) | Indicates if there is public access to pipelines and job details of the project, including output logs and artifacts. | -| `pushRules` | [`PushRules`](#pushrules) | The project's push rules settings. | +| `pushRules` | [`PushRules`](#pushrules) | Project's push rules settings. | | `removeSourceBranchAfterMerge` | [`Boolean`](#boolean) | Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project. | | `repository` | [`Repository`](#repository) | Git repository of the project. | | `repositorySizeExcess` | [`Float`](#float) | Size of repository that exceeds the limit in bytes. | @@ -11854,7 +12409,7 @@ Represents vulnerability finding of a security report on the pipeline. | `sshUrlToRepo` | [`String`](#string) | URL to connect to the project via SSH. | | `starCount` | [`Int!`](#int) | Number of times the project has been starred. | | `statistics` | [`ProjectStatistics`](#projectstatistics) | Statistics of the project. | -| `suggestionCommitMessage` | [`String`](#string) | The commit message used to apply merge request suggestions. | +| `suggestionCommitMessage` | [`String`](#string) | Commit message used to apply merge request suggestions. | | `tagList` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.12. Use `topics`. | | `terraformStates` | [`TerraformStateConnection`](#terraformstateconnection) | Terraform states associated with the project. (see [Connections](#connections)) | | `topics` | [`[String!]`](#string) | List of project topics. | @@ -12069,6 +12624,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | `normalizedTargetUrls` | [`[String!]`](#string) | Normalized URL of the target to be scanned. | +| `status` | [`DastSiteValidationStatusEnum`](#dastsitevalidationstatusenum) | Status of the site validation. Ignored if `dast_failed_site_validations` feature flag is disabled. | ##### `Project.environment` @@ -12140,7 +12696,7 @@ Returns [`Issue`](#issue). | Name | Type | Description | | ---- | ---- | ----------- | -| `assigneeId` | [`String`](#string) | ID of a user assigned to the issues, "none" and "any" values are supported. | +| `assigneeId` | [`String`](#string) | ID of a user assigned to the issues. Wildcard values "NONE" and "ANY" are supported. | | `assigneeUsername` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.11. Use `assigneeUsernames`. | | `assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the issue. | | `authorUsername` | [`String`](#string) | Username of the author of the issue. | @@ -12156,6 +12712,7 @@ Returns [`Issue`](#issue). | `labelName` | [`[String]`](#string) | Labels applied to this issue. | | `milestoneTitle` | [`[String]`](#string) | Milestone applied to this issue. | | `milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | +| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | `not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | | `search` | [`String`](#string) | Search query for issue title or description. | | `sort` | [`IssueSort`](#issuesort) | Sort issues by this criteria. | @@ -12175,7 +12732,7 @@ Returns [`IssueStatusCountsType`](#issuestatuscountstype). | Name | Type | Description | | ---- | ---- | ----------- | -| `assigneeId` | [`String`](#string) | ID of a user assigned to the issues, "none" and "any" values are supported. | +| `assigneeId` | [`String`](#string) | ID of a user assigned to the issues. Wildcard values "NONE" and "ANY" are supported. | | `assigneeUsername` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.11. Use `assigneeUsernames`. | | `assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the issue. | | `authorUsername` | [`String`](#string) | Username of the author of the issue. | @@ -12188,6 +12745,7 @@ Returns [`IssueStatusCountsType`](#issuestatuscountstype). | `labelName` | [`[String]`](#string) | Labels applied to this issue. | | `milestoneTitle` | [`[String]`](#string) | Milestone applied to this issue. | | `milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | +| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | `not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | | `search` | [`String`](#string) | Search query for issue title or description. | | `types` | [`[IssueType!]`](#issuetype) | Filter issues by the given issue types. | @@ -12208,7 +12766,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `assigneeId` | [`String`](#string) | ID of a user assigned to the issues, "none" and "any" values are supported. | +| `assigneeId` | [`String`](#string) | ID of a user assigned to the issues. Wildcard values "NONE" and "ANY" are supported. | | `assigneeUsername` **{warning-solid}** | [`String`](#string) | **Deprecated** in 13.11. Use `assigneeUsernames`. | | `assigneeUsernames` | [`[String!]`](#string) | Usernames of users assigned to the issue. | | `authorUsername` | [`String`](#string) | Username of the author of the issue. | @@ -12224,6 +12782,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `labelName` | [`[String]`](#string) | Labels applied to this issue. | | `milestoneTitle` | [`[String]`](#string) | Milestone applied to this issue. | | `milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | +| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | `not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | | `search` | [`String`](#string) | Search query for issue title or description. | | `sort` | [`IssueSort`](#issuesort) | Sort issues by this criteria. | @@ -12296,7 +12855,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `Project.label` -A label available on this project. +Label available on this project. Returns [`Label`](#label). @@ -12321,7 +12880,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | `includeAncestorGroups` | [`Boolean`](#boolean) | Include labels from ancestor groups. | -| `searchTerm` | [`String`](#string) | A search term to find labels with. | +| `searchTerm` | [`String`](#string) | Search term to find labels with. | ##### `Project.mergeRequest` @@ -12360,7 +12919,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `reviewerUsername` | [`String`](#string) | Username of the reviewer. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `Project.milestones` @@ -12377,16 +12936,16 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `containingDate` | [`Time`](#time) | A date that the milestone contains. | +| `containingDate` | [`Time`](#time) | Date the milestone contains. | | `endDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.end. | | `ids` | [`[ID!]`](#id) | Array of global milestone IDs, e.g., `"gid://gitlab/Milestone/1"`. | | `includeAncestors` | [`Boolean`](#boolean) | Also return milestones in the project's parent group and its ancestors. | -| `searchTitle` | [`String`](#string) | A search string for the title. | +| `searchTitle` | [`String`](#string) | Search string for the title. | | `sort` | [`MilestoneSort`](#milestonesort) | Sort milestones by this criteria. | | `startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | `state` | [`MilestoneStateEnum`](#milestonestateenum) | Filter milestones by state. | | `timeframe` | [`Timeframe`](#timeframe) | List items overlapping the given timeframe. | -| `title` | [`String`](#string) | The title of the milestone. | +| `title` | [`String`](#string) | Title of the milestone. | ##### `Project.networkPolicies` @@ -12402,7 +12961,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `environmentId` | [`EnvironmentID`](#environmentid) | The global ID of the environment to filter policies. | +| `environmentId` | [`EnvironmentID`](#environmentid) | Global ID of the environment to filter policies. | ##### `Project.packages` @@ -12453,6 +13012,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | `ref` | [`String`](#string) | Filter pipelines by the ref they are run for. | | `sha` | [`String`](#string) | Filter pipelines by the sha of the commit they are run for. | +| `source` | [`String`](#string) | Filter pipelines by their source. Will be ignored if `dast_view_scans` feature flag is disabled. | | `status` | [`PipelineStatusEnum`](#pipelinestatusenum) | Filter pipelines by their status. | ##### `Project.projectMembers` @@ -12482,7 +13042,7 @@ Returns [`Release`](#release). | Name | Type | Description | | ---- | ---- | ----------- | -| `tagName` | [`String!`](#string) | The name of the tag associated to the release. | +| `tagName` | [`String!`](#string) | Name of the tag associated to the release. | ##### `Project.releases` @@ -12513,7 +13073,7 @@ Returns [`Requirement`](#requirement). | `authorUsername` | [`[String!]`](#string) | Filter requirements by author username. | | `iid` | [`ID`](#id) | IID of the requirement, e.g., "1". | | `iids` | [`[ID!]`](#id) | List of IIDs of requirements, e.g., `[1, 2]`. | -| `lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | The state of latest requirement test report. | +| `lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | State of latest requirement test report. | | `search` | [`String`](#string) | Search query for requirement title. | | `sort` | [`Sort`](#sort) | List requirements by sort order. | | `state` | [`RequirementState`](#requirementstate) | Filter requirements by state. | @@ -12535,7 +13095,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `authorUsername` | [`[String!]`](#string) | Filter requirements by author username. | | `iid` | [`ID`](#id) | IID of the requirement, e.g., "1". | | `iids` | [`[ID!]`](#id) | List of IIDs of requirements, e.g., `[1, 2]`. | -| `lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | The state of latest requirement test report. | +| `lastTestReportState` | [`RequirementStatusFilter`](#requirementstatusfilter) | State of latest requirement test report. | | `search` | [`String`](#string) | Search query for requirement title. | | `sort` | [`Sort`](#sort) | List requirements by sort order. | | `state` | [`RequirementState`](#requirementstate) | Filter requirements by state. | @@ -12770,6 +13330,7 @@ Represents a Project Membership. | `commitCount` | [`Float!`](#float) | Commit count of the project. | | `lfsObjectsSize` | [`Float!`](#float) | Large File Storage (LFS) object size of the project in bytes. | | `packagesSize` | [`Float!`](#float) | Packages size of the project in bytes. | +| `pipelineArtifactsSize` | [`Float`](#float) | CI Pipeline artifacts size in bytes. | | `repositorySize` | [`Float!`](#float) | Repository size of the project in bytes. | | `snippetsSize` | [`Float`](#float) | Snippets size of the project in bytes. | | `storageSize` | [`Float!`](#float) | Storage size of the project in bytes. | @@ -12784,7 +13345,7 @@ The alert condition for Prometheus. | Name | Type | Description | | ---- | ---- | ----------- | -| `humanizedText` | [`String!`](#string) | The human-readable text of the alert condition. | +| `humanizedText` | [`String!`](#string) | Human-readable text of the alert condition. | | `id` | [`ID!`](#id) | ID of the alert condition. | ### `PushRules` @@ -12838,7 +13399,7 @@ Represents a release. | ---- | ---- | ----------- | | `assets` | [`ReleaseAssets`](#releaseassets) | Assets of the release. | | `author` | [`UserCore`](#usercore) | User that created the release. | -| `commit` | [`Commit`](#commit) | The commit associated with the release. | +| `commit` | [`Commit`](#commit) | Commit associated with the release. | | `createdAt` | [`Time`](#time) | Timestamp of when the release was created. | | `description` | [`String`](#string) | Description (also known as "release notes") of the release. | | `descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | @@ -12957,9 +13518,9 @@ Returns [`[String!]`](#string). | Name | Type | Description | | ---- | ---- | ----------- | -| `limit` | [`Int!`](#int) | The number of branch names to return. | -| `offset` | [`Int!`](#int) | The number of branch names to skip. | -| `searchPattern` | [`String!`](#string) | The pattern to search for branch names by. | +| `limit` | [`Int!`](#int) | Number of branch names to return. | +| `offset` | [`Int!`](#int) | Number of branch names to skip. | +| `searchPattern` | [`String!`](#string) | Pattern to search for branch names by. | ##### `Repository.paginatedTree` @@ -12975,9 +13536,9 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `path` | [`String`](#string) | The path to get the tree for. Default value is the root of the repository. | +| `path` | [`String`](#string) | Path to get the tree for. Default value is the root of the repository. | | `recursive` | [`Boolean`](#boolean) | Used to get a recursive tree. Default is false. | -| `ref` | [`String`](#string) | The commit ref to get the tree for. Default value is HEAD. | +| `ref` | [`String`](#string) | Commit ref to get the tree for. Default value is HEAD. | ##### `Repository.tree` @@ -12989,9 +13550,9 @@ Returns [`Tree`](#tree). | Name | Type | Description | | ---- | ---- | ----------- | -| `path` | [`String`](#string) | The path to get the tree for. Default value is the root of the repository. | +| `path` | [`String`](#string) | Path to get the tree for. Default value is the root of the repository. | | `recursive` | [`Boolean`](#boolean) | Used to get a recursive tree. Default is false. | -| `ref` | [`String`](#string) | The commit ref to get the tree for. Default value is HEAD. | +| `ref` | [`String`](#string) | Commit ref to get the tree for. Default value is HEAD. | ### `RepositoryBlob` @@ -13002,7 +13563,7 @@ Returns [`Tree`](#tree). | `canModifyBlob` | [`Boolean`](#boolean) | Whether the current user can modify the blob. | | `editBlobPath` | [`String`](#string) | Web path to edit the blob in the old-style editor. | | `externalStorageUrl` | [`String`](#string) | Web path to download the raw blob via external storage, if enabled. | -| `fileType` | [`String`](#string) | The expected format of the blob based on the extension. | +| `fileType` | [`String`](#string) | Expected format of the blob based on the extension. | | `forkAndEditPath` | [`String`](#string) | Web path to edit this blob using a forked project. | | `id` | [`ID!`](#id) | ID of the blob. | | `ideEditPath` | [`String`](#string) | Web path to edit this blob in the Web IDE. | @@ -13013,10 +13574,10 @@ Returns [`Tree`](#tree). | `oid` | [`String!`](#string) | OID of the blob. | | `path` | [`String!`](#string) | Path of the blob. | | `plainData` | [`String`](#string) | Blob plain highlighted data. | -| `rawBlob` | [`String`](#string) | The raw content of the blob. | +| `rawBlob` | [`String`](#string) | Raw content of the blob. | | `rawPath` | [`String`](#string) | Web path to download the raw blob. | | `rawSize` | [`Int`](#int) | Size (in bytes) of the blob, or the blob target if stored externally. | -| `rawTextBlob` | [`String`](#string) | The raw content of the blob, if the blob is text data. | +| `rawTextBlob` | [`String`](#string) | Raw content of the blob, if the blob is text data. | | `replacePath` | [`String`](#string) | Web path to replace the blob content. | | `richViewer` | [`BlobViewer`](#blobviewer) | Blob content rich viewer. | | `simpleViewer` | [`BlobViewer!`](#blobviewer) | Blob content simple viewer. | @@ -13096,15 +13657,15 @@ Counts of requirements by their state. | Name | Type | Description | | ---- | ---- | ----------- | -| `buildArtifactsSize` | [`Float!`](#float) | The CI artifacts size in bytes. | -| `lfsObjectsSize` | [`Float!`](#float) | The LFS objects size in bytes. | -| `packagesSize` | [`Float!`](#float) | The packages size in bytes. | -| `pipelineArtifactsSize` | [`Float!`](#float) | The CI pipeline artifacts size in bytes. | -| `repositorySize` | [`Float!`](#float) | The Git repository size in bytes. | -| `snippetsSize` | [`Float!`](#float) | The snippets size in bytes. | -| `storageSize` | [`Float!`](#float) | The total storage in bytes. | -| `uploadsSize` | [`Float!`](#float) | The uploads size in bytes. | -| `wikiSize` | [`Float!`](#float) | The wiki size in bytes. | +| `buildArtifactsSize` | [`Float!`](#float) | CI artifacts size in bytes. | +| `lfsObjectsSize` | [`Float!`](#float) | LFS objects size in bytes. | +| `packagesSize` | [`Float!`](#float) | Packages size in bytes. | +| `pipelineArtifactsSize` | [`Float!`](#float) | CI pipeline artifacts size in bytes. | +| `repositorySize` | [`Float!`](#float) | Git repository size in bytes. | +| `snippetsSize` | [`Float!`](#float) | Snippets size in bytes. | +| `storageSize` | [`Float!`](#float) | Total storage in bytes. | +| `uploadsSize` | [`Float!`](#float) | Uploads size in bytes. | +| `wikiSize` | [`Float!`](#float) | Wiki size in bytes. | ### `RunnerArchitecture` @@ -13221,8 +13782,8 @@ Represents a resource scanned by a security scan. | Name | Type | Description | | ---- | ---- | ----------- | -| `requestMethod` | [`String`](#string) | The HTTP request method used to access the URL. | -| `url` | [`String`](#string) | The URL scanned by the scanner. | +| `requestMethod` | [`String`](#string) | HTTP request method used to access the URL. | +| `url` | [`String`](#string) | URL scanned by the scanner. | ### `SecurityReportSummary` @@ -13238,6 +13799,7 @@ Represents summary of a security report. | `coverageFuzzing` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `coverage_fuzzing` scan. | | `dast` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `dast` scan. | | `dependencyScanning` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `dependency_scanning` scan. | +| `generic` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `generic` scan. | | `sast` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `sast` scan. | | `secretDetection` | [`SecurityReportSummarySection`](#securityreportsummarysection) | Aggregated counts for the `secret_detection` scan. | @@ -13249,7 +13811,7 @@ Represents a section of a summary of a security report. | Name | Type | Description | | ---- | ---- | ----------- | -| `scannedResources` | [`ScannedResourceConnection`](#scannedresourceconnection) | A list of the first 20 scanned resources. (see [Connections](#connections)) | +| `scannedResources` | [`ScannedResourceConnection`](#scannedresourceconnection) | List of the first 20 scanned resources. (see [Connections](#connections)) | | `scannedResourcesCount` | [`Int`](#int) | Total number of scanned resources. | | `scannedResourcesCsvPath` | [`String`](#string) | Path to download all the scanned resources in CSV format. | | `scans` | [`ScanConnection!`](#scanconnection) | List of security scans ran for the type. (see [Connections](#connections)) | @@ -13448,7 +14010,7 @@ Represents a snippet entry. | Name | Type | Description | | ---- | ---- | ----------- | -| `author` | [`UserCore`](#usercore) | The owner of the snippet. | +| `author` | [`UserCore`](#usercore) | Owner of the snippet. | | `createdAt` | [`Time!`](#time) | Timestamp this snippet was created. | | `description` | [`String`](#string) | Description of the snippet. | | `descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | @@ -13457,7 +14019,7 @@ Represents a snippet entry. | `httpUrlToRepo` | [`String`](#string) | HTTP URL to the snippet repository. | | `id` | [`SnippetID!`](#snippetid) | ID of the snippet. | | `notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | -| `project` | [`Project`](#project) | The project the snippet is associated with. | +| `project` | [`Project`](#project) | Project the snippet is associated with. | | `rawUrl` | [`String!`](#string) | Raw URL of the snippet. | | `sshUrlToRepo` | [`String`](#string) | SSH URL to the snippet repository. | | `title` | [`String!`](#string) | Title of the snippet. | @@ -13499,7 +14061,7 @@ Represents the snippet blob. | `path` | [`String`](#string) | Blob path. | | `plainData` | [`String`](#string) | Blob plain highlighted data. | | `rawPath` | [`String!`](#string) | Blob raw content endpoint path. | -| `rawPlainData` | [`String`](#string) | The raw content of the blob, if the blob is text data. | +| `rawPlainData` | [`String`](#string) | Raw content of the blob, if the blob is text data. | | `renderedAsText` | [`Boolean!`](#boolean) | Shows whether the blob is rendered as text. | | `richData` | [`String`](#string) | Blob highlighted data. | | `richViewer` | [`SnippetBlobViewer`](#snippetblobviewer) | Blob content rich viewer. | @@ -13599,9 +14161,9 @@ Completion status of tasks. | ---- | ---- | ----------- | | `createdAt` | [`Time!`](#time) | Timestamp the Terraform state was created. | | `id` | [`ID!`](#id) | ID of the Terraform state. | -| `latestVersion` | [`TerraformStateVersion`](#terraformstateversion) | The latest version of the Terraform state. | +| `latestVersion` | [`TerraformStateVersion`](#terraformstateversion) | Latest version of the Terraform state. | | `lockedAt` | [`Time`](#time) | Timestamp the Terraform state was locked. | -| `lockedByUser` | [`UserCore`](#usercore) | The user currently holding a lock on the Terraform state. | +| `lockedByUser` | [`UserCore`](#usercore) | User currently holding a lock on the Terraform state. | | `name` | [`String!`](#string) | Name of the Terraform state. | | `updatedAt` | [`Time!`](#time) | Timestamp the Terraform state was updated. | @@ -13612,10 +14174,10 @@ Completion status of tasks. | Name | Type | Description | | ---- | ---- | ----------- | | `createdAt` | [`Time!`](#time) | Timestamp the version was created. | -| `createdByUser` | [`UserCore`](#usercore) | The user that created this version. | +| `createdByUser` | [`UserCore`](#usercore) | User that created this version. | | `downloadPath` | [`String`](#string) | URL for downloading the version's JSON file. | | `id` | [`ID!`](#id) | ID of the Terraform state version. | -| `job` | [`CiJob`](#cijob) | The job that created this version. | +| `job` | [`CiJob`](#cijob) | Job that created this version. | | `serial` | [`Int`](#int) | Serial number of the version. | | `updatedAt` | [`Time!`](#time) | Timestamp the version was updated. | @@ -13750,8 +14312,8 @@ Represents measured stats metrics for timeboxes. | Name | Type | Description | | ---- | ---- | ----------- | -| `count` | [`Int!`](#int) | The count metric. | -| `weight` | [`Int!`](#int) | The weight metric. | +| `count` | [`Int!`](#int) | Count metric. | +| `weight` | [`Int!`](#int) | Weight metric. | ### `TimeboxReport` @@ -13770,13 +14332,13 @@ Represents a historically accurate report about the timebox. | Name | Type | Description | | ---- | ---- | ----------- | -| `issue` | [`Issue`](#issue) | The issue that logged time was added to. | -| `mergeRequest` | [`MergeRequest`](#mergerequest) | The merge request that logged time was added to. | -| `note` | [`Note`](#note) | The note where the quick action to add the logged time was executed. | +| `issue` | [`Issue`](#issue) | Issue that logged time was added to. | +| `mergeRequest` | [`MergeRequest`](#mergerequest) | Merge request that logged time was added to. | +| `note` | [`Note`](#note) | Note where the quick action was executed to add the logged time. | | `spentAt` | [`Time`](#time) | Timestamp of when the time tracked was spent at. | -| `summary` | [`String`](#string) | The summary of how the time was spent. | -| `timeSpent` | [`Int!`](#int) | The time spent displayed in seconds. | -| `user` | [`UserCore!`](#usercore) | The user that logged the time. | +| `summary` | [`String`](#string) | Summary of how the time was spent. | +| `timeSpent` | [`Int!`](#int) | Time spent displayed in seconds. | +| `user` | [`UserCore!`](#usercore) | User that logged the time. | ### `Todo` @@ -13787,12 +14349,12 @@ Representing a to-do entry. | Name | Type | Description | | ---- | ---- | ----------- | | `action` | [`TodoActionEnum!`](#todoactionenum) | Action of the to-do item. | -| `author` | [`UserCore!`](#usercore) | The author of this to-do item. | +| `author` | [`UserCore!`](#usercore) | Author of this to-do item. | | `body` | [`String!`](#string) | Body of the to-do item. | | `createdAt` | [`Time!`](#time) | Timestamp this to-do item was created. | | `group` | [`Group`](#group) | Group this to-do item is associated with. | | `id` | [`ID!`](#id) | ID of the to-do item. | -| `project` | [`Project`](#project) | The project this to-do item is associated with. | +| `project` | [`Project`](#project) | Project this to-do item is associated with. | | `state` | [`TodoStateEnum!`](#todostateenum) | State of the to-do item. | | `targetType` | [`TodoTargetEnum!`](#todotargetenum) | Target type of the to-do item. | @@ -13824,6 +14386,23 @@ Represents a directory. | `webPath` | [`String`](#string) | Web path for the tree entry (directory). | | `webUrl` | [`String`](#string) | Web URL for the tree entry (directory). | +### `UploadRegistry` + +Represents the Geo replication and verification state of an upload. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `createdAt` | [`Time`](#time) | Timestamp when the UploadRegistry was created. | +| `fileId` | [`ID!`](#id) | ID of the Upload. | +| `id` | [`ID!`](#id) | ID of the UploadRegistry. | +| `lastSyncFailure` | [`String`](#string) | Error message during sync of the UploadRegistry. | +| `lastSyncedAt` | [`Time`](#time) | Timestamp of the most recent successful sync of the UploadRegistry. | +| `retryAt` | [`Time`](#time) | Timestamp after which the UploadRegistry should be resynced. | +| `retryCount` | [`Int`](#int) | Number of consecutive failed sync attempts of the UploadRegistry. | +| `state` | [`RegistryState`](#registrystate) | Sync state of the UploadRegistry. | + ### `UsageTrendsMeasurement` Represents a recorded measurement (object count) for the Admins. @@ -13833,8 +14412,8 @@ Represents a recorded measurement (object count) for the Admins. | Name | Type | Description | | ---- | ---- | ----------- | | `count` | [`Int!`](#int) | Object count. | -| `identifier` | [`MeasurementIdentifier!`](#measurementidentifier) | The type of objects being measured. | -| `recordedAt` | [`Time`](#time) | The time the measurement was recorded. | +| `identifier` | [`MeasurementIdentifier!`](#measurementidentifier) | Type of objects being measured. | +| `recordedAt` | [`Time`](#time) | Time the measurement was recorded. | ### `UserCallout` @@ -13860,7 +14439,7 @@ Core represention of a GitLab user. | `groupCount` | [`Int`](#int) | Group count for the user. | | `groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | `id` | [`ID!`](#id) | ID of the user. | -| `location` | [`String`](#string) | The location of the user. | +| `location` | [`String`](#string) | Location of the user. | | `name` | [`String!`](#string) | Human-readable name of the user. | | `namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | | `projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -13900,7 +14479,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `reviewerUsername` | [`String`](#string) | Username of the reviewer. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `UserCore.authoredMergeRequests` @@ -13929,9 +14508,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | `reviewerUsername` | [`String`](#string) | Username of the reviewer. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +##### `UserCore.groups` + +Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. + +Returns [`GroupConnection`](#groupconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +###### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| `search` | [`String`](#string) | Search by group name or path. | + ##### `UserCore.reviewRequestedMergeRequests` Merge requests assigned to the user for review. @@ -13958,7 +14554,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ##### `UserCore.snippets` @@ -13976,7 +14572,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | `ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| `type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| `type` | [`TypeEnum`](#typeenum) | Type of snippet. | | `visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ##### `UserCore.starredProjects` @@ -14031,12 +14627,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| `authorId` | [`[ID!]`](#id) | The ID of an author. | -| `groupId` | [`[ID!]`](#id) | The ID of a group. | -| `projectId` | [`[ID!]`](#id) | The ID of a project. | -| `state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| `action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| `authorId` | [`[ID!]`](#id) | ID of an author. | +| `groupId` | [`[ID!]`](#id) | ID of a group. | +| `projectId` | [`[ID!]`](#id) | ID of a project. | +| `state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ### `UserMergeRequestInteraction` @@ -14053,7 +14649,7 @@ fields relate to interactions between the two entities. | `approved` | [`Boolean!`](#boolean) | Whether this user has approved this merge request. | | `canMerge` | [`Boolean!`](#boolean) | Whether this user can merge this merge request. | | `canUpdate` | [`Boolean!`](#boolean) | Whether this user can update this merge request. | -| `reviewState` | [`MergeRequestReviewState`](#mergerequestreviewstate) | The state of the review by this user. | +| `reviewState` | [`MergeRequestReviewState`](#mergerequestreviewstate) | State of the review by this user. | | `reviewed` | [`Boolean!`](#boolean) | Whether this user has provided a review for this merge request. | ### `UserPermissions` @@ -14101,15 +14697,15 @@ Represents a vulnerability. | Name | Type | Description | | ---- | ---- | ----------- | | `confirmedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to confirmed. | -| `confirmedBy` | [`UserCore`](#usercore) | The user that confirmed the vulnerability. | +| `confirmedBy` | [`UserCore`](#usercore) | User that confirmed the vulnerability. | | `description` | [`String`](#string) | Description of the vulnerability. | | `details` | [`[VulnerabilityDetail!]!`](#vulnerabilitydetail) | Details of the vulnerability. | | `detectedAt` | [`Time!`](#time) | Timestamp of when the vulnerability was first detected. | | `discussions` | [`DiscussionConnection!`](#discussionconnection) | All discussions on this noteable. (see [Connections](#connections)) | | `dismissedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to dismissed. | -| `dismissedBy` | [`UserCore`](#usercore) | The user that dismissed the vulnerability. | +| `dismissedBy` | [`UserCore`](#usercore) | User that dismissed the vulnerability. | | `externalIssueLinks` | [`VulnerabilityExternalIssueLinkConnection!`](#vulnerabilityexternalissuelinkconnection) | List of external issue links related to the vulnerability. (see [Connections](#connections)) | -| `falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. Available only when feature flag `vulnerability_flags` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. | +| `falsePositive` | [`Boolean`](#boolean) | Indicates whether the vulnerability is a false positive. | | `hasSolutions` | [`Boolean`](#boolean) | Indicates whether there is a solution available for this vulnerability. | | `id` | [`ID!`](#id) | GraphQL ID of the vulnerability. | | `identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerability. | @@ -14117,10 +14713,10 @@ Represents a vulnerability. | `mergeRequest` | [`MergeRequest`](#mergerequest) | Merge request that fixes the vulnerability. | | `notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | `primaryIdentifier` | [`VulnerabilityIdentifier`](#vulnerabilityidentifier) | Primary identifier of the vulnerability. | -| `project` | [`Project`](#project) | The project on which the vulnerability was found. | -| `reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING, CLUSTER_IMAGE_SCANNING). `Scan Type` in the UI. | +| `project` | [`Project`](#project) | Project on which the vulnerability was found. | +| `reportType` | [`VulnerabilityReportType`](#vulnerabilityreporttype) | Type of the security report that found the vulnerability (SAST, DEPENDENCY_SCANNING, CONTAINER_SCANNING, DAST, SECRET_DETECTION, COVERAGE_FUZZING, API_FUZZING, CLUSTER_IMAGE_SCANNING, GENERIC). `Scan Type` in the UI. | | `resolvedAt` | [`Time`](#time) | Timestamp of when the vulnerability state was changed to resolved. | -| `resolvedBy` | [`UserCore`](#usercore) | The user that resolved the vulnerability. | +| `resolvedBy` | [`UserCore`](#usercore) | User that resolved the vulnerability. | | `resolvedOnDefaultBranch` | [`Boolean!`](#boolean) | Indicates whether the vulnerability is fixed on the default branch or not. | | `scanner` | [`VulnerabilityScanner`](#vulnerabilityscanner) | Scanner metadata for the vulnerability. | | `severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability (INFO, UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL). | @@ -14198,7 +14794,7 @@ Represents the vulnerability details commit field. | `description` | [`String`](#string) | Description of the field. | | `fieldName` | [`String`](#string) | Name of the field. | | `name` | [`String`](#string) | Name of the field. | -| `value` | [`String!`](#string) | The commit SHA value. | +| `value` | [`String!`](#string) | Commit SHA value. | ### `VulnerabilityDetailDiff` @@ -14357,7 +14953,7 @@ Represents an issue link of a vulnerability. | Name | Type | Description | | ---- | ---- | ----------- | | `id` | [`ID!`](#id) | GraphQL ID of the vulnerability. | -| `issue` | [`Issue!`](#issue) | The issue attached to issue link. | +| `issue` | [`Issue!`](#issue) | Issue attached to issue link. | | `linkType` | [`VulnerabilityIssueLinkType!`](#vulnerabilityissuelinktype) | Type of the issue link. | ### `VulnerabilityLocationContainerScanning` @@ -14412,6 +15008,16 @@ Represents the location of a vulnerability found by a dependency security scan. | `dependency` | [`VulnerableDependency`](#vulnerabledependency) | Dependency containing the vulnerability. | | `file` | [`String`](#string) | Path to the vulnerable file. | +### `VulnerabilityLocationGeneric` + +Represents the location of a vulnerability found by a generic scanner. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `description` | [`String`](#string) | Free-form description of where the vulnerability is located. | + ### `VulnerabilityLocationSast` Represents the location of a vulnerability found by a SAST scan. @@ -14497,8 +15103,8 @@ Represents a vulnerable dependency. Used in vulnerability location data. | Name | Type | Description | | ---- | ---- | ----------- | -| `package` | [`VulnerablePackage`](#vulnerablepackage) | The package associated with the vulnerable dependency. | -| `version` | [`String`](#string) | The version of the vulnerable dependency. | +| `package` | [`VulnerablePackage`](#vulnerablepackage) | Package associated with the vulnerable dependency. | +| `version` | [`String`](#string) | Version of the vulnerable dependency. | ### `VulnerablePackage` @@ -14508,7 +15114,7 @@ Represents a vulnerable package. Used in vulnerability dependency data. | Name | Type | Description | | ---- | ---- | ----------- | -| `name` | [`String`](#string) | The name of the vulnerable package. | +| `name` | [`String`](#string) | Name of the vulnerable package. | ### `VulnerableProjectsByGrade` @@ -14698,8 +15304,8 @@ Values for YAML processor result. | Value | Description | | ----- | ----------- | -| `INVALID` | The configuration file is not valid. | -| `VALID` | The configuration file is valid. | +| `INVALID` | Configuration file is not valid. | +| `VALID` | Configuration file is valid. | ### `CiJobStatus` @@ -14827,10 +15433,10 @@ Status of the tags cleanup of a container repository. | Value | Description | | ----- | ----------- | -| `ONGOING` | The tags cleanup is ongoing. | -| `SCHEDULED` | The tags cleanup is scheduled and is going to be executed shortly. | -| `UNFINISHED` | The tags cleanup has been partially executed. There are still remaining tags to delete. | -| `UNSCHEDULED` | The tags cleanup is not scheduled. This is the default state. | +| `ONGOING` | Tags cleanup is ongoing. | +| `SCHEDULED` | Tags cleanup is scheduled and is going to be executed shortly. | +| `UNFINISHED` | Tags cleanup has been partially executed. There are still remaining tags to delete. | +| `UNSCHEDULED` | Tags cleanup is not scheduled. This is the default state. | ### `ContainerRepositorySort` @@ -14858,6 +15464,17 @@ Status of a container repository. | `DELETE_FAILED` | Delete Failed status. | | `DELETE_SCHEDULED` | Delete Scheduled status. | +### `DastProfileCadenceUnit` + +Unit for the duration of Dast Profile Cadence. + +| Value | Description | +| ----- | ----------- | +| `DAY` | DAST Profile Cadence duration in days. | +| `MONTH` | DAST Profile Cadence duration in months. | +| `WEEK` | DAST Profile Cadence duration in weeks. | +| `YEAR` | DAST Profile Cadence duration in years. | + ### `DastScanTypeEnum` | Value | Description | @@ -14875,6 +15492,15 @@ Status of a container repository. | `PASSED_VALIDATION` | Site validation process finished successfully. | | `PENDING_VALIDATION` | Site validation process has not started. | +### `DastSiteValidationStatusEnum` + +| Value | Description | +| ----- | ----------- | +| `FAILED_VALIDATION` | Site validation process finished but failed. | +| `INPROGRESS_VALIDATION` | Site validation process is in progress. | +| `PASSED_VALIDATION` | Site validation process finished successfully. | +| `PENDING_VALIDATION` | Site validation process has not started. | + ### `DastSiteValidationStrategyEnum` | Value | Description | @@ -14960,7 +15586,7 @@ Type of file the position refers to. | Value | Description | | ----- | ----------- | | `image` | An image. | -| `text` | A text file. | +| `text` | Text file. | ### `DoraMetricBucketingInterval` @@ -15074,6 +15700,14 @@ Group member relation. | `DIRECT` | Members in the group itself. | | `INHERITED` | Members in the group's ancestor groups. | +### `GroupPermission` + +User permission on groups. + +| Value | Description | +| ----- | ----------- | +| `CREATE_PROJECTS` | Groups where the user can create projects. | + ### `HealthStatus` Health status of an issue or epic. @@ -15143,6 +15777,8 @@ Values for sorting issues. | `SEVERITY_DESC` | Severity from more critical to less critical. | | `SLA_DUE_AT_ASC` | Issues with earliest SLA due time shown first. | | `SLA_DUE_AT_DESC` | Issues with latest SLA due time shown first. | +| `TITLE_ASC` | Title by ascending order. | +| `TITLE_DESC` | Title by descending order. | | `UPDATED_ASC` | Updated at ascending order. | | `UPDATED_DESC` | Updated at descending order. | | `WEIGHT_ASC` | Weight by ascending order. | @@ -15189,12 +15825,12 @@ State of a GitLab iteration. | Value | Description | | ----- | ----------- | -| `all` | | -| `closed` | | -| `current` | | -| `opened` | | +| `all` | Any iteration. | +| `closed` | Closed iteration. | +| `current` | Current iteration. | +| `opened` | Open iteration. | | `started` **{warning-solid}** | **Deprecated** in 14.1. Use current instead. | -| `upcoming` | | +| `upcoming` | Upcoming iteration. | ### `IterationWildcardId` @@ -15374,10 +16010,10 @@ Milestone ID wildcard values. | Value | Description | | ----- | ----------- | -| `ANY` | A milestone is assigned. | +| `ANY` | Milestone is assigned. | | `NONE` | No milestone is assigned. | -| `STARTED` | An open, started milestone (start date <= today). | -| `UPCOMING` | An open milestone due in the future (due date >= today). | +| `STARTED` | Milestone assigned is open and started (start date <= today). | +| `UPCOMING` | Milestone assigned is due closest in the future (due date > today). | ### `MoveType` @@ -15385,8 +16021,8 @@ The position to which the adjacent object should be moved. | Value | Description | | ----- | ----------- | -| `after` | The adjacent object will be moved after the object that is being moved. | -| `before` | The adjacent object will be moved before the object that is being moved. | +| `after` | Adjacent object is moved after the object that is being moved. | +| `before` | Adjacent object is moved before the object that is being moved. | ### `MutationOperationMode` @@ -15421,8 +16057,8 @@ Negated Milestone ID wildcard values. | Value | Description | | ----- | ----------- | -| `STARTED` | An open, started milestone (start date <= today). | -| `UPCOMING` | An open milestone due in the future (due date >= today). | +| `STARTED` | Milestone assigned is open and yet to be started (start date > today). | +| `UPCOMING` | Milestone assigned is open but due in the past (due date <= today). | ### `NetworkPolicyKind` @@ -15430,8 +16066,8 @@ Kind of the network policy. | Value | Description | | ----- | ----------- | -| `CiliumNetworkPolicy` | The policy kind of Cilium Network Policy. | -| `NetworkPolicy` | The policy kind of Network Policy. | +| `CiliumNetworkPolicy` | Policy kind of Cilium Network Policy. | +| `NetworkPolicy` | Policy kind of Network Policy. | ### `OncallRotationUnitEnum` @@ -15590,8 +16226,8 @@ State of a requirement. | Value | Description | | ----- | ----------- | -| `ARCHIVED` | | -| `OPENED` | | +| `ARCHIVED` | Archived requirement. | +| `OPENED` | Open requirement. | ### `RequirementStatusFilter` @@ -15599,9 +16235,18 @@ Status of a requirement based on last test report. | Value | Description | | ----- | ----------- | -| `FAILED` | | +| `FAILED` | Failed test report. | | `MISSING` | Requirements without any test report. | -| `PASSED` | | +| `PASSED` | Passed test report. | + +### `RunnerMembershipFilter` + +Values for filtering runners in namespaces. + +| Value | Description | +| ----- | ----------- | +| `DESCENDANTS` | Include runners that have either a direct relationship or a relationship with descendants. These can be project runners or group runners (in the case where group is queried). | +| `DIRECT` | Include runners that have a direct relationship. | ### `SastUiComponentSize` @@ -15609,9 +16254,9 @@ Size of UI component in SAST configuration page. | Value | Description | | ----- | ----------- | -| `LARGE` | The size of UI component in SAST configuration page is large. | -| `MEDIUM` | The size of UI component in SAST configuration page is medium. | -| `SMALL` | The size of UI component in SAST configuration page is small. | +| `LARGE` | Size of UI component in SAST configuration page is large. | +| `MEDIUM` | Size of UI component in SAST configuration page is medium. | +| `SMALL` | Size of UI component in SAST configuration page is small. | ### `SecurityReportTypeEnum` @@ -15632,14 +16277,14 @@ The type of the security scanner. | Value | Description | | ----- | ----------- | -| `API_FUZZING` | | -| `CLUSTER_IMAGE_SCANNING` | | -| `CONTAINER_SCANNING` | | -| `COVERAGE_FUZZING` | | -| `DAST` | | -| `DEPENDENCY_SCANNING` | | -| `SAST` | | -| `SECRET_DETECTION` | | +| `API_FUZZING` | API Fuzzing scanner. | +| `CLUSTER_IMAGE_SCANNING` | Cluster Image Scanning scanner. | +| `CONTAINER_SCANNING` | Container Scanning scanner. | +| `COVERAGE_FUZZING` | Coverage Fuzzing scanner. | +| `DAST` | DAST scanner. | +| `DEPENDENCY_SCANNING` | Dependency Scanning scanner. | +| `SAST` | SAST scanner. | +| `SECRET_DETECTION` | Secret Detection scanner. | ### `SentryErrorStatus` @@ -15741,8 +16386,8 @@ State of a test report. | Value | Description | | ----- | ----------- | -| `FAILED` | | -| `PASSED` | | +| `FAILED` | Failed test report. | +| `PASSED` | Passed test report. | ### `TodoActionEnum` @@ -15762,19 +16407,19 @@ State of a test report. | Value | Description | | ----- | ----------- | -| `done` | The state of the todo is done. | -| `pending` | The state of the todo is pending. | +| `done` | State of the todo is done. | +| `pending` | State of the todo is pending. | ### `TodoTargetEnum` | Value | Description | | ----- | ----------- | -| `ALERT` | An Alert. | -| `COMMIT` | A Commit. | -| `DESIGN` | A Design. | +| `ALERT` | Alert. | +| `COMMIT` | Commit. | +| `DESIGN` | Design. | | `EPIC` | An Epic. | -| `ISSUE` | An Issue. | -| `MERGEREQUEST` | A MergeRequest. | +| `ISSUE` | Issue. | +| `MERGEREQUEST` | Merge request. | ### `TypeEnum` @@ -15789,7 +16434,6 @@ Name of the feature that the callout is for. | Value | Description | | ----- | ----------- | -| `ACCOUNT_RECOVERY_REGULAR_CHECK` | Callout feature name for account_recovery_regular_check. | | `ACTIVE_USER_COUNT_THRESHOLD` | Callout feature name for active_user_count_threshold. | | `BUY_PIPELINE_MINUTES_NOTIFICATION_DOT` | Callout feature name for buy_pipeline_minutes_notification_dot. | | `CANARY_DEPLOYMENT` | Callout feature name for canary_deployment. | @@ -15818,6 +16462,7 @@ Name of the feature that the callout is for. | `THREAT_MONITORING_INFO` | Callout feature name for threat_monitoring_info. | | `TRIAL_STATUS_REMINDER_D14` | Callout feature name for trial_status_reminder_d14. | | `TRIAL_STATUS_REMINDER_D3` | Callout feature name for trial_status_reminder_d3. | +| `TWO_FACTOR_AUTH_RECOVERY_SETTINGS_CHECK` | Callout feature name for two_factor_auth_recovery_settings_check. | | `ULTIMATE_TRIAL` | Callout feature name for ultimate_trial. | | `UNFINISHED_TAG_CLEANUP_CALLOUT` | Callout feature name for unfinished_tag_cleanup_callout. | | `WEB_IDE_ALERT_DISMISSED` | Callout feature name for web_ide_alert_dismissed. | @@ -15829,9 +16474,9 @@ Possible states of a user. | Value | Description | | ----- | ----------- | -| `active` | The user is active and is able to use the system. | -| `blocked` | The user has been blocked and is prevented from using the system. | -| `deactivated` | The user is no longer active and is unable to use the system. | +| `active` | User is active and is able to use the system. | +| `blocked` | User has been blocked and is prevented from using the system. | +| `deactivated` | User is no longer active and is unable to use the system. | ### `VisibilityLevelsEnum` @@ -15845,9 +16490,23 @@ Possible states of a user. | Value | Description | | ----- | ----------- | -| `internal` | The snippet is visible for any logged in user except external users. | -| `private` | The snippet is visible only to the snippet creator. | -| `public` | The snippet can be accessed without any authentication. | +| `internal` | Snippet is visible for any logged in user except external users. | +| `private` | Snippet is visible only to the snippet creator. | +| `public` | Snippet can be accessed without any authentication. | + +### `VulnerabilityConfidence` + +Confidence that a given vulnerability is present in the codebase. + +| Value | Description | +| ----- | ----------- | +| `CONFIRMED` | Confirmed confidence. | +| `EXPERIMENTAL` | Experimental confidence. | +| `HIGH` | High confidence. | +| `IGNORE` | Ignore confidence. | +| `LOW` | Low confidence. | +| `MEDIUM` | Medium confidence. | +| `UNKNOWN` | Unknown confidence. | ### `VulnerabilityDismissalReason` @@ -15883,11 +16542,11 @@ The grade of the vulnerable project. | Value | Description | | ----- | ----------- | -| `A` | | -| `B` | | -| `C` | | -| `D` | | -| `F` | | +| `A` | A grade. | +| `B` | B grade. | +| `C` | C grade. | +| `D` | D grade. | +| `F` | F grade. | ### `VulnerabilityIssueLinkType` @@ -15895,8 +16554,8 @@ The type of the issue link related to a vulnerability. | Value | Description | | ----- | ----------- | -| `CREATED` | | -| `RELATED` | | +| `CREATED` | Issue is created for the vulnerability. | +| `RELATED` | Has a related issue. | ### `VulnerabilityReportType` @@ -15904,14 +16563,15 @@ The type of the security scan that found the vulnerability. | Value | Description | | ----- | ----------- | -| `API_FUZZING` | | -| `CLUSTER_IMAGE_SCANNING` | | -| `CONTAINER_SCANNING` | | -| `COVERAGE_FUZZING` | | -| `DAST` | | -| `DEPENDENCY_SCANNING` | | -| `SAST` | | -| `SECRET_DETECTION` | | +| `API_FUZZING` | API Fuzzing report. | +| `CLUSTER_IMAGE_SCANNING` | Cluster Image Scanning report. | +| `CONTAINER_SCANNING` | Container Scanning report. | +| `COVERAGE_FUZZING` | Coverage Fuzzing report. | +| `DAST` | DAST report. | +| `DEPENDENCY_SCANNING` | Dependency Scanning report. | +| `GENERIC` | Generic report. | +| `SAST` | SAST report. | +| `SECRET_DETECTION` | Secret Detection report. | ### `VulnerabilitySeverity` @@ -15919,12 +16579,12 @@ The severity of the vulnerability. | Value | Description | | ----- | ----------- | -| `CRITICAL` | | -| `HIGH` | | -| `INFO` | | -| `LOW` | | -| `MEDIUM` | | -| `UNKNOWN` | | +| `CRITICAL` | Critical severity. | +| `HIGH` | High severity. | +| `INFO` | Info severity. | +| `LOW` | Low severity. | +| `MEDIUM` | Medium severity. | +| `UNKNOWN` | Unknown severity. | ### `VulnerabilitySort` @@ -15949,10 +16609,10 @@ The state of the vulnerability. | Value | Description | | ----- | ----------- | -| `CONFIRMED` | | -| `DETECTED` | | -| `DISMISSED` | | -| `RESOLVED` | | +| `CONFIRMED` | Confirmed vulnerability. | +| `DETECTED` | Detected vulnerability. | +| `DISMISSED` | Dismissed vulnerability. | +| `RESOLVED` | Resolved vulnerability. | ### `WeightWildcardId` @@ -16072,12 +16732,24 @@ A `CustomEmojiID` is a global ID. It is encoded as a string. An example `CustomEmojiID` is: `"gid://gitlab/CustomEmoji/1"`. +### `CustomerRelationsOrganizationID` + +A `CustomerRelationsOrganizationID` is a global ID. It is encoded as a string. + +An example `CustomerRelationsOrganizationID` is: `"gid://gitlab/CustomerRelations::Organization/1"`. + ### `DastProfileID` A `DastProfileID` is a global ID. It is encoded as a string. An example `DastProfileID` is: `"gid://gitlab/Dast::Profile/1"`. +### `DastProfileScheduleID` + +A `DastProfileScheduleID` is a global ID. It is encoded as a string. + +An example `DastProfileScheduleID` is: `"gid://gitlab/Dast::ProfileSchedule/1"`. + ### `DastScannerProfileID` A `DastScannerProfileID` is a global ID. It is encoded as a string. @@ -16550,6 +17222,7 @@ One of: - [`VulnerabilityLocationCoverageFuzzing`](#vulnerabilitylocationcoveragefuzzing) - [`VulnerabilityLocationDast`](#vulnerabilitylocationdast) - [`VulnerabilityLocationDependencyScanning`](#vulnerabilitylocationdependencyscanning) +- [`VulnerabilityLocationGeneric`](#vulnerabilitylocationgeneric) - [`VulnerabilityLocationSast`](#vulnerabilitylocationsast) - [`VulnerabilityLocationSecretDetection`](#vulnerabilitylocationsecretdetection) @@ -16614,16 +17287,16 @@ Implementations: | Name | Type | Description | | ---- | ---- | ----------- | -| `diffRefs` | [`DiffRefs!`](#diffrefs) | The diff refs for this design. | +| `diffRefs` | [`DiffRefs!`](#diffrefs) | Diff refs for this design. | | `event` | [`DesignVersionEvent!`](#designversionevent) | How this design was changed in the current version. | -| `filename` | [`String!`](#string) | The filename of the design. | -| `fullPath` | [`String!`](#string) | The full path to the design file. | -| `id` | [`ID!`](#id) | The ID of this design. | -| `image` | [`String!`](#string) | The URL of the full-sized image. | +| `filename` | [`String!`](#string) | Filename of the design. | +| `fullPath` | [`String!`](#string) | Full path to the design file. | +| `id` | [`ID!`](#id) | ID of this design. | +| `image` | [`String!`](#string) | URL of the full-sized image. | | `imageV432x230` | [`String`](#string) | The URL of the design resized to fit within the bounds of 432x230. This will be `null` if the image has not been generated. | -| `issue` | [`Issue!`](#issue) | The issue the design belongs to. | -| `notesCount` | [`Int!`](#int) | The total count of user-created notes for this design. | -| `project` | [`Project!`](#project) | The project the design belongs to. | +| `issue` | [`Issue!`](#issue) | Issue the design belongs to. | +| `notesCount` | [`Int!`](#int) | Total count of user-created notes for this design. | +| `project` | [`Project!`](#project) | Project the design belongs to. | #### `Entry` @@ -16655,7 +17328,7 @@ Implementations: | Name | Type | Description | | ---- | ---- | ----------- | -| `events` | [`EventConnection`](#eventconnection) | A list of events associated with the object. (see [Connections](#connections)) | +| `events` | [`EventConnection`](#eventconnection) | List of events associated with the object. (see [Connections](#connections)) | #### `MemberInterface` @@ -16776,7 +17449,7 @@ Implementations: | `groupCount` | [`Int`](#int) | Group count for the user. | | `groupMemberships` | [`GroupMemberConnection`](#groupmemberconnection) | Group memberships of the user. (see [Connections](#connections)) | | `id` | [`ID!`](#id) | ID of the user. | -| `location` | [`String`](#string) | The location of the user. | +| `location` | [`String`](#string) | Location of the user. | | `name` | [`String!`](#string) | Human-readable name of the user. | | `namespace` | [`Namespace`](#namespace) | Personal namespace of the user. | | `projectMemberships` | [`ProjectMemberConnection`](#projectmemberconnection) | Project memberships of the user. (see [Connections](#connections)) | @@ -16816,7 +17489,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `reviewerUsername` | [`String`](#string) | Username of the reviewer. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ###### `User.authoredMergeRequests` @@ -16845,9 +17518,26 @@ four standard [pagination arguments](#connection-pagination-arguments): | `reviewerUsername` | [`String`](#string) | Username of the reviewer. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | +###### `User.groups` + +Groups where the user has access. Will always return `null` if `paginatable_namespace_drop_down_for_project_creation` feature flag is disabled. + +Returns [`GroupConnection`](#groupconnection). + +This field returns a [connection](#connections). It accepts the +four standard [pagination arguments](#connection-pagination-arguments): +`before: String`, `after: String`, `first: Int`, `last: Int`. + +####### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `permissionScope` | [`GroupPermission`](#grouppermission) | Filter by permissions the user has on groups. | +| `search` | [`String`](#string) | Search by group name or path. | + ###### `User.reviewRequestedMergeRequests` Merge requests assigned to the user for review. @@ -16874,7 +17564,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | `projectPath` | [`String`](#string) | The full-path of the project the authored merge requests should be in. Incompatible with projectId. | | `sort` | [`MergeRequestSort`](#mergerequestsort) | Sort merge requests by this criteria. | | `sourceBranches` | [`[String!]`](#string) | Array of source branch names. All resolved merge requests will have one of these branches as their source. | -| `state` | [`MergeRequestState`](#mergerequeststate) | A merge request state. If provided, all resolved merge requests will have this state. | +| `state` | [`MergeRequestState`](#mergerequeststate) | Merge request state. If provided, all resolved merge requests will have this state. | | `targetBranches` | [`[String!]`](#string) | Array of target branch names. All resolved merge requests will have one of these branches as their target. | ###### `User.snippets` @@ -16892,7 +17582,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | `ids` | [`[SnippetID!]`](#snippetid) | Array of global snippet IDs. For example, `gid://gitlab/ProjectSnippet/1`. | -| `type` | [`TypeEnum`](#typeenum) | The type of snippet. | +| `type` | [`TypeEnum`](#typeenum) | Type of snippet. | | `visibility` | [`VisibilityScopesEnum`](#visibilityscopesenum) | Visibility of the snippet. | ###### `User.starredProjects` @@ -16947,12 +17637,12 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | -| `action` | [`[TodoActionEnum!]`](#todoactionenum) | The action to be filtered. | -| `authorId` | [`[ID!]`](#id) | The ID of an author. | -| `groupId` | [`[ID!]`](#id) | The ID of a group. | -| `projectId` | [`[ID!]`](#id) | The ID of a project. | -| `state` | [`[TodoStateEnum!]`](#todostateenum) | The state of the todo. | -| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | The type of the todo. | +| `action` | [`[TodoActionEnum!]`](#todoactionenum) | Action to be filtered. | +| `authorId` | [`[ID!]`](#id) | ID of an author. | +| `groupId` | [`[ID!]`](#id) | ID of a group. | +| `projectId` | [`[ID!]`](#id) | ID of a project. | +| `state` | [`[TodoStateEnum!]`](#todostateenum) | State of the todo. | +| `type` | [`[TodoTargetEnum!]`](#todotargetenum) | Type of the todo. | ## Input types @@ -16970,7 +17660,7 @@ Field that are available while modifying the custom mapping attributes for an HT | Name | Type | Description | | ---- | ---- | ----------- | -| `fieldName` | [`AlertManagementPayloadAlertFieldName!`](#alertmanagementpayloadalertfieldname) | A GitLab alert field name. | +| `fieldName` | [`AlertManagementPayloadAlertFieldName!`](#alertmanagementpayloadalertfieldname) | GitLab alert field name. | | `label` | [`String`](#string) | Human-readable label of the payload path. | | `path` | [`[PayloadAlertFieldPathSegment!]!`](#payloadalertfieldpathsegment) | Path to value inside payload JSON. | | `type` | [`AlertManagementPayloadAlertFieldType!`](#alertmanagementpayloadalertfieldtype) | Type of the parsed value. | @@ -16992,7 +17682,8 @@ Field that are available while modifying the custom mapping attributes for an HT | `iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | | `labelName` | [`[String]`](#string) | Filter by label name. | | `milestoneTitle` | [`String`](#string) | Filter by milestone title. | -| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| `milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter by milestone ID wildcard. | +| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | `not` | [`NegatedBoardIssueInput`](#negatedboardissueinput) | List of negated arguments. | | `releaseTag` | [`String`](#string) | Filter by release tag. | | `search` | [`String`](#string) | Search query for issue title or description. | @@ -17006,7 +17697,7 @@ Field that are available while modifying the custom mapping attributes for an HT | Name | Type | Description | | ---- | ---- | ----------- | -| `action` | [`CommitActionMode!`](#commitactionmode) | The action to perform, create, delete, move, update, chmod. | +| `action` | [`CommitActionMode!`](#commitactionmode) | Action to perform: create, delete, move, update, or chmod. | | `content` | [`String`](#string) | Content of the file. | | `encoding` | [`CommitEncoding`](#commitencoding) | Encoding of the file. Default is text. | | `executeFilemode` | [`Boolean`](#boolean) | Enables/disables the execute flag on the file. | @@ -17025,6 +17716,30 @@ Field that are available while modifying the custom mapping attributes for an HT | `name` | [`String`](#string) | New name for the compliance framework. | | `pipelineConfigurationFullPath` | [`String`](#string) | Full path of the compliance pipeline configuration stored in a project repository, such as `.gitlab/.compliance-gitlab-ci.yml@compliance/hipaa` **(ULTIMATE)**. | +### `DastProfileCadenceInput` + +Represents DAST Profile Cadence. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `duration` | [`Int`](#int) | Duration of the DAST Profile Cadence. | +| `unit` | [`DastProfileCadenceUnit`](#dastprofilecadenceunit) | Unit for the duration of DAST Profile Cadence. | + +### `DastProfileScheduleInput` + +Input type for DAST Profile Schedules. + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `active` | [`Boolean`](#boolean) | Status of a Dast Profile Schedule. | +| `cadence` | [`DastProfileCadenceInput`](#dastprofilecadenceinput) | Cadence of a Dast Profile Schedule. | +| `startsAt` | [`Time`](#time) | Start time of a Dast Profile Schedule. | +| `timezone` | [`String`](#string) | Time Zone for the Start time of a Dast Profile Schedule. | + ### `DastSiteProfileAuthInput` Input type for DastSiteProfile authentication. @@ -17034,11 +17749,11 @@ Input type for DastSiteProfile authentication. | Name | Type | Description | | ---- | ---- | ----------- | | `enabled` | [`Boolean`](#boolean) | Indicates whether authentication is enabled. | -| `password` | [`String`](#string) | The password to authenticate with on the target website. | -| `passwordField` | [`String`](#string) | The name of password field at the sign-in HTML form. | +| `password` | [`String`](#string) | Password to authenticate with on the target website. | +| `passwordField` | [`String`](#string) | Name of password field at the sign-in HTML form. | | `url` | [`String`](#string) | The URL of the page containing the sign-in HTML form on the target website. | -| `username` | [`String`](#string) | The username to authenticate with on the target website. | -| `usernameField` | [`String`](#string) | The name of username field at the sign-in HTML form. | +| `username` | [`String`](#string) | Username to authenticate with on the target website. | +| `usernameField` | [`String`](#string) | Name of username field at the sign-in HTML form. | ### `DiffImagePositionInput` @@ -17061,8 +17776,8 @@ Input type for DastSiteProfile authentication. | Name | Type | Description | | ---- | ---- | ----------- | -| `newPath` | [`String`](#string) | The path of the file on the head sha. | -| `oldPath` | [`String`](#string) | The path of the file on the start sha. | +| `newPath` | [`String`](#string) | Path of the file on the HEAD SHA. | +| `oldPath` | [`String`](#string) | Path of the file on the start SHA. | ### `DiffPositionInput` @@ -17085,7 +17800,7 @@ Input type for DastSiteProfile authentication. | ---- | ---- | ----------- | | `authorUsername` | [`String`](#string) | Filter by author username. | | `labelName` | [`[String]`](#string) | Filter by label name. | -| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | `not` | [`NegatedEpicBoardIssueInput`](#negatedepicboardissueinput) | Negated epic arguments. | | `search` | [`String`](#string) | Search query for epic title or description. | @@ -17097,10 +17812,10 @@ A node of an epic tree. | Name | Type | Description | | ---- | ---- | ----------- | -| `adjacentReferenceId` | [`EpicTreeSortingID`](#epictreesortingid) | The ID of the epic_issue or issue that the actual epic or issue is switched with. | -| `id` | [`EpicTreeSortingID!`](#epictreesortingid) | The ID of the epic_issue or epic that is being moved. | +| `adjacentReferenceId` | [`EpicTreeSortingID`](#epictreesortingid) | ID of the epic issue or issue the epic or issue is switched with. | +| `id` | [`EpicTreeSortingID!`](#epictreesortingid) | ID of the epic issue or epic that is being moved. | | `newParentId` | [`EpicID`](#epicid) | ID of the new parent epic. | -| `relativePosition` | [`MoveType`](#movetype) | The type of the switch, after or before allowed. | +| `relativePosition` | [`MoveType`](#movetype) | Type of switch. Valid values are `after` or `before`. | ### `EscalationRuleInput` @@ -17110,10 +17825,10 @@ Represents an escalation rule. | Name | Type | Description | | ---- | ---- | ----------- | -| `elapsedTimeSeconds` | [`Int!`](#int) | The time in seconds before the rule is activated. | -| `oncallScheduleIid` | [`ID`](#id) | The on-call schedule to notify. | -| `status` | [`EscalationRuleStatus!`](#escalationrulestatus) | The status required to prevent the rule from activating. | -| `username` | [`String`](#string) | The username of the user to notify. | +| `elapsedTimeSeconds` | [`Int!`](#int) | Time in seconds before the rule is activated. | +| `oncallScheduleIid` | [`ID`](#id) | On-call schedule to notify. | +| `status` | [`EscalationRuleStatus!`](#escalationrulestatus) | Status required to prevent the rule from activating. | +| `username` | [`String`](#string) | Username of the user to notify. | ### `JiraUsersMappingInputType` @@ -17148,7 +17863,8 @@ Represents an escalation rule. | `iterationWildcardId` | [`NegatedIterationWildcardId`](#negatediterationwildcardid) | Filter by iteration ID wildcard. | | `labelName` | [`[String]`](#string) | Filter by label name. | | `milestoneTitle` | [`String`](#string) | Filter by milestone title. | -| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| `milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter by milestone ID wildcard. | +| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | `releaseTag` | [`String`](#string) | Filter by release tag. | | `types` | [`[IssueType!]`](#issuetype) | Filter by the given issue types. | | `weight` | [`String`](#string) | Filter by weight. | @@ -17161,7 +17877,7 @@ Represents an escalation rule. | ---- | ---- | ----------- | | `authorUsername` | [`String`](#string) | Filter by author username. | | `labelName` | [`[String]`](#string) | Filter by label name. | -| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | ### `NegatedEpicFilterInput` @@ -17181,6 +17897,7 @@ Represents an escalation rule. | ---- | ---- | ----------- | | `assigneeId` | [`String`](#string) | ID of a user not assigned to the issues. | | `assigneeUsernames` | [`[String!]`](#string) | Usernames of users not assigned to the issue. | +| `authorUsername` | [`String`](#string) | Username of a user who didn't author the issue. | | `epicId` | [`String`](#string) | ID of an epic not associated with the issues. | | `iids` | [`[String!]`](#string) | List of IIDs of issues to exclude. For example, `[1, 2]`. | | `iterationId` | [`[ID!]`](#id) | List of iteration Global IDs not applied to the issue. | @@ -17188,6 +17905,7 @@ Represents an escalation rule. | `labelName` | [`[String!]`](#string) | Labels not applied to this issue. | | `milestoneTitle` | [`[String!]`](#string) | Milestone not applied to this issue. | | `milestoneWildcardId` | [`NegatedMilestoneWildcardId`](#negatedmilestonewildcardid) | Filter by negated milestone wildcard values. | +| `myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | `weight` | [`String`](#string) | Weight not applied to the issue. | ### `OncallRotationActivePeriodInputType` @@ -17198,8 +17916,8 @@ Active period time range for on-call rotation. | Name | Type | Description | | ---- | ---- | ----------- | -| `endTime` | [`String!`](#string) | The end of the rotation active period in 24 hour format, for example "18:30". | -| `startTime` | [`String!`](#string) | The start of the rotation active period in 24 hour format, for example "18:30". | +| `endTime` | [`String!`](#string) | End of the rotation active period in 24 hour format. For example, "18:30". | +| `startTime` | [`String!`](#string) | Start of the rotation active period in 24 hour format. For example, "18:30". | ### `OncallRotationDateInputType` @@ -17209,8 +17927,8 @@ Date input type for on-call rotation. | Name | Type | Description | | ---- | ---- | ----------- | -| `date` | [`String!`](#string) | The date component of the date in YYYY-MM-DD format. | -| `time` | [`String!`](#string) | The time component of the date in 24hr HH:MM format. | +| `date` | [`String!`](#string) | Date component of the date in YYYY-MM-DD format. | +| `time` | [`String!`](#string) | Time component of the date in 24hr HH:MM format. | ### `OncallRotationLengthInputType` @@ -17220,8 +17938,8 @@ The rotation length of the on-call rotation. | Name | Type | Description | | ---- | ---- | ----------- | -| `length` | [`Int!`](#int) | The rotation length of the on-call rotation. | -| `unit` | [`OncallRotationUnitEnum!`](#oncallrotationunitenum) | The unit of the rotation length of the on-call rotation. | +| `length` | [`Int!`](#int) | Rotation length of the on-call rotation. | +| `unit` | [`OncallRotationUnitEnum!`](#oncallrotationunitenum) | Unit of the rotation length of the on-call rotation. | ### `OncallUserInputType` @@ -17231,9 +17949,9 @@ The rotation user and color palette. | Name | Type | Description | | ---- | ---- | ----------- | -| `colorPalette` | [`DataVisualizationColorEnum`](#datavisualizationcolorenum) | A value of DataVisualizationColorEnum. The color from the palette to assign to the on-call user. | -| `colorWeight` | [`DataVisualizationWeightEnum`](#datavisualizationweightenum) | A value of DataVisualizationWeightEnum. The color weight to assign to for the on-call user. Note: To view on-call schedules in GitLab, do not provide a value below 500. A value between 500 and 950 ensures sufficient contrast. | -| `username` | [`String!`](#string) | The username of the user to participate in the on-call rotation, such as `user_one`. | +| `colorPalette` | [`DataVisualizationColorEnum`](#datavisualizationcolorenum) | Value of DataVisualizationColorEnum. The color from the palette to assign to the on-call user. | +| `colorWeight` | [`DataVisualizationWeightEnum`](#datavisualizationweightenum) | Color weight to assign to for the on-call user. To view on-call schedules in GitLab, do not provide a value below 500. A value between 500 and 950 ensures sufficient contrast. | +| `username` | [`String!`](#string) | Username of the user to participate in the on-call rotation. For example, `"user_one"`. | ### `ReleaseAssetLinkInput` @@ -17244,7 +17962,7 @@ Fields that are available when modifying a release asset link. | Name | Type | Description | | ---- | ---- | ----------- | | `directAssetPath` | [`String`](#string) | Relative path for a direct asset link. | -| `linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | The type of the asset link. | +| `linkType` | [`ReleaseAssetLinkType`](#releaseassetlinktype) | Type of the asset link. | | `name` | [`String!`](#string) | Name of the asset link. | | `url` | [`String!`](#string) | URL of the asset link. | @@ -17256,7 +17974,7 @@ Fields that are available when modifying release assets. | Name | Type | Description | | ---- | ---- | ----------- | -| `links` | [`[ReleaseAssetLinkInput!]`](#releaseassetlinkinput) | A list of asset links to associate to the release. | +| `links` | [`[ReleaseAssetLinkInput!]`](#releaseassetlinkinput) | List of asset links to associate to the release. | ### `SastCiConfigurationAnalyzersEntityInput` @@ -17315,8 +18033,8 @@ A time-frame defined as a closed inclusive range of two dates. | Name | Type | Description | | ---- | ---- | ----------- | -| `end` | [`Date!`](#date) | The end of the range. | -| `start` | [`Date!`](#date) | The start of the range. | +| `end` | [`Date!`](#date) | End of the range. | +| `start` | [`Date!`](#date) | Start of the range. | ### `UpdateDiffImagePositionInput` @@ -17328,3 +18046,14 @@ A time-frame defined as a closed inclusive range of two dates. | `width` | [`Int`](#int) | Total width of the image. | | `x` | [`Int`](#int) | X position of the note. | | `y` | [`Int`](#int) | Y position of the note. | + +### `VulnerabilityIdentifierInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| `externalId` | [`String`](#string) | External ID of the vulnerability identifier. | +| `externalType` | [`String`](#string) | External type of the vulnerability identifier. | +| `name` | [`String!`](#string) | Name of the vulnerability identifier. | +| `url` | [`String!`](#string) | URL of the vulnerability identifier. | diff --git a/doc/api/graphql/removed_items.md b/doc/api/graphql/removed_items.md index 1c425d5f1d5..0048148ab11 100644 --- a/doc/api/graphql/removed_items.md +++ b/doc/api/graphql/removed_items.md @@ -12,7 +12,7 @@ According to our [process for removing items](index.md#deprecation-and-removal-p ## GitLab 14.0 -Fields removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63293): +Fields [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63293) in GitLab 14.0: ### GraphQL Mutations @@ -38,7 +38,7 @@ Fields removed in [GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/merge_req ## GitLab 13.6 -Fields removed in [GitLab 13.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44866): +Fields [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44866) in GitLab 13.6: | Field name | GraphQL type | Deprecated in | Use instead | |----------------------|--------------------------|---------------|----------------------------| diff --git a/doc/api/graphql/users_example.md b/doc/api/graphql/users_example.md index 8fbfb67d166..0658a9402e7 100644 --- a/doc/api/graphql/users_example.md +++ b/doc/api/graphql/users_example.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Query users with GraphQL +# Query users with GraphQL **(FREE)** This page describes how you can use the GraphiQL explorer to query users. diff --git a/doc/api/group_activity_analytics.md b/doc/api/group_activity_analytics.md index 003c96b65fa..9206b0a1bd6 100644 --- a/doc/api/group_activity_analytics.md +++ b/doc/api/group_activity_analytics.md @@ -4,7 +4,7 @@ group: Optimize info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group Activity Analytics API +# Group Activity Analytics API **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26460) in GitLab 12.9. diff --git a/doc/api/group_badges.md b/doc/api/group_badges.md index 463507bf583..1e830237b50 100644 --- a/doc/api/group_badges.md +++ b/doc/api/group_badges.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group badges API +# Group badges API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17082) in GitLab 10.6. diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index eaa7b57e520..6178a3fdc04 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -76,7 +76,7 @@ Example response: ] ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) see different parameters, due to the ability to have multiple group boards. Example response: @@ -192,7 +192,7 @@ Example response: } ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) see different parameters, due to the ability to have multiple group issue boards. Example response: @@ -244,7 +244,7 @@ Example response: ## Create a group issue board **(PREMIUM)** -Creates a Group Issue Board. +Creates a group issue board. ```plaintext POST /groups/:id/boards @@ -283,7 +283,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5954) in GitLab 11.1. -Updates a Group Issue Board. +Updates a group issue board. ```plaintext PUT /groups/:id/boards/:board_id @@ -351,7 +351,7 @@ Example response: ## Delete a group issue board **(PREMIUM)** -Deletes a Group Issue Board. +Deletes a group issue board. ```plaintext DELETE /groups/:id/boards/:board_id @@ -452,7 +452,7 @@ Example response: ## New group issue board list -Creates a new Issue Board list. +Creates an issue board list. ```plaintext POST /groups/:id/boards/:board_id/lists @@ -493,7 +493,7 @@ Example response: ## Edit group issue board list -Updates an existing Issue Board list. This call is used to change list position. +Updates an existing issue board list. This call is used to change list position. ```plaintext PUT /groups/:id/boards/:board_id/lists/:list_id diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index d2bcac6332a..0a431cfdfbf 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -4,7 +4,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group Import/Export API +# Group Import/Export API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20353) in GitLab 12.8. diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index 25102e32360..04a619c8fa9 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -13,7 +13,7 @@ It allows users to list, create, update, and delete group labels. Furthermore, u unsubscribe from group labels. NOTE: -The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413). +The `description_html` - was [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) to response JSON in GitLab 12.7. ## List group labels @@ -26,7 +26,7 @@ GET /groups/:id/labels | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | -| `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543))_ | +| `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543) in GitLab 12.2)_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | | `only_group_labels` | boolean | no | Toggle to include only group labels or also project labels. Defaults to `true`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index f816f2dc173..7c51de47bc7 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -4,7 +4,7 @@ group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group-level Variables API +# Group-level Variables API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34519) in GitLab 9.5 diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index d7de3272005..8b9c09ef1a0 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -32,7 +32,7 @@ Parameters: | `state` | string | no | Return only `active` or `closed` milestones | | `title` | string | no | Return only the milestones having the given `title` | | `search` | string | no | Return only milestones with a title or description matching the provided string | -| `include_parent_milestones` | boolean | optional | Include milestones from parent group and its ancestors. Introduced in [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) | +| `include_parent_milestones` | boolean | optional | Include milestones from parent group and its ancestors. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) in GitLab 13.4 | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/5/milestones" diff --git a/doc/api/group_protected_environments.md b/doc/api/group_protected_environments.md index ddd9ca891d8..0e1cd149c51 100644 --- a/doc/api/group_protected_environments.md +++ b/doc/api/group_protected_environments.md @@ -7,17 +7,11 @@ type: concepts, howto # Group-level protected environments API **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in [GitLab Premium](https://about.gitlab.com/pricing/) 14.0. -> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](../ci/environments/protected_environments.md#enable-or-disable-group-level-protected-environments). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215888) in GitLab 14.0. [Deployed behind the `group_level_protected_environments` flag](../administration/feature_flags.md), disabled by default. +> - [Feature flag `group_level_protected_environments`](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) removed in GitLab 14.3. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/331085) in GitLab 14.3. -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. - -Read more about [group-level protected environments](../ci/environments/protected_environments.md#group-level-protected-environments), +Read more about [group-level protected environments](../ci/environments/protected_environments.md#group-level-protected-environments). ## Valid access levels diff --git a/doc/api/group_relations_export.md b/doc/api/group_relations_export.md index 2f9c1e381df..4dbf0f6d54c 100644 --- a/doc/api/group_relations_export.md +++ b/doc/api/group_relations_export.md @@ -4,7 +4,7 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group Relations Export API +# Group Relations Export API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59978) in GitLab 13.12. diff --git a/doc/api/group_wikis.md b/doc/api/group_wikis.md index e1470a2cdd7..17337934a92 100644 --- a/doc/api/group_wikis.md +++ b/doc/api/group_wikis.md @@ -7,7 +7,7 @@ type: reference, api # Group wikis API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212199) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212199) in GitLab 13.5. The [group wikis](../user/project/wiki/index.md#group-wikis) API is available only in APIv4. An API for [project wikis](wikis.md) is also available. diff --git a/doc/api/groups.md b/doc/api/groups.md index 3831aef10c9..bd4c7de567c 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Groups API +# Groups API **(FREE)** ## List groups @@ -13,6 +13,11 @@ authentication, only public groups are returned. By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). +When accessed without authentication, this endpoint also supports [keyset pagination](index.md#keyset-based-pagination): + +- When requesting consecutive pages of results, we recommend you use keyset pagination. +- Beyond a specific offset limit (specified by [max offset allowed by the REST API for offset-based pagination](../administration/instance_limits.md#max-offset-allowed-by-the-rest-api-for-offset-based-pagination)), offset pagination is unavailable. + Parameters: | Attribute | Type | Required | Description | @@ -764,6 +769,10 @@ For GitLab 14.0 and later, the [limit cannot be disabled](https://gitlab.com/git ## New group +NOTE: +On GitLab SaaS, you must use the GitLab UI to create groups without a parent group. You cannot +use the API to do this. + Creates a new project group. Available only for users who can create groups. ```plaintext @@ -795,10 +804,6 @@ Parameters: | `shared_runners_minutes_limit` | integer | no | **(PREMIUM SELF)** 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 | **(PREMIUM SELF)** Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | -NOTE: -On GitLab SaaS, you must use the GitLab UI to create groups without a parent group. You cannot -use the API to do this. - ### Options for `default_branch_protection` The `default_branch_protection` attribute determines whether developers and maintainers can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table: @@ -1338,7 +1343,7 @@ DELETE /groups/:id/share/:group_id ## Push Rules **(PREMIUM)** -> Introduced in [GitLab](https://about.gitlab.com/pricing/) 13.4. +> Introduced in GitLab 13.4. ### Get group push rules **(PREMIUM)** @@ -1370,7 +1375,7 @@ GET /groups/:id/push_rule } ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `commit_committer_check` and `reject_unsigned_commits` parameters: ```json diff --git a/doc/api/index.md b/doc/api/index.md index 12d01828803..7b599b6ae0a 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -125,7 +125,7 @@ There are several ways you can authenticate with the GitLab API: - [Personal access tokens](../user/profile/personal_access_tokens.md) - [Project access tokens](../user/project/settings/project_access_tokens.md) - [Session cookie](#session-cookie) -- [GitLab CI/CD job token](#gitlab-cicd-job-token) **(Specific endpoints only)** +- [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) **(Specific endpoints only)** Project access tokens are supported by: @@ -208,118 +208,6 @@ The primary user of this authentication method is the web frontend of GitLab itself. The web frontend can use the API as the authenticated user to get a list of projects without explicitly passing an access token. -### GitLab CI/CD job token - -When a pipeline job is about to run, GitLab generates a unique token and injects it as the -[`CI_JOB_TOKEN` predefined variable](../ci/variables/predefined_variables.md). - -You can use a GitLab CI/CD job token to authenticate with specific API endpoints: - -- Packages: - - [Package Registry](../user/packages/package_registry/index.md). To push to the - Package Registry, you can use [deploy tokens](../user/project/deploy_tokens/index.md). - - [Container Registry](../user/packages/container_registry/index.md) - (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). - - [Container Registry API](container_registry.md) (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled) -- [Get job artifacts](job_artifacts.md#get-job-artifacts). -- [Get job token's job](jobs.md#get-job-tokens-job). -- [Pipeline triggers](pipeline_triggers.md), using the `token=` parameter. -- [Release creation](releases/index.md#create-a-release). -- [Terraform plan](../user/infrastructure/index.md). - -The token has the same permissions to access the API as the user that triggers the -pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../user/permissions.md). - -The token is valid only while the pipeline job runs. After the job finishes, you can't -use the token anymore. - -A job token can access a project's resources without any configuration, but it might -give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) -to redesign the feature for more strategic control of the access permissions. - -#### GitLab CI/CD job token security - -To make sure that this token doesn't leak, GitLab: - -- Masks the job token in job logs. -- Grants permissions to the job token only when the job is running. - -To make sure that this token doesn't leak, you should also configure -your [runners](../ci/runners/README.md) to be secure. Avoid: - -- Using Docker's `privileged` mode if the machines are re-used. -- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs - run on the same machine. - -If you have an insecure GitLab Runner configuration, you increase the risk that someone -tries to steal tokens from other jobs. - -#### Limit GitLab CI/CD job token access - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. -> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default. -> - Disabled on GitLab.com. -> - Not recommended for production use. -> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ci-job-token-scope-limit). **(FREE SELF)** - -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. - -You can limit the access scope of a project's CI/CD job token to increase the -job token's security. A job token might give extra permissions that aren't necessary -to access specific private resources. Limiting the job token access scope reduces the risk of a leaked -token being used to access private data that the user associated to the job can access. - -Control the job token access scope with an allowlist of other projects authorized -to be accessed by authenticating with the current project's job token. By default -the token scope only allows access to the same project where the token comes from. -Other projects can be added and removed by maintainers with access to both projects. - -This setting is enabled by default for all new projects, and disabled by default in projects -created before GitLab 14.1. It is strongly recommended that project maintainers enable this -setting at all times, and configure the allowlist for cross-project access if needed. - -For example, when the setting is enabled, jobs in a pipeline in project `A` have -a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token -to make an API request to a private project `B`, then `B` must be added to the allowlist for `A`. -If project `B` is public or internal, it doesn't need to be added to the allowlist. -The job token scope is only for controlling access to private projects. - -To enable and configure the job token scope limit: - -1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **Token Access**. -1. Toggle **Limit CI_JOB_TOKEN access** to enabled. -1. (Optional) Add existing projects to the token's access scope. The user adding a - project must have the [maintainer role](../user/permissions.md) in both projects. - -If the job token scope limit is disabled, the token can potentially be used to authenticate -API requests to all projects accessible to the user that triggered the job. - -There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve -the feature with more strategic control of the access permissions. - -##### Enable or disable CI job token scope limit **(FREE SELF)** - -The GitLab CI/CD job token access scope limit is under development and not ready for production -use. It is deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:ci_scoped_job_token) -``` - -To disable it: - -```ruby -Feature.disable(:ci_scoped_job_token) -``` - ### Impersonation tokens Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md). @@ -574,22 +462,43 @@ The response header includes a link to the next page. For example: ```http HTTP/1.1 200 OK ... -Links: ; rel="next" Link: ; rel="next" Status: 200 OK ... ``` +The link to the next page contains an additional filter `id_after=42` that +excludes already-retrieved records. + +As another example, the following request lists 50 [groups](groups.md) per page ordered +by `name` ascending using keyset pagination: + +```shell +curl --request GET --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups?pagination=keyset&per_page=50&order_by=name&sort=asc" +``` + +The response header includes a link to the next page: + +```http +HTTP/1.1 200 OK +... +Link: ; rel="next" +Status: 200 OK +... +``` + +The link to the next page contains an additional filter `cursor=eyJuYW1lIjoiRmxpZ2h0anMiLCJpZCI6IjI2IiwiX2tkIjoibiJ9` that +excludes already-retrieved records. + +The type of filter depends on the +`order_by` option used, and we can have more than one additional filter. + WARNING: -The `Links` header is scheduled to be removed in GitLab 14.0 to be aligned with the +The `Links` header was removed in GitLab 14.0 to be aligned with the [W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) and should be used instead. -The link to the next page contains an additional filter `id_after=42` that -excludes already-retrieved records. The type of filter depends on the -`order_by` option used, and we may have more than one additional filter. - When the end of the collection is reached and there are no additional records to retrieve, the `Link` header is absent and the resulting array is empty. @@ -601,9 +510,10 @@ pagination headers. Keyset-based pagination is supported only for selected resources and ordering options: -| Resource | Order | -|-------------------------|-------| -| [Projects](projects.md) | `order_by=id` only. | +| Resource | Options | Availability | +|:-------------------------|:---------------------------------|:----------------------------------------| +| [Projects](projects.md) | `order_by=id` only | Authenticated and unauthenticated users | +| [Groups](groups.md) | `order_by=name`, `sort=asc` only | Unauthenticated users only | ## Path parameters @@ -675,7 +585,7 @@ send the payload body: ```shell curl --request POST --header "Content-Type: application/json" \ - --data '{"name":"", "description":"", "description":""}' "https://gitlab/api/v4/projects" ``` URL encoded query strings have a length limitation. Requests that are too large @@ -705,7 +615,7 @@ curl --request POST --header "PRIVATE-TOKEN: " \ curl --request POST --header "PRIVATE-TOKEN: " \ --form "namespace=email" \ --form "path=impapi" \ ---form "file=@/path/to/somefile.txt" +--form "file=@/path/to/somefile.txt" \ --form "override_params[visibility]=private" \ --form "override_params[some_other_param]=some_value" \ "https://gitlab.example.com/api/v4/projects/import" @@ -718,7 +628,7 @@ curl --request POST --header "PRIVATE-TOKEN: " \ ```shell curl --globoff --request POST --header "PRIVATE-TOKEN: " \ -"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[][key]=VAR1&variables[][value]=hello&variables[][key]=VAR2&variables[][value]=world" +"https://gitlab.example.com/api/v4/projects/169/pipeline?ref=master&variables[0][key]=VAR1&variables[0][value]=hello&variables[1][key]=VAR2&variables[1][value]=world" curl --request POST --header "PRIVATE-TOKEN: " \ --header "Content-Type: application/json" \ diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index ae94fdb137c..4e0ec3bd433 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -4,7 +4,7 @@ group: Configure info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Instance clusters API **(FREE)** +# Instance clusters API **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36001) in GitLab 13.2. diff --git a/doc/api/instance_level_ci_variables.md b/doc/api/instance_level_ci_variables.md index de6fd958aa6..2b2579425b5 100644 --- a/doc/api/instance_level_ci_variables.md +++ b/doc/api/instance_level_ci_variables.md @@ -4,7 +4,7 @@ group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Instance-level CI/CD variables API +# Instance-level CI/CD variables API **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14108) in GitLab 13.0 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/218249) in GitLab 13.2. diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index d4f59d10316..ac26d2a3d17 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Issue links API **(FREE)** -> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.4. +> The simple "relates to" relationship [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212329) to GitLab Free in 13.4. ## List issue relations diff --git a/doc/api/issues.md b/doc/api/issues.md index feec9b31747..97d0fd3ce8f 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -20,7 +20,7 @@ Read more on [pagination](index.md#pagination). WARNING: The `reference` attribute in responses is deprecated in favor of `references`. -Introduced in [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354). +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.6. NOTE: The `references.relative` attribute is relative to the group or project of the issue being requested. @@ -61,18 +61,19 @@ GET /issues?state=opened | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | +| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | | `iids[]` | integer array | no | Return only the issues having the given `iid` | | `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | +| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. Using `None` or `Any` will be [deprecated in the future](https://gitlab.com/gitlab-org/gitlab/-/issues/336044). Please use `milestone_id` attribute instead. `milestone` and `milestone_id` are mutually exclusive. | +| `milestone_id` | string | no | Returns issues assigned to milestones with a given timebox value (`None`, `Any`, `Upcoming`, and `Started`). `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. `Upcoming` lists all issues assigned to milestones due in the future. `Started` lists all issues assigned to open, started milestones. `milestone` and `milestone_id` are mutually exclusive. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335939) in GitLab 14.3)_ | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | -| `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. _(Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/197170))_ | -| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, and `weight`. | -| `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | +| `non_archived` | boolean | no | Return issues only from non-archived projects. If `false`, the response returns issues from both archived and non-archived projects. Default is `true`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197170) in GitLab 13.0)_ | +| `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `assignee_id`, `assignee_username`, `author_id`, `author_username`, `iids`, `iteration_id`, `iteration_title`, `labels`, `milestone`, `milestone_id` and `weight`. | +| `order_by` | string | no | Return issues ordered by `created_at`, `due_date`, `label_priority`, `milestone_due`, `popularity`, `priority`, `relative_position`, `title`, `updated_at`, or `weight` fields. Default is `created_at`. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`
For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.
_([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | | `search` | string | no | Search issues against their `title` and `description` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | @@ -80,7 +81,7 @@ GET /issues?state=opened | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413)| +| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7| ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/issues" @@ -224,11 +225,11 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -267,16 +268,16 @@ GET /groups/:id/issues?state=opened | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | +| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | +| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_ | -| `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _(Introduced in [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785))_ | +| `non_archived` | boolean | no | Return issues from non archived projects. Default is true. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23785) in GitLab 12.8)_ | | `not` | Hash | no | Return issues that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `my_reaction_emoji`, `search`, `in` | | `order_by` | string | no | Return issues ordered by `created_at`, `updated_at`, `priority`, `due_date`, `relative_position`, `label_priority`, `milestone_due`, `popularity`, `weight` fields. Default is `created_at` | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.
For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.
_([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13004) in GitLab 9.5. [Changed to snake_case](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in GitLab 11.0)_ | @@ -286,7 +287,7 @@ GET /groups/:id/issues?state=opened | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | +| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/groups/4/issues" @@ -428,11 +429,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -471,10 +472,10 @@ GET /projects/:id/issues?state=opened | `confidential` | boolean | no | Filter confidential or public issues. | | `created_after` | datetime | no | Return issues created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `created_before` | datetime | no | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | -| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _(Introduced in [GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/233420))_ | +| `due_date` | string | no | Return issues that have no due date, are overdue, or whose due date is this week, this month, or between two weeks ago and next month. Accepts: `0` (no due date), `overdue`, `week`, `month`, `next_month_and_previous_two_weeks`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233420) in GitLab 13.3)_ | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `iids[]` | integer array | no | Return only the issues having the given `iid` | -| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _(Introduced in [GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/260375))_ | +| `issue_type` | string | no | Filter to a given type of issue. One of `issue`, `incident`, or `test_case`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260375) in GitLab 13.12)_ | | `iteration_id` **(PREMIUM)** | integer | no | Return issues assigned to the given iteration ID. `None` returns issues that do not belong to an iteration. `Any` returns issues that belong to an iteration. Mutually exclusive with `iteration_title`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `iteration_title` **(PREMIUM)** | string | no | Return issues assigned to the iteration with the given title. Similar to `iteration_id` and mutually exclusive with `iteration_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in GitLab 13.6)_ | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | @@ -489,7 +490,7 @@ GET /projects/:id/issues?state=opened | `updated_after` | datetime | no | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `updated_before` | datetime | no | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) | | `weight` **(PREMIUM)** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | -| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) | +| `with_labels_details` | boolean | no | If `true`, the response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. `description_html` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7 | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/4/issues" @@ -638,11 +639,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced 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 `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Single issue @@ -803,11 +804,11 @@ The `assignee` column is deprecated. We now show it as a single-sized array `ass to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated, and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated, and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced in GitLab 10.6](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042). +The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. @@ -964,11 +965,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced 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 `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## New issue @@ -991,7 +992,7 @@ POST /projects/:id/issues | `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 `YYYY-MM-DD`, 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, [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | +| `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.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) | | `issue_type` | string | no | The type of issue. One of `issue`, `incident`, or `test_case`. Default is `issue`. | @@ -1114,11 +1115,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced 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 `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Rate limits @@ -1161,7 +1162,7 @@ PUT /projects/:id/issues/:issue_iid | `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 `YYYY-MM-DD`, 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, [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157)) | +| `epic_iid` **(PREMIUM)** | integer | no | IID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5) | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `issue_type` | string | no | Updates the type of issue. One of `issue`, `incident`, or `test_case`. | @@ -1289,11 +1290,11 @@ Issues created by users on GitLab Ultimate include the `health_status` property: ``` 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 `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. WARNING: @@ -1479,11 +1480,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced 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 `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Subscribe to an issue @@ -1624,11 +1625,11 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. WARNING: -The `epic_iid` attribute is deprecated and [scheduled for removal in API version 5](https://gitlab.com/gitlab-org/gitlab/-/issues/35157). +The `epic_iid` attribute is deprecated and [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/35157) in API version 5. Please use `iid` of the `epic` attribute instead. NOTE: -The `closed_by` attribute was [introduced 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 `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Unsubscribe from an issue @@ -1822,7 +1823,7 @@ WARNING: The `assignee` column is deprecated. We now show it as a single-sized array `assignees` to conform to the GitLab EE API. NOTE: -The `closed_by` attribute was [introduced 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 `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. ## Promote an issue to an epic **(PREMIUM)** diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md index 0a39400dfd4..6d8c256d5aa 100644 --- a/doc/api/job_artifacts.md +++ b/doc/api/job_artifacts.md @@ -4,7 +4,7 @@ group: Testing info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Job Artifacts API +# Job Artifacts API **(FREE)** ## Get job artifacts @@ -20,7 +20,7 @@ GET /projects/:id/jobs/:job_id/artifacts |-------------|----------------|----------|--------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | ID of a job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -85,7 +85,7 @@ Parameters | `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | | `job` | string | yes | The name of the job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request using the `PRIVATE-TOKEN` header: @@ -146,7 +146,7 @@ Parameters | `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `job_id` | integer | yes | The unique job identifier. | | `artifact_path` | string | yes | Path to a file inside the artifacts archive. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request: @@ -188,7 +188,7 @@ Parameters: | `ref_name` | string | yes | Branch or tag name in repository. `HEAD` or `SHA` references are not supported. | | `artifact_path` | string | yes | Path to a file inside the artifacts archive. | | `job` | string | yes | The name of the job. | -| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | +| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | Example request: diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 42774b80b27..ac8b756beac 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -466,7 +466,7 @@ Example of response ## Get Kubernetes Agents by `CI_JOB_TOKEN` **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324269) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324269) in GitLab 13.11. Retrieve the job that generated the `CI_JOB_TOKEN`, along with a list of allowed GitLab Kubernetes Agents. diff --git a/doc/api/labels.md b/doc/api/labels.md index 1606df03afb..a8cb56f1573 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Interact with [labels](../user/project/labels.md) using the REST API. NOTE: -The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413). +The `description_html` - was [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) to response JSON in GitLab 12.7. ## List labels @@ -24,7 +24,7 @@ GET /projects/:id/labels | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced in GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543))_ | +| `with_counts` | boolean | no | Whether or not to include issue and merge request counts. Defaults to `false`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31543) in GitLab 12.2)_ | | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. | | `search` | string | no | Keyword to filter labels by. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 | diff --git a/doc/api/lint.md b/doc/api/lint.md index a47bb028248..9f95b9a94ae 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Validate the CI YAML configuration Checks if CI/CD YAML configuration is valid. This endpoint validates basic CI/CD -configuration syntax. It doesn't have any namespace specific context. +configuration syntax. It doesn't have any namespace-specific context. Access to this endpoint does not require authentication when the instance [allows new sign ups](../user/admin_area/settings/sign_up_restrictions.md#disable-new-sign-ups) diff --git a/doc/api/members.md b/doc/api/members.md index 4b383efd792..0b8cf686b8c 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Group and project members API +# Group and project members API **(FREE)** ## Valid access levels @@ -92,7 +92,7 @@ Gets a list of group or project members viewable by the authenticated user, incl If a user is a member of this group or project and also of one or more ancestor groups, only its membership with the highest `access_level` is returned. -([Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56677)] in GitLab 13.11.) +([Improved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56677) in GitLab 13.11.) This represents the effective permission of the user. This function takes pagination parameters `page` and `per_page` to restrict the list of users. @@ -552,7 +552,7 @@ Example response: "state": "active", "avatar_url": "https://www.gravatar.com/avatar/c2525a7f58ae3776070e44c106c48e15?s=80&d=identicon", "web_url": "http://192.168.1.8:3000/root", - "expires_at": "2012-10-22T14:13:35Z", + "expires_at": "2012-10-22", "access_level": 40, "email": "john@example.com", "override": false diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index ef8af608466..b4403e1d9b9 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -81,7 +81,7 @@ POST /projects/:id/approvals > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. > - Moved to GitLab Premium in 13.9. -> - `protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. +> - `protected_branches` property was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/460) in GitLab 12.7. You can request information about a project's approval rules using the following endpoint: @@ -954,7 +954,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approve | `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `merge_request_iid` | integer | yes | The IID of the merge request | | `sha` | string | no | The `HEAD` of the merge request | -| `approval_password` **(PREMIUM)** | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. | +| `approval_password` | string | no | Current user's password. Required if [**Require user password to approve**](../user/project/merge_requests/approvals/settings.md#require-user-password-to-approve) is enabled in the project settings. | The `sha` parameter works in the same way as when [accepting a merge request](merge_requests.md#accept-mr): if it is passed, then it must diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index b90f0e70a02..98af228a064 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -222,7 +222,7 @@ Parameters: ] ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -418,7 +418,7 @@ The `merge_status` field may hold one of the following values: | `cannot_be_merged` | There are merge conflicts between the source and target branches | | `cannot_be_merged_recheck` | Currently unchecked. Before the current changes, there were conflicts | -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -460,8 +460,8 @@ Parameters: | `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. | | `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | -| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413).| -| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890). | +| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7.| +| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. | | `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -478,7 +478,7 @@ Parameters: | `source_branch` | string | no | Return merge requests with the given source branch. | | `target_branch` | string | no | Return merge requests with the given target branch. | | `search` | string | no | Search merge requests against their `title` and `description`. | -| `non_archived` | boolean | no | Return merge requests from non archived projects only. Default is true. _(Introduced in [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23809))_. | +| `non_archived` | boolean | no | Return merge requests from non archived projects only. Default is true. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23809) in GitLab 12.8)_. | | `not` | Hash | no | Return merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. | ```json @@ -592,7 +592,7 @@ Parameters: ] ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -625,7 +625,7 @@ Parameters: |----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `merge_request_iid` | integer | yes | The internal ID of the merge request. | -| `render_html` | integer | no | If `true` response includes rendered HTML for title and description. | +| `render_html` | boolean | no | If `true` response includes rendered HTML for title and description. | | `include_diverged_commits_count` | boolean | no | If `true` response includes the commits behind the target branch. | | `include_rebase_in_progress` | boolean | no | If `true` response includes whether a rebase operation is in progress. | @@ -764,7 +764,7 @@ Parameters: } ``` -Users on GitLab Premium also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -1014,7 +1014,7 @@ The new pipeline can be: - A detached merge request pipeline. - A [pipeline for merged results](../ci/pipelines/pipelines_for_merged_results.md) - if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results). + if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results). **(PREMIUM)** ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/pipelines @@ -1375,7 +1375,7 @@ Must include at least one non-required attribute from above. } ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -1561,7 +1561,7 @@ Parameters: } ``` -Users on GitLab Premium also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -1750,7 +1750,7 @@ Parameters: } ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -2051,7 +2051,7 @@ Example response: } ``` -Users on GitLab Premium also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json @@ -2211,7 +2211,7 @@ Example response: } ``` -Users on GitLab Premium or higher also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `approvals_before_merge` parameter: ```json diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index b2f1e52f194..feba57a7ced 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -7,7 +7,7 @@ type: concepts, howto # Dashboard annotations API **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29089) in GitLab 12.10 behind a disabled feature flag. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29089) in GitLab 12.10 behind a disabled feature flag. Metrics dashboard annotations allow you to indicate events on your graphs at a single point in time or over a time span. diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 603d307f4b7..f615ddaaa71 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -43,7 +43,7 @@ Example Response: ## Remove a star from a dashboard -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31892) in GitLab 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31892) in GitLab 13.0. ```plaintext DELETE /projects/:id/metrics/user_starred_dashboards diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 183d8b4799b..84b4e2fe39d 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -32,7 +32,7 @@ Parameters: | `state` | string | optional | Return only `active` or `closed` milestones | | `title` | string | optional | Return only the milestones having the given `title` | | `search` | string | optional | Return only milestones with a title or description matching the provided string | -| `include_parent_milestones` | boolean | optional | Include group milestones from parent group and its ancestors. Introduced in [GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) | +| `include_parent_milestones` | boolean | optional | Include group milestones from parent group and its ancestors. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/196066) in GitLab 13.4 | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/milestones" diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 390ba7dbd79..4b70a643263 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -199,7 +199,7 @@ Example responses: } ``` -Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) also see the `new_epic` +Users on [GitLab Ultimate](https://about.gitlab.com/pricing/) also see the `new_epic` parameter: ```json diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index ce455c89d1a..abf9d7af229 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -5,7 +5,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab as an OAuth2 provider +# GitLab as an OAuth 2.0 provider **(FREE)** This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow other services to access GitLab resources on user's behalf. @@ -15,9 +15,9 @@ other services, see the [OAuth2 authentication service provider](../integration/ documentation. This functionality is based on the [doorkeeper Ruby gem](https://github.com/doorkeeper-gem/doorkeeper). -## Supported OAuth2 flows +## Supported OAuth 2.0 flows -GitLab currently supports the following authorization flows: +GitLab supports the following authorization flows: - **Authorization code with [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636):** Most secure. Without PKCE, you'd have to include client secrets on mobile clients, @@ -26,14 +26,13 @@ GitLab currently supports the following authorization flows: server-side apps. - **Implicit grant:** Originally designed for user-agent only apps, such as single page web apps running on GitLab Pages). - The [IETF](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-09#section-2.1.2) + The [Internet Engineering Task Force (IETF)](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-09#section-2.1.2) recommends against Implicit grant flow. - **Resource owner password credentials:** To be used **only** for securely hosted, first-party services. GitLab recommends against use of this flow. The draft specification for [OAuth 2.1](https://oauth.net/2.1/) specifically omits both the -Implicit grant and Resource Owner Password Credentials flows. - it will be deprecated in the next OAuth specification version. +Implicit grant and Resource Owner Password Credentials flows. It will be deprecated in the next OAuth specification version. Refer to the [OAuth RFC](https://tools.ietf.org/html/rfc6749) to find out how all those flows work and pick the right one for your use case. @@ -57,7 +56,7 @@ parameter, which are securely bound to the user agent", with each request to the For production, please use HTTPS for your `redirect_uri`. For development, GitLab allows insecure HTTP redirect URIs. -As OAuth2 bases its security entirely on the transport layer, you should not use unprotected +As OAuth 2.0 bases its security entirely on the transport layer, you should not use unprotected URIs. For more information, see the [OAuth 2.0 RFC](https://tools.ietf.org/html/rfc6749#section-3.1.2.1) and the [OAuth 2.0 Threat Model RFC](https://tools.ietf.org/html/rfc6819#section-4.4.2.1). These factors are particularly important when using the @@ -83,7 +82,11 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD which use the characters `A-Z`, `a-z`, `0-9`, `-`, `.`, `_`, and `~`. - The `CODE_CHALLENGE` is an URL-safe base64-encoded string of the SHA256 hash of the `CODE_VERIFIER` + - The SHA256 hash must be in binary format before encoding. - In Ruby, you can set that up with `Base64.urlsafe_encode64(Digest::SHA256.digest(CODE_VERIFIER), padding: false)`. + - For reference, a `CODE_VERIFIER` string of `ks02i3jdikdo2k0dkfodf3m39rjfjsdk0wk349rj3jrhf` when hashed + and encoded using the Ruby snippet above produces a `CODE_CHALLENGE` string + of `2i0WFA-0AerkjQm4X4oDEhqA17QIAKNjXpagHBXmO_U`. 1. Request authorization code. To do that, you should redirect the user to the `/oauth/authorize` page with the following query parameters: @@ -123,7 +126,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD "created_at": 1607635748 } ``` - + 1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may be used even after the `access_token` itself expires. This request: - Invalidates the existing `access_token` and `refresh_token`. @@ -135,7 +138,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD ``` Example response: - + ```json { "access_token": "c97d1fe52119f38c7f67f0a14db68d60caa35ddc86fd12401718b649dcfa9c68", @@ -203,7 +206,7 @@ be used as a CSRF token. "created_at": 1607635748 } ``` - + 1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may be used even after the `access_token` itself expires. This request: - Invalidates the existing `access_token` and `refresh_token`. @@ -245,12 +248,13 @@ scheduled to be removed for existing applications. We recommend that you use [Authorization code with PKCE](#authorization-code-with-proof-key-for-code-exchange-pkce) instead. If you choose to use Implicit flow, be sure to verify the `application id` (or `client_id`) associated with the access token before granting -access to the data, as described in [Retrieving the token information](#retrieving-the-token-information)). +access to the data. To learn more, read +[Retrieving the token information](#retrieve-the-token-information)). Unlike the authorization code flow, the client receives an `access token` -immediately as a result of the authorization request. The flow does not use -the client secret or the authorization code because all of the application code -and storage is easily accessible on client browsers and mobile devices. +immediately as a result of the authorization request. The flow does not use the +client secret or the authorization code, as the application +code and storage is accessible on client browsers and mobile devices. To request the access token, you should redirect the user to the `/oauth/authorize` endpoint using `token` response type: @@ -367,10 +371,11 @@ or you can put the token to the Authorization header: curl --header "Authorization: Bearer OAUTH-TOKEN" "https://gitlab.example.com/api/v4/user" ``` -## Retrieving the token information +## Retrieve the token information -To verify the details of a token, use the `token/info` endpoint provided by the Doorkeeper gem. -For more information, see [`/oauth/token/info`](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo). +To verify the details of a token, use the `token/info` endpoint provided by the +Doorkeeper gem. For more information, see +[`/oauth/token/info`](https://github.com/doorkeeper-gem/doorkeeper/wiki/API-endpoint-descriptions-and-examples#get----oauthtokeninfo). You must supply the access token, either: @@ -407,9 +412,10 @@ prevent breaking changes introduced in [doorkeeper 5.0.2](https://github.com/doo Don't rely on these fields as they are slated for removal in a later release. -## OAuth2 tokens and GitLab registries +## OAuth 2.0 tokens and GitLab registries -Standard OAuth2 tokens support different degrees of access to GitLab registries, as they: +Standard OAuth 2.0 tokens support different degrees of access to GitLab +registries, as they: - Do not allow users to authenticate to: - The GitLab [Container registry](../user/packages/container_registry/index.md#authenticate-with-the-container-registry). diff --git a/doc/api/packages.md b/doc/api/packages.md index 73092e68c82..a75b2e376fa 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Packages API +# Packages API **(FREE)** This is the API documentation of [GitLab Packages](../administration/packages/index.md). diff --git a/doc/api/packages/composer.md b/doc/api/packages/composer.md index 4f8e0a23c9c..b3a27519729 100644 --- a/doc/api/packages/composer.md +++ b/doc/api/packages/composer.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Composer API +# Composer API **(FREE)** This is the API documentation for [Composer Packages](../../user/packages/composer_repository/index.md). @@ -108,13 +108,14 @@ V1. GET group/:id/-/packages/composer/:package_name$:sha ``` -Note the `$` symbol in the URL. When making requests, you may need to use the URL-encoded version of -the symbol `%24` (see example below). +Note the `$` symbol in the URL. When making requests, you may need the +URL-encoded version of the symbol `%24`. Refer to the example after +the table: -| Attribute | Type | Required | Description | -| -------------- | ------ | -------- | ----------- | -| `id` | string | yes | The ID or full path of the group. | -| `package_name` | string | yes | The name of the package. | +| Attribute | Type | Required | Description | +|----------------|--------|----------|---------------------------------------------------------------------------------------| +| `id` | string | yes | The ID or full path of the group. | +| `package_name` | string | yes | The name of the package. | | `sha` | string | yes | The SHA digest of the package, provided by the [V1 packages list](#v1-packages-list). | ```shell diff --git a/doc/api/packages/conan.md b/doc/api/packages/conan.md index 88ed2524173..f5d08ed7ef8 100644 --- a/doc/api/packages/conan.md +++ b/doc/api/packages/conan.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Conan API +# Conan API **(FREE)** This is the API documentation for [Conan Packages](../../user/packages/conan_repository/index.md). diff --git a/doc/api/packages/go_proxy.md b/doc/api/packages/go_proxy.md index 2f81435db42..ffafc387951 100644 --- a/doc/api/packages/go_proxy.md +++ b/doc/api/packages/go_proxy.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Go Proxy API +# Go Proxy API **(FREE SELF)** This is the API documentation for [Go Packages](../../user/packages/go_proxy/index.md). This API is behind a feature flag that is disabled by default. GitLab administrators with access to diff --git a/doc/api/packages/helm.md b/doc/api/packages/helm.md index f1d5f24cd99..8c3b9869368 100644 --- a/doc/api/packages/helm.md +++ b/doc/api/packages/helm.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Helm API +# Helm API **(FREE)** This is the API documentation for [Helm](../../user/packages/helm_repository/index.md). @@ -38,14 +38,14 @@ GET projects/:id/packages/helm/:channel/index.yaml ```shell curl --user : \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml + "https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml" ``` Write the output to a file: ```shell curl --user : \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml \ + "https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/index.yaml" \ --remote-name ``` @@ -67,7 +67,7 @@ GET projects/:id/packages/helm/:channel/charts/:file_name.tgz ```shell curl --user : \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/charts/mychart.tgz \ + "https://gitlab.example.com/api/v4/projects/1/packages/helm/stable/charts/mychart.tgz" \ --remote-name ``` @@ -91,5 +91,5 @@ POST projects/:id/packages/helm/api/:channel/charts curl --request POST \ --form 'chart=@mychart.tgz' \ --user : \ - https://gitlab.example.com/api/v4/projects/1/packages/helm/api/stable/charts + "https://gitlab.example.com/api/v4/projects/1/packages/helm/api/stable/charts" ``` diff --git a/doc/api/packages/maven.md b/doc/api/packages/maven.md index d03c9be3060..b4b3d579ffb 100644 --- a/doc/api/packages/maven.md +++ b/doc/api/packages/maven.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Maven API +# Maven API **(FREE)** This is the API documentation for [Maven Packages](../../user/packages/maven_repository/index.md). diff --git a/doc/api/packages/npm.md b/doc/api/packages/npm.md index 3992a042915..24ac1a640c9 100644 --- a/doc/api/packages/npm.md +++ b/doc/api/packages/npm.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.example/handbook/engineering/ux/technical-writing/#assignments --- -# npm API +# npm API **(FREE)** This is the API documentation for [npm Packages](../../user/packages/npm_registry/index.md). @@ -58,11 +58,11 @@ Upload a package. PUT projects/:id/packages/npm/:package_name ``` -| Attribute | Type | Required | Description | -| ----------------- | ------ | -------- | ----------- | -| `id` | string | yes | The ID or full path of the project. | -| `package_name` | string | yes | The name of the package. | -| `versions` | string | yes | Package version info. | +| Attribute | Type | Required | Description | +|----------------|--------|----------|-------------------------------------| +| `id` | string | yes | The ID or full path of the project. | +| `package_name` | string | yes | The name of the package. | +| `versions` | string | yes | Package version information. | ```shell curl --request PUT diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md index d19e2dfa65b..aee3a4fe542 100644 --- a/doc/api/packages/nuget.md +++ b/doc/api/packages/nuget.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about..example/handbook/engineering/ux/technical-writing/#assignments --- -# NuGet API +# NuGet API **(FREE)** This is the API documentation for [NuGet Packages](../../user/packages/nuget_repository/index.md). @@ -73,7 +73,7 @@ curl --user : "https://gitlab.example.com/api/v Write the output to a file: ```shell -curl --user : "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/mynugetpkg.1.3.0.17.nupkg" >> MyNuGetPkg.1.3.0.17.nupkg +curl --user : "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/mynugetpkg.1.3.0.17.nupkg" > MyNuGetPkg.1.3.0.17.nupkg ``` This writes the downloaded file to `MyNuGetPkg.1.3.0.17.nupkg` in the current directory. diff --git a/doc/api/packages/pypi.md b/doc/api/packages/pypi.md index dd301e9fab8..a1c96d03297 100644 --- a/doc/api/packages/pypi.md +++ b/doc/api/packages/pypi.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# PyPI API +# PyPI API **(FREE)** This is the API documentation for [PyPI Packages](../../user/packages/pypi_repository/index.md). @@ -47,7 +47,8 @@ To write the output to a file: curl --user : "https://gitlab.example.com/api/v4/groups/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" >> my.pypi.package-0.0.1.tar.gz ``` -This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current directory. +This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current +directory. ## Group level simple API entry point @@ -106,7 +107,7 @@ GET projects/:id/packages/pypi/files/:sha256/:file_identifier | --------- | ---- | -------- | ----------- | | `id` | string | yes | The ID or full path of the project. | | `sha256` | string | yes | PyPI package file sha256 check sum. | -| `file_identifier` | string | yes | The PyPI package file name. | +| `file_identifier` | string | yes | The PyPI package filename. | ```shell curl --user : "https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" @@ -118,7 +119,8 @@ To write the output to a file: curl --user : "https://gitlab.example.com/api/v4/projects/1/packages/pypi/files/5y57017232013c8ac80647f4ca153k3726f6cba62d055cd747844ed95b3c65ff/my.pypi.package-0.0.1.tar.gz" >> my.pypi.package-0.0.1.tar.gz ``` -This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current directory. +This writes the downloaded file to `my.pypi.package-0.0.1.tar.gz` in the current +directory. ## Project-level simple API entry point diff --git a/doc/api/packages/rubygems.md b/doc/api/packages/rubygems.md index 426548d5ed2..10dcaafda42 100644 --- a/doc/api/packages/rubygems.md +++ b/doc/api/packages/rubygems.md @@ -4,7 +4,7 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Ruby gems API +# Ruby gems API **(FREE SELF)** This is the API documentation for [Ruby gems](../../user/packages/rubygems_registry/index.md). diff --git a/doc/api/pages.md b/doc/api/pages.md index ef6523520de..f81a3c3c72b 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Pages API +# Pages API **(FREE)** Endpoints for managing [GitLab Pages](https://about.gitlab.com/stages-devops-lifecycle/pages/). diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 46d92db9853..47a8df3875e 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Pages domains API +# Pages domains API **(FREE)** Endpoints for connecting custom domain(s) and TLS certificates in [GitLab Pages](https://about.gitlab.com/stages-devops-lifecycle/pages/). diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index 4949bf504fa..b96ee81f673 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -4,14 +4,14 @@ group: Compliance info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Personal access tokens API +# Personal access tokens API **(FREE)** You can read more about [personal access tokens](../user/profile/personal_access_tokens.md#personal-access-tokens). ## List personal access tokens -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227264) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227264) in GitLab 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) from GitLab Ultimate to GitLab Free in 13.6. Get a list of personal access tokens. @@ -70,8 +70,8 @@ curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/a ## Revoke a personal access token -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216004) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.3. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) to [GitLab Free](https://about.gitlab.com/pricing/) in 13.6. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216004) in GitLab 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/270200) from GitLab Ultimate to GitLab Free in 13.6. Revoke a personal access token. diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index 2fe3f487ebc..5472e5bc334 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -38,6 +38,9 @@ curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/a ] ``` +The trigger token is displayed in full if the trigger token was created by the authenticated +user. Trigger tokens created by other users are shortened to four characters. + ## Get trigger details Get details of project's build trigger. diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index ad7336bba8f..f3c30a414ea 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -32,10 +32,10 @@ GET /projects/:id/pipelines | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | no | The scope of pipelines, one of: `running`, `pending`, `finished`, `branches`, `tags` | | `status` | string | no | The status of pipelines, one of: `created`, `waiting_for_resource`, `preparing`, `pending`, `running`, `success`, `failed`, `canceled`, `skipped`, `manual`, `scheduled` | +| `source` | string | no | In [GitLab 14.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/325439), how the pipeline was triggered, one of: `push`, `web`, `trigger`, `schedule`, `api`, `external`, `pipeline`, `chat`, `webide`, `merge_request_event`, `external_pull_request_event`, `parent_pipeline`, `ondemand_dast_scan`, or `ondemand_dast_validation`. | | `ref` | string | no | The ref of pipelines | | `sha` | string | no | The SHA of pipelines | | `yaml_errors`| boolean | no | Returns pipelines with invalid configurations | -| `name`| string | no | _([Deprecated in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/336953))_ The name of the user who triggered pipelines | | `username`| string | no | The username of the user who triggered pipelines | | `updated_after` | datetime | no | Return pipelines updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | | `updated_before` | datetime | no | Return pipelines updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). | @@ -55,6 +55,7 @@ Example of response "iid": 12, "project_id": 1, "status": "pending", + "soure": "push", "ref": "new-pipeline", "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", "web_url": "https://example.com/foo/bar/pipelines/47", @@ -66,6 +67,7 @@ Example of response "iid": 13, "project_id": 1, "status": "pending", + "soure": "web", "ref": "new-pipeline", "sha": "eb94b618fb5865b26e80fdd8ae531b7a63ad851a", "web_url": "https://example.com/foo/bar/pipelines/48", @@ -212,7 +214,7 @@ Sample response: ### Get a pipeline's test report summary -> Introduced in [GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65471) +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65471) in GitLab 14.2. NOTE: This API route is part of the [Unit test report](../ci/unit_test_reports.md) feature. diff --git a/doc/api/plan_limits.md b/doc/api/plan_limits.md index c89c7b46d54..52152dd6e14 100644 --- a/doc/api/plan_limits.md +++ b/doc/api/plan_limits.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Plan limits API **(FREE)** +# Plan limits API **(FREE SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54232) in GitLab 13.10. diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md index 1638bb644c2..0d130f6f484 100644 --- a/doc/api/project_aliases.md +++ b/doc/api/project_aliases.md @@ -7,7 +7,7 @@ type: reference, api # Project Aliases API **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab 12.1. All methods require administrator authorization. diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 2b4976510bb..bb05e4788d0 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -294,7 +294,7 @@ Parameters: | `platform_kubernetes_attributes[token]` | string | no | The token to authenticate against Kubernetes | | `platform_kubernetes_attributes[ca_cert]` | string | no | TLS certificate. Required if API is using a self-signed TLS certificate. | | `platform_kubernetes_attributes[namespace]` | string | no | The unique namespace related to the project | -| `environment_scope` | string | no | The associated environment to the cluster **(PREMIUM)** | +| `environment_scope` | string | no | The associated environment to the cluster | NOTE: `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index e596b25ca22..2dcef40aacb 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, api --- -# Project-level Variables API +# Project-level Variables API **(FREE)** ## List project variables diff --git a/doc/api/project_vulnerabilities.md b/doc/api/project_vulnerabilities.md index 2035d17aa3f..7ba359587f6 100644 --- a/doc/api/project_vulnerabilities.md +++ b/doc/api/project_vulnerabilities.md @@ -7,7 +7,7 @@ type: reference, api # Project Vulnerabilities API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. WARNING: This API is in an alpha stage and considered unstable. diff --git a/doc/api/projects.md b/doc/api/projects.md index a510f05df58..29e3cdf6cbf 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -55,7 +55,7 @@ GET /projects | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | | `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `last_activity_at`, or `similarity` fields. `repository_size`, `storage_size`, `packages_size` or `wiki_size` fields are only allowed for admins. `similarity` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332890) in GitLab 14.1) is only available when searching and is limited to projects that the current user is a member of. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | -| `repository_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2). | +| `repository_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in GitLab 11.2). | | `repository_storage` | string | **{dotted-circle}** No | Limit results to projects stored on `repository_storage`. _(admins only)_ | | `search_namespaces` | boolean | **{dotted-circle}** No | Include ancestor namespaces when matching search criteria. Default is `false`. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | @@ -65,7 +65,7 @@ GET /projects | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `topic` | string | **{dotted-circle}** No | Comma-separated topic names. Limit results to projects that match all of given topics. See `topics` attribute. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | -| `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2). | +| `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in GitLab 11.2). | | `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | @@ -2428,7 +2428,7 @@ POST /projects/:id/housekeeping ## Push Rules **(PREMIUM)** -### Get project push rules **(PREMIUM)** +### Get project push rules Get the [push rules](../push_rules/push_rules.md#enabling-push-rules) of a project. @@ -2474,7 +2474,7 @@ parameters: } ``` -### Add project push rule **(PREMIUM)** +### Add project push rule Adds a push rule to a specified project. @@ -2486,7 +2486,7 @@ POST /projects/:id/push_rule |-----------------------------------------|----------------|------------------------|-------------| | `author_email_regex` | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | -| `commit_committer_check` **(PREMIUM)** | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | | `commit_message_negative_regex` | string | **{dotted-circle}** No | No commit message is allowed to match this, for example `ssh\:\/\/`. | | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | @@ -2495,9 +2495,9 @@ POST /projects/:id/push_rule | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | **{dotted-circle}** No | Reject commit when it's not signed through GPG. | +| `reject_unsigned_commits` | boolean | **{dotted-circle}** No | Reject commit when it's not signed through GPG. | -### Edit project push rule **(PREMIUM)** +### Edit project push rule Edits a push rule for a specified project. @@ -2509,7 +2509,7 @@ PUT /projects/:id/push_rule |-----------------------------------------|----------------|------------------------|-------------| | `author_email_regex` | string | **{dotted-circle}** No | All commit author emails must match this, for example `@my-company.com$`. | | `branch_name_regex` | string | **{dotted-circle}** No | All branch names must match this, for example `(feature|hotfix)\/*`. | -| `commit_committer_check` **(PREMIUM)** | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | +| `commit_committer_check` | boolean | **{dotted-circle}** No | Users can only push commits to this repository that were committed with one of their own verified emails. | | `commit_message_negative_regex` | string | **{dotted-circle}** No | No commit message is allowed to match this, for example `ssh\:\/\/`. | | `commit_message_regex` | string | **{dotted-circle}** No | All commit messages must match this, for example `Fixed \d+\..*`. | | `deny_delete_tag` | boolean | **{dotted-circle}** No | Deny deleting a tag. | @@ -2518,7 +2518,7 @@ PUT /projects/:id/push_rule | `max_file_size` | integer | **{dotted-circle}** No | Maximum file size (MB). | | `member_check` | boolean | **{dotted-circle}** No | Restrict commits by author (email) to existing GitLab users. | | `prevent_secrets` | boolean | **{dotted-circle}** No | GitLab rejects any files that are likely to contain secrets. | -| `reject_unsigned_commits` **(PREMIUM)** | boolean | **{dotted-circle}** No | Reject commits when they are not GPG signed. | +| `reject_unsigned_commits` | boolean | **{dotted-circle}** No | Reject commits when they are not GPG signed. | ### Delete project push rule diff --git a/doc/api/protected_environments.md b/doc/api/protected_environments.md index 9a64e676ad9..82bb1e55e77 100644 --- a/doc/api/protected_environments.md +++ b/doc/api/protected_environments.md @@ -7,7 +7,7 @@ type: concepts, howto # Protected environments API **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30595) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30595) in GitLab 12.8. ## Valid access levels diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 35bf24c586c..72627783947 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Releases API +# Releases API **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. > - Using this API you can manipulate GitLab [Release](../../user/project/releases/index.md) entries. @@ -21,7 +21,7 @@ For authentication, the Releases API accepts either: - A [Personal Access Token](../../user/profile/personal_access_tokens.md) using the `PRIVATE-TOKEN` header. -- The [GitLab CI/CD job token](../index.md#gitlab-cicd-job-token) `$CI_JOB_TOKEN` using +- The [GitLab CI/CD job token](../../ci/jobs/ci_job_token.md) `$CI_JOB_TOKEN` using the `JOB-TOKEN` header. ## List Releases @@ -89,8 +89,8 @@ Example response: "state":"closed", "created_at":"2019-07-12T19:45:44.256Z", "updated_at":"2019-07-12T19:45:44.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/1", "issue_stats": { "total": 98, @@ -106,8 +106,8 @@ Example response: "state":"closed", "created_at":"2019-07-16T14:00:12.256Z", "updated_at":"2019-07-16T14:00:12.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/2", "issue_stats": { "total": 24, @@ -292,8 +292,8 @@ Example response: "state":"closed", "created_at":"2019-07-12T19:45:44.256Z", "updated_at":"2019-07-12T19:45:44.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/1", "issue_stats": { "total": 98, @@ -309,8 +309,8 @@ Example response: "state":"closed", "created_at":"2019-07-16T14:00:12.256Z", "updated_at":"2019-07-16T14:00:12.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/2", "issue_stats": { "total": 24, @@ -434,8 +434,8 @@ Example response: "state":"closed", "created_at":"2019-07-12T19:45:44.256Z", "updated_at":"2019-07-12T19:45:44.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/1", "issue_stats": { "total": 99, @@ -451,8 +451,8 @@ Example response: "state":"closed", "created_at":"2019-07-16T14:00:12.256Z", "updated_at":"2019-07-16T14:00:12.256Z", - "due_date":"2019-08-16T11:00:00.256Z", - "start_date":"2019-07-30T12:00:00.256Z", + "due_date":"2019-08-16", + "start_date":"2019-07-30", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/2", "issue_stats": { "total": 24, @@ -499,7 +499,7 @@ Example response: ### Group milestones **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235391) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235391) in GitLab 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) @@ -508,7 +508,7 @@ adding milestones for ancestor groups raises an error. ## Collect release evidence **(PREMIUM SELF)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in GitLab 12.10. Create Evidence for an existing Release. @@ -600,8 +600,8 @@ Example response: "state":"active", "created_at":"2019-09-01T13:00:00.256Z", "updated_at":"2019-09-01T13:00:00.256Z", - "due_date":"2019-09-20T13:00:00.256Z", - "start_date":"2019-09-05T12:00:00.256Z", + "due_date":"2019-09-20", + "start_date":"2019-09-05", "web_url":"https://gitlab.example.com/root/awesome-app/-/milestones/3", "issue_stats": { "opened": 11, diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index 2f8dc363124..c9d183b8351 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -4,7 +4,7 @@ group: Release info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Release links API +# Release links API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7. diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 9d464c94d99..1c9136d22ac 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -200,7 +200,8 @@ Example response: "deleted_file": false }], "compare_timeout": false, - "compare_same_ref": false + "compare_same_ref": false, + "web_url": "https://gitlab.example.com/thedude/gitlab-foss/-/compare/ae73cb07c9eeaf35924a10f713b364d32b2dd34f...0b4bc9a49b562e85de7cc9e834518ea6828729b9" } ``` @@ -214,7 +215,7 @@ GET /projects/:id/repository/contributors ``` WARNING: -The `additions` and `deletions` attributes are deprecated [as of GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39653), because they [always return `0`](https://gitlab.com/gitlab-org/gitlab/-/issues/233119). +The `additions` and `deletions` attributes are [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39653) as of GitLab 13.4, because they [always return `0`](https://gitlab.com/gitlab-org/gitlab/-/issues/233119). Supported attributes: @@ -447,6 +448,10 @@ You can set the following variables in this file: - `template`: a custom template to use for generating the changelog data. - `categories`: a hash that maps raw category names to the names to use in the changelog. +- `include_groups`: a list of group full paths containing users whose + contributions should be credited regardless of project membership. The user + generating the changelog must have access to each group or the members will + not be credited. Using the default settings, generating a changelog results in a section along the lines of the following: @@ -507,7 +512,7 @@ follows: {% each entries %} - [{{ title }}]({{ commit.reference }})\ -{% if author.contributor %} by {{ author.reference }}{% end %}\ +{% if author.credit %} by {{ author.reference }}{% end %}\ {% if merge_request %} ([merge request]({{ merge_request.reference }})){% end %} {% end %} @@ -597,7 +602,7 @@ template: | {% each entries %} - [{{ title }}]({{ commit.reference }})\ - {% if author.contributor %} by {{ author.reference }}{% end %} + {% if author.credit %} by {{ author.reference }}{% end %} {% end %} @@ -633,8 +638,11 @@ In an entry, the following variables are available (here `foo.bar` means that - `commit.trailers`: an object containing all the Git trailers that were present in the commit body. - `author.reference`: a reference to the commit author (for example, `@alice`). -- `author.contributor`: a boolean set to `true` when the author is an external - contributor, otherwise this is set to `false`. +- `author.contributor`: a boolean set to `true` when the author is not a project + member, otherwise `false`. +- `author.credit`: a boolean set to `true` when `author.contributor` is `true` or + when `include_groups` is configured, and the author is a member of one of the + groups. - `merge_request.reference`: a reference to the merge request that first introduced the change (for example, `gitlab-org/gitlab!50063`). diff --git a/doc/api/resource_access_tokens.md b/doc/api/resource_access_tokens.md index 3532cfda47b..fa1e7aace9a 100644 --- a/doc/api/resource_access_tokens.md +++ b/doc/api/resource_access_tokens.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Project access tokens API +# Project access tokens API **(FREE)** You can read more about [project access tokens](../user/project/settings/project_access_tokens.md). diff --git a/doc/api/resource_label_events.md b/doc/api/resource_label_events.md index c5292059c0f..9c05d32c992 100644 --- a/doc/api/resource_label_events.md +++ b/doc/api/resource_label_events.md @@ -95,7 +95,7 @@ Parameters: curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/issues/11/resource_label_events/1" ``` -## Epics **(ULTIMATE)** +## Epics **(PREMIUM)** ### List group epic label events diff --git a/doc/api/runners.md b/doc/api/runners.md index 9e48331cdea..bfdf2d49100 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -4,7 +4,7 @@ group: Runner info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Runners API +# Runners API **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5. @@ -41,7 +41,6 @@ GET /runners?scope=active GET /runners?type=project_type GET /runners?status=active GET /runners?tag_list=tag1,tag2 -GET /runners?search=gitlab ``` | Attribute | Type | Required | Description | @@ -50,7 +49,6 @@ GET /runners?search=gitlab | `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | | `tag_list` | string array | no | List of the runner's tags | -| `search` | string | no | The full token or partial description text to match | ```shell curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/runners" @@ -85,7 +83,7 @@ Example response: ] ``` -## List all runners +## List all runners **(FREE SELF)** Get a list of all runners in the GitLab instance (specific and shared). Access is restricted to users with `admin` privileges. @@ -160,6 +158,8 @@ Example response: ] ``` +To view more than the first 20 runners, use [pagination](index.md#pagination). + ## Get runner's details Get details of a runner. @@ -246,8 +246,8 @@ curl --request PUT --header "PRIVATE-TOKEN: " "https://gitlab ``` NOTE: -The `token` attribute in the response was deprecated [in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320). -and removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/214322). +The `token` attribute in the response was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/214320) in GitLab 12.10. +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/214322) in GitLab 13.0. Example response: @@ -675,3 +675,48 @@ Response: |-----------|---------------------------------| | 200 | Credentials are valid | | 403 | Credentials are invalid | + +## Reset instance's runner registration token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3. + +Resets the runner registration token for the GitLab instance. + +```plaintext +POST /runners/reset_registration_token +``` + +```shell +curl --request POST --header "PRIVATE-TOKEN: " \ + "https://gitlab.example.com/api/v4/runners/reset_registration_token" +``` + +## Reset project's runner registration token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3. + +Resets the runner registration token for a project. + +```plaintext +POST /projects/:id/runners/reset_registration_token +``` + +```shell +curl --request POST --header "PRIVATE-TOKEN: " \ + "https://gitlab.example.com/api/v4/projects/9/runners/reset_registration_token" +``` + +## Reset group's runner registration token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3. + +Resets the runner registration token for a group. + +```plaintext +POST /groups/:id/runners/reset_registration_token +``` + +```shell +curl --request POST --header "PRIVATE-TOKEN: " \ + "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token" +``` diff --git a/doc/api/scim.md b/doc/api/scim.md index 42580ba65b6..2d9cc148412 100644 --- a/doc/api/scim.md +++ b/doc/api/scim.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # SCIM API (SYSTEM ONLY) **(PREMIUM SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab Premium 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9388) in GitLab 11.10. The SCIM API implements the [RFC7644 protocol](https://tools.ietf.org/html/rfc7644). As this API is for **system** use for SCIM provider integration, it is subject to change without notice. diff --git a/doc/api/services.md b/doc/api/services.md index 8daaa532ff4..cf6c5ec511b 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -503,7 +503,7 @@ GET /projects/:id/services/emails-on-push ## Confluence service -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220934) in GitLab 13.2. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220934) in GitLab 13.2. Replaces the link to the internal wiki with a link to a Confluence Cloud Workspace. @@ -659,7 +659,7 @@ PUT /projects/:id/services/hangouts-chat ``` NOTE: -Specific event parameters (for example, `push_events` flag) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) +Specific event parameters (for example, `push_events` flag) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4. Parameters: @@ -1119,7 +1119,7 @@ PUT /projects/:id/services/slack ``` NOTE: -Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) +Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4. Parameters: @@ -1153,6 +1153,8 @@ Parameters: | `tag_push_events` | boolean | false | Enable notifications for tag push events | | `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications | | `wiki_page_events` | boolean | false | Enable notifications for wiki page events | +| `vulnerability_channel` | string | false | **(ULTIMATE)** The name of the channel to receive vulnerability event notifications. | +| `vulnerability_events` | boolean | false | **(ULTIMATE)** Enable notifications for vulnerability events | ### Delete Slack service @@ -1229,7 +1231,7 @@ PUT /projects/:id/services/mattermost ``` NOTE: -Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced in v10.4](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) +Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4. Parameters: @@ -1250,6 +1252,7 @@ Parameters: | `confidential_note_events` | boolean | false | Enable notifications for confidential note events | | `pipeline_events` | boolean | false | Enable notifications for pipeline events | | `wiki_page_events` | boolean | false | Enable notifications for wiki page events | +| `vulnerability_events` | boolean | false | **(ULTIMATE)** Enable notifications for vulnerability events | | `push_channel` | string | false | The name of the channel to receive push events notifications | | `issue_channel` | string | false | The name of the channel to receive issues events notifications | | `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications | @@ -1259,6 +1262,7 @@ Parameters: | `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications | | `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications | | `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications | +| `vulnerability_channel` | string | false | **(ULTIMATE)** The name of the channel to receive vulnerability events notifications | ### Delete Mattermost notifications service @@ -1361,7 +1365,7 @@ GET /projects/:id/services/jenkins A continuous integration and build server NOTE: -This service was [removed in v13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) +This service was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) in GitLab 13.0. ### Create/Edit Jenkins CI (Deprecated) service diff --git a/doc/api/settings.md b/doc/api/settings.md index d49359b5d43..6b1faa0402f 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -96,7 +96,7 @@ Example response: } ``` -Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) may also see the `file_template_project_id`, `delayed_project_deletion`, `deletion_adjourned_period`, or the `geo_node_allowed_ips` parameters: ```json @@ -197,7 +197,7 @@ Example response: } ``` -Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see +Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) may also see these parameters: - `file_template_project_id` @@ -334,7 +334,7 @@ listed in the descriptions of the relevant settings. | `issues_create_limit` | integer | no | Max number of issue creation requests per minute per user. Disabled by default.| | `keep_latest_artifact` | boolean | no | Prevent the deletion of the artifacts from the most recent successful jobs, regardless of the expiry time. Enabled by default. | | `local_markdown_version` | integer | no | Increase this value when any cached Markdown should be invalidated. | -| `mailgun_signing_key` | string | no | The Mailgun HTTP webhook signing key for receiving events from webhook | +| `mailgun_signing_key` | string | no | The Mailgun HTTP webhook signing key for receiving events from webhook. | | `mailgun_events_enabled` | boolean | no | Enable Mailgun event receiver. | | `maintenance_mode_message` | string | no | **(PREMIUM)** Message displayed when instance is in maintenance mode. | | `maintenance_mode` | boolean | no | **(PREMIUM)** When instance is in maintenance mode, non-administrative users can sign in with read-only access and make read-only API requests. | @@ -386,6 +386,9 @@ listed in the descriptions of the relevant settings. | `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | | `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared runners per month. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | +| `sidekiq_job_limiter_mode` | string | no | `track` or `compress`. Sets the behavior for [Sidekiq job size limits](../user/admin_area/settings/sidekiq_job_limits.md). Default: 'compress'. | +| `sidekiq_job_limiter_compression_threshold_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are compressed before being stored in Redis. Default: 100 000 bytes (100KB). | +| `sidekiq_job_limiter_limit_bytes` | integer | no | The threshold in bytes at which Sidekiq jobs are rejected. Default: 0 bytes (doesn't reject any job). | | `sign_in_text` | string | no | Text on the login page. | | `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. | | `signup_enabled` | boolean | no | Enable registration. Default is `true`. | @@ -412,15 +415,22 @@ listed in the descriptions of the relevant settings. | `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_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_enabled` | boolean | no | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_enabled` or `throttle_unauthenticated_api_enabled` instead.) (**If enabled, requires:** `throttle_unauthenticated_period_in_seconds` and `throttle_unauthenticated_requests_per_period`) Enable unauthenticated web 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` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_period_in_seconds` or `throttle_unauthenticated_api_period_in_seconds` instead.) Rate limit period in seconds. | +| `throttle_unauthenticated_requests_per_period` | integer | required by:
`throttle_unauthenticated_enabled` | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/335300) in GitLab 14.3. Use `throttle_unauthenticated_web_requests_per_period` or `throttle_unauthenticated_api_requests_per_period` instead.) Max requests per period per IP. | +| `throttle_unauthenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_api_period_in_seconds` and `throttle_unauthenticated_api_requests_per_period`) Enable unauthenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_unauthenticated_api_period_in_seconds` | integer | required by:
`throttle_unauthenticated_api_enabled` | Rate limit period in seconds. | +| `throttle_unauthenticated_api_requests_per_period` | integer | required by:
`throttle_unauthenticated_api_enabled` | Max requests per period per IP. | +| `throttle_unauthenticated_web_enabled` | boolean | no | (**If enabled, requires:** `throttle_unauthenticated_web_period_in_seconds` and `throttle_unauthenticated_web_requests_per_period`) Enable unauthenticated web request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | +| `throttle_unauthenticated_web_period_in_seconds` | integer | required by:
`throttle_unauthenticated_web_enabled` | Rate limit period in seconds. | +| `throttle_unauthenticated_web_requests_per_period` | integer | required by:
`throttle_unauthenticated_web_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_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 is counted towards the limit. | | `usage_ping_enabled` | boolean | no | Every week GitLab reports license usage back to GitLab, Inc. | +| `user_deactivation_emails_enabled` | boolean | no | Send an email to users upon account deactivation. | | `user_default_external` | boolean | no | Newly registered users are external by default. | | `user_default_internal_regex` | string | no | Specify an email address regex pattern to identify default internal users. | | `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider. | diff --git a/doc/api/statistics.md b/doc/api/statistics.md index a57838e6496..75dfa0de705 100644 --- a/doc/api/statistics.md +++ b/doc/api/statistics.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Application statistics API +# Application statistics API **(FREE SELF)** ## Get current application statistics diff --git a/doc/api/status_checks.md b/doc/api/status_checks.md index 25ccd5d767a..0c72ee37348 100644 --- a/doc/api/status_checks.md +++ b/doc/api/status_checks.md @@ -42,9 +42,9 @@ GET /projects/:id/merge_requests/:merge_request_iid/status_checks ] ``` -## Set approval status of an external status check +## Set status of an external status check -For a single merge request, use the API to inform GitLab that a merge request has been approved by an external service. +For a single merge request, use the API to inform GitLab that a merge request has passed a check by an external service. ```plaintext POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses @@ -62,7 +62,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses NOTE: `sha` must be the SHA at the `HEAD` of the merge request's source branch. -## Get project external status checks **(ULTIMATE)** +## Get project external status checks You can request information about a project's external status checks using the following endpoint: @@ -97,7 +97,7 @@ GET /projects/:id/external_status_checks ] ``` -## Create external status check **(ULTIMATE)** +## Create external status check You can create a new external status check for a project using the following endpoint: @@ -116,7 +116,7 @@ defined external service. This includes confidential merge requests. | `external_url` | string | yes | URL of status check resource | | `protected_branch_ids` | `array` | no | IDs of protected branches to scope the rule by | -## Delete external status check **(ULTIMATE)** +## Delete external status check You can delete an external status check for a project using the following endpoint: @@ -129,7 +129,7 @@ DELETE /projects/:id/external_status_checks/:check_id | `rule_id` | integer | yes | ID of an status check | | `id` | integer | yes | ID of a project | -## Update external status check **(ULTIMATE)** +## Update external status check You can update an existing external status check for a project using the following endpoint: diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 39a3ccb2bc3..3587016ac6b 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -4,13 +4,13 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# System hooks API +# System hooks API **(FREE SELF)** All methods require administrator authorization. You can configure the URL endpoint of the system hooks from the GitLab user interface: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. Select **System Hooks** (`/admin/hooks`). Read more about [system hooks](../system_hooks/system_hooks.md). diff --git a/doc/api/templates/dockerfiles.md b/doc/api/templates/dockerfiles.md index 2d7e926561f..5f862201571 100644 --- a/doc/api/templates/dockerfiles.md +++ b/doc/api/templates/dockerfiles.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Dockerfiles API +# Dockerfiles API **(FREE)** GitLab provides an API endpoint for instance-level Dockerfile templates. Default templates are defined at diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index f1bf8120574..71b791de16a 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# .gitignore API +# .gitignore API **(FREE)** In GitLab, the `/gitignores` endpoint returns a list of Git `.gitignore` templates. For more information, see the [Git documentation for `.gitignore`](https://git-scm.com/docs/gitignore). diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index 82abe598cf6..abed008218c 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab CI YMLs API +# GitLab CI YMLs API **(FREE)** In GitLab, there is an API endpoint available to work with GitLab CI/CD YMLs. For more information on CI/CD pipeline configuration in GitLab, see the diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index e7eaa6eb3e0..adba4f75255 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Licenses API +# Licenses API **(FREE)** In GitLab, there is an API endpoint available for working with various open source license templates. For more information on the terms of various diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md index 00d87c89faf..f244c681086 100644 --- a/doc/api/usage_data.md +++ b/doc/api/usage_data.md @@ -11,7 +11,7 @@ The Service Data API is associated with [Service Ping](../development/service_pi ## Export metric definitions as a single YAML file -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57270) in GitLab 13.11. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57270) in GitLab 13.11. Export all metric definitions as a single YAML file, similar to the [Metrics Dictionary](https://gitlab-org.gitlab.io/growth/product-intelligence/metric-dictionary), for easier importing. @@ -37,7 +37,7 @@ Example response: product_group: group::global search product_category: global_search value_type: number - status: data_available + status: active time_frame: 28d data_source: redis_hll distribution: diff --git a/doc/api/users.md b/doc/api/users.md index 6ba751bd292..dfd2f6cc87d 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -4,7 +4,7 @@ group: Access info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Users API +# Users API **(FREE)** ## List users @@ -39,7 +39,7 @@ GET /users ] ``` -You can also search for users by name or primary email using `?search=`. For example. `/users?search=John`. +You can also search for users by name, username, primary email, or secondary email, by using `?search=`. For example. `/users?search=John`. In addition, you can lookup users by username: @@ -124,7 +124,6 @@ GET /users "created_at": "2012-05-23T08:00:58Z", "is_admin": false, "bio": "", - "bio_html": "", "location": null, "skype": "", "linkedin": "", @@ -164,7 +163,6 @@ GET /users "created_at": "2012-05-23T08:01:01Z", "is_admin": false, "bio": "", - "bio_html": "", "location": null, "skype": "", "linkedin": "", @@ -191,7 +189,7 @@ GET /users ] ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, `is_auditor`, and `using_license_seat` parameters. +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, `is_auditor`, and `using_license_seat` parameters. ```json [ @@ -207,7 +205,7 @@ Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see ] ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `group_saml` provider option and `provisioned_by_group_id` parameter: ```json @@ -261,7 +259,7 @@ GET /users?with_custom_attributes=true ## Single user -Get a single user. +Get a single user. This endpoint can be accessed without authentication. ### For user @@ -283,7 +281,6 @@ Parameters: "web_url": "http://localhost:3000/john_smith", "created_at": "2012-05-23T08:00:58Z", "bio": "", - "bio_html": "", "bot": false, "location": null, "public_email": "john@example.com", @@ -322,7 +319,6 @@ Example Responses: "created_at": "2012-05-23T08:00:58Z", "is_admin": false, "bio": "", - "bio_html": "", "location": null, "public_email": "john@example.com", "skype": "", @@ -361,7 +357,7 @@ Example Responses: NOTE: The `plan` and `trial` parameters are only available on GitLab Enterprise Edition. -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `is_auditor`, and `extra_shared_runners_minutes_limit` parameters. ```json @@ -375,7 +371,7 @@ the `shared_runners_minutes_limit`, `is_auditor`, and `extra_shared_runners_minu } ``` -Users on GitLab.com [Premium or higher](https://about.gitlab.com/pricing/) also +Users on [GitLab.com Premium or higher](https://about.gitlab.com/pricing/) also see the `group_saml` option and `provisioned_by_group_id` parameter: ```json @@ -551,7 +547,6 @@ GET /user "web_url": "http://localhost:3000/john_smith", "created_at": "2012-05-23T08:00:58Z", "bio": "", - "bio_html": "", "location": null, "public_email": "john@example.com", "skype": "", @@ -601,7 +596,6 @@ GET /user "created_at": "2012-05-23T08:00:58Z", "is_admin": false, "bio": "", - "bio_html": "", "location": null, "public_email": "john@example.com", "skype": "", @@ -633,7 +627,7 @@ GET /user } ``` -Users on GitLab [Premium or higher](https://about.gitlab.com/pricing/) also see these +Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see these parameters: - `shared_runners_minutes_limit` @@ -668,7 +662,7 @@ Example response: ## Get the status of a user -Get the status of a user. +Get the status of a user. This endpoint can be accessed without authentication. ```plaintext GET /users/:id_or_username/status @@ -812,7 +806,7 @@ Example response: ### Followers and following -Get the followers of a user. +Get the followers of a user. This endpoint can be accessed without authentication. ```plaintext GET /users/:id/followers @@ -1467,6 +1461,46 @@ Returns: - `404 User Not Found` if the user cannot be found. - `403 Forbidden` if the user cannot be activated because they are blocked by an administrator or by LDAP synchronization. +## Ban user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327354) in GitLab 14.3. + +Bans the specified user. Available only for admin. + +```plaintext +POST /users/:id/ban +``` + +Parameters: + +- `id` (required) - ID of specified user + +Returns: + +- `201 OK` on success. +- `404 User Not Found` if user cannot be found. +- `403 Forbidden` when trying to ban a user that is not active. + +## Unban user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327354) in GitLab 14.3. + +Unbans the specified user. Available only for admin. + +```plaintext +POST /users/:id/unban +``` + +Parameters: + +- `id` (required) - ID of specified user + +Returns: + +- `201 OK` on success. +- `404 User Not Found` if the user cannot be found. +- `403 Forbidden` when trying to unban a user that is not banned. + ### Get user contribution events Please refer to the [Events API documentation](events.md#get-user-contribution-events) @@ -1564,6 +1598,45 @@ Example Responses: { "message": "The user you are trying to approve is not pending approval" } ``` +## Reject user + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/339925) in GitLab 14.3. + +Rejects specified user that is [pending approval](../user/admin_area/moderate_users.md#users-pending-approval). Available only for administrators. + +```plaintext +POST /users/:id/reject +``` + +Parameters: + +- `id` (required) - ID of specified user + +```shell +curl --request POST --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/users/42/reject" +``` + +Returns: + +- `200 OK` on success. +- `403 Forbidden` if not authenticated as an administrator. +- `404 User Not Found` if user cannot be found. +- `409 Conflict` if user is not pending approval. + +Example Responses: + +```json +{ "message": "Success" } +``` + +```json +{ "message": "404 User Not Found" } +``` + +```json +{ "message": "User does not have a pending request" } +``` + ## Get an impersonation token of a user > Requires admin permissions. diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 8875e4daa87..3fba95c1fb3 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # API V3 to API V4 WARNING: -The GitLab API v3 was removed in [GitLab 11.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819). +The GitLab API v3 was [removed](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36819) in GitLab 11.0. For information about the current version of the GitLab API, read the [API documentation](index.md). diff --git a/doc/api/version.md b/doc/api/version.md index b23930e70f9..b076993f00e 100644 --- a/doc/api/version.md +++ b/doc/api/version.md @@ -4,7 +4,7 @@ group: Integrations info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Version API +# Version API **(FREE)** > Introduced in GitLab 8.13. diff --git a/doc/api/vulnerabilities.md b/doc/api/vulnerabilities.md index b18a837de26..1c6f7a760e6 100644 --- a/doc/api/vulnerabilities.md +++ b/doc/api/vulnerabilities.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerabilities API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10242) in GitLab 12.6. NOTE: The former Vulnerabilities API was renamed to Vulnerability Findings API diff --git a/doc/api/vulnerability_exports.md b/doc/api/vulnerability_exports.md index 4240d363ff0..9395a4ee5de 100644 --- a/doc/api/vulnerability_exports.md +++ b/doc/api/vulnerability_exports.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability export API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197494) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. [Updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30397) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197494) in GitLab 12.10. [Updated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30397) in GitLab 13.0. WARNING: This API is in an alpha stage and considered unstable. @@ -198,7 +198,7 @@ The response is `404 Not Found` if the vulnerability export is not finished yet Example response: ```csv -Group Name,Project Name,Scanner Type,Scanner Name,Status,Vulnerability,Details,Additional Info,Severity,CVE,CWE,Other Identifiers +Group Name,Project Name,Tool,Scanner Name,Status,Vulnerability,Details,Additional Info,Severity,CVE,CWE,Other Identifiers Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2017-16997 in glibc,,CVE-2017-16997 in glibc,critical,CVE-2017-16997 Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2017-18269 in glibc,,CVE-2017-18269 in glibc,critical,CVE-2017-18269 Gitlab.org,Defend,container_scanning,Trivy,detected,CVE-2018-1000001 in glibc,,CVE-2018-1000001 in glibc,high,CVE-2018-1000001 diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index c7f045a67a0..dfc6074a1aa 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Vulnerability Findings API **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19029) in GitLab Ultimate 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19029) in GitLab 12.5. NOTE: This API resource is renamed from Vulnerabilities to Vulnerability Findings because the Vulnerabilities are reserved diff --git a/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md b/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md index 92717dc1fe9..095eaaec23f 100644 --- a/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md +++ b/doc/architecture/blueprints/composable_codebase_using_rails_engines/index.md @@ -6,6 +6,9 @@ comments: false description: 'Making a GitLab codebase composable - allowing to run parts of the application' --- +NOTE: +Due to our focus on improving the overall availability of GitLab.com and reducing tech debt, we do not have capacity to act on this blueprint. We will re-evaluate in Q1-FY23. + # Composable GitLab codebase - using Rails Engines The one of the major risks of a single codebase is an infinite growth of the whole diff --git a/doc/architecture/blueprints/container_registry_metadata_database/index.md b/doc/architecture/blueprints/container_registry_metadata_database/index.md index b71517de061..f52635baf7b 100644 --- a/doc/architecture/blueprints/container_registry_metadata_database/index.md +++ b/doc/architecture/blueprints/container_registry_metadata_database/index.md @@ -77,12 +77,12 @@ The single entrypoint for the registry is the [HTTP API](https://gitlab.com/gitl | Operation | UI | Background | Observations | | ------------------------------------------------------------ | ------------------ | ------------------------ | ------------------------------------------------------------ | -| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | :heavy_check_mark: | :heavy_check_mark: | Used globally to ensure that the registry supports the Docker Distribution V2 API, as well as for identifying whether GitLab Rails is talking to the GitLab Container Registry or a third-party one (used to toggle features only available in the former). | -| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | :heavy_check_mark: | :heavy_check_mark: | Used to list and show tags in the UI. Used to list tags in the background for [cleanup policies](../../../user/packages/container_registry/#cleanup-policy) and [Geo replication](../../../administration/geo/replication/docker_registry.md). | -| [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | :heavy_check_mark: | :heavy_multiplication_x: | Used to get the digest of a manifest by tag. This is then used to pull the manifest and show the tag details in the UI. | -| [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | :heavy_check_mark: | :heavy_multiplication_x: | Used to show the image size and the manifest digest in the tag details UI. | -| [Pull blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-a-layer) | :heavy_check_mark: | :heavy_multiplication_x: | Used to show the configuration digest and the creation date in the tag details UI. | -| [Delete tag](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-a-tag) | :heavy_check_mark: | :heavy_check_mark: | Used to delete a tag from the UI and in background (cleanup policies). | +| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | **{check-circle}** Yes | **{check-circle}** Yes | Used globally to ensure that the registry supports the Docker Distribution V2 API, as well as for identifying whether GitLab Rails is talking to the GitLab Container Registry or a third-party one (used to toggle features only available in the former). | +| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | **{check-circle}** Yes | **{check-circle}** Yes | Used to list and show tags in the UI. Used to list tags in the background for [cleanup policies](../../../user/packages/container_registry/#cleanup-policy) and [Geo replication](../../../administration/geo/replication/docker_registry.md). | +| [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | **{check-circle}** Yes | **{dotted-circle}** No | Used to get the digest of a manifest by tag. This is then used to pull the manifest and show the tag details in the UI. | +| [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | **{check-circle}** Yes | **{dotted-circle}** No | Used to show the image size and the manifest digest in the tag details UI. | +| [Pull blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-a-layer) | **{check-circle}** Yes | **{dotted-circle}** No | Used to show the configuration digest and the creation date in the tag details UI. | +| [Delete tag](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-a-tag) | **{check-circle}** Yes | **{check-circle}** Yes | Used to delete a tag from the UI and in background (cleanup policies). | A valid authentication token is generated in GitLab Rails and embedded in all these requests before sending them to the registry. @@ -211,22 +211,22 @@ This is a list of all the registry HTTP API operations and how they depend on th | Operation | Method | Path | Requires Database | Requires Storage | Used by GitLab Rails * | |--------------------------------------------------------------------------------------------------------------------------------|----------|-----------------------------------------|-------------------|------------------|------------------------| -| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | `GET` | `/v2/` | ✖ | ✖ | ✔ | -| [List repositories](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-repositories) | `GET` | `/v2/_catalog` | ✔ | ✖ | ✖ | -| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | `GET` | `/v2//tags/list` | ✔ | ✖ | ✔ | -| [Delete tag](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-a-tag) | `DELETE` | `/v2//tags/reference/` | ✔ | ✖ | ✔ | -| [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | `HEAD` | `/v2//manifests/` | ✔ | ✖ | ✔ | -| [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | `GET` | `/v2//manifests/` | ✔ | ✖ | ✔ | -| [Push manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pushing-an-image-manifest) | `PUT` | `/v2//manifests/` | ✔ | ✖ | ✖ | -| [Delete manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-an-image) | `DELETE` | `/v2//manifests/` | ✔ | ✖ | ✖ | -| [Check if blob exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-layers) | `HEAD` | `/v2//blobs/` | ✔ | ✖ | ✖ | -| [Pull blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#fetch-blob) | `GET` | `/v2//blobs/` | ✔ | ✔ | ✔ | -| [Delete blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#delete-blob) | `DELETE` | `/v2//blobs/` | ✔ | ✖ | ✖ | -| [Start blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#starting-an-upload) | `POST` | `/v2//blobs/uploads/` | ✔ | ✔ | ✖ | -| [Check blob upload status](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#get-blob-upload) | `GET` | `/v2//blobs/uploads/` | ✔ | ✔ | ✖ | -| [Push blob chunk](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#chunked-upload-1) | `PATCH` | `/v2//blobs/uploads/` | ✔ | ✔ | ✖ | -| [Complete blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#put-blob-upload) | `PUT` | `/v2//blobs/uploads/` | ✔ | ✔ | ✖ | -| [Cancel blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#canceling-an-upload) | `DELETE` | `/v2//blobs/uploads/` | ✔ | ✔ | ✖ | +| [Check API version](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#api-version-check) | `GET` | `/v2/` | **{dotted-circle}** No | **{dotted-circle}** No | **{check-circle}** Yes | +| [List repositories](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-repositories) | `GET` | `/v2/_catalog` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [List repository tags](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#listing-image-tags) | `GET` | `/v2//tags/list` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | +| [Delete tag](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-a-tag) | `DELETE` | `/v2//tags/reference/` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | +| [Check if manifest exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-manifests) | `HEAD` | `/v2//manifests/` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | +| [Pull manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pulling-an-image-manifest) | `GET` | `/v2//manifests/` | **{check-circle}** Yes | **{dotted-circle}** No | **{check-circle}** Yes | +| [Push manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#pushing-an-image-manifest) | `PUT` | `/v2//manifests/` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [Delete manifest](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#deleting-an-image) | `DELETE` | `/v2//manifests/` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [Check if blob exists](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#existing-layers) | `HEAD` | `/v2//blobs/` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [Pull blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#fetch-blob) | `GET` | `/v2//blobs/` | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| [Delete blob](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#delete-blob) | `DELETE` | `/v2//blobs/` | **{check-circle}** Yes | **{dotted-circle}** No | **{dotted-circle}** No | +| [Start blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#starting-an-upload) | `POST` | `/v2//blobs/uploads/` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| [Check blob upload status](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#get-blob-upload) | `GET` | `/v2//blobs/uploads/` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| [Push blob chunk](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#chunked-upload-1) | `PATCH` | `/v2//blobs/uploads/` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| [Complete blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#put-blob-upload) | `PUT` | `/v2//blobs/uploads/` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| [Cancel blob upload](https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs/spec/api.md#canceling-an-upload) | `DELETE` | `/v2//blobs/uploads/` | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | `*` Please refer to the [list of interactions between registry and Rails](#from-gitlab-rails-to-registry) to know why and how. diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/db_terminology_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/db_terminology_v14_2.png deleted file mode 100644 index 85ba1360f06..00000000000 Binary files a/doc/architecture/blueprints/database/scalability/patterns/img/db_terminology_v14_2.png and /dev/null differ diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_calls_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_calls_v14_2.png index f6ae995391c..ec0f6470bdd 100644 Binary files a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_calls_v14_2.png and b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_calls_v14_2.png differ diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_fixed_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_fixed_v14_2.png index dcfaae230d3..40abdd1e238 100644 Binary files a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_fixed_v14_2.png and b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_licenses_fixed_v14_2.png differ diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_readwriteratio_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_readwriteratio_v14_2.png index 9b85f814bc1..0aa14675b5d 100644 Binary files a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_readwriteratio_v14_2.png and b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_readwriteratio_v14_2.png differ diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_reads_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_reads_v14_2.png index 4f448841e48..66f5ec4bbc1 100644 Binary files a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_reads_v14_2.png and b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_reads_v14_2.png differ diff --git a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_writes_v14_2.png b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_writes_v14_2.png index e4f5756051f..c1d0193ccf0 100644 Binary files a/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_writes_v14_2.png and b/doc/architecture/blueprints/database/scalability/patterns/img/read_mostly_subscriptions_writes_v14_2.png differ diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 87c7af2030d..29a03fe06ab 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: index, concepts, howto --- @@ -37,15 +37,15 @@ can't link to files outside it. - Define artifacts per job. - Subsequent jobs in later stages of the same pipeline can use artifacts. - Different projects cannot share artifacts. - -Artifacts expire after 30 days unless you define an [expiration time](../yaml/index.md#artifactsexpire_in). -Use [dependencies](../yaml/index.md#dependencies) to control which jobs fetch the artifacts. +- Artifacts expire after 30 days by default. You can define a custom [expiration time](../yaml/index.md#artifactsexpire_in). +- The latest artifacts do not expire if [keep latest artifacts](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs) is enabled. +- Use [dependencies](../yaml/index.md#dependencies) to control which jobs fetch the artifacts. ## Good caching practices To ensure maximum availability of the cache, do one or more of the following: -- [Tag your runners](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs +- [Tag your runners](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) and use the tag on jobs that share the cache. - [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects). - [Use a `key`](../yaml/index.md#cachekey) that fits your workflow. For example, diff --git a/doc/ci/chatops/index.md b/doc/ci/chatops/index.md index a461147661c..a2d9cf9054d 100644 --- a/doc/ci/chatops/index.md +++ b/doc/ci/chatops/index.md @@ -7,8 +7,8 @@ type: index, concepts, howto # GitLab ChatOps **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Free](https://about.gitlab.com/pricing/) in 11.9. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in GitLab Ultimate 10.6. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to GitLab Free in 11.9. GitLab ChatOps provides a method to interact with CI/CD jobs through chat services like Slack. Many organizations' discussion, collaboration, and troubleshooting takes 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 60a939496d6..70a9c8fc775 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -29,7 +29,7 @@ repositories: 1. In GitHub, create a token: 1. Open . - 1. Create a **Personal Access Token**. + 1. Create a **Personal Access Token**. 1. Enter a **Token description** and update the scope to allow `repo` and `admin:repo_hook` so that GitLab can access your project, update commit statuses, and create a web hook to notify GitLab of new commits. @@ -57,7 +57,7 @@ To manually enable GitLab CI/CD for your repository: 1. In GitHub, create a token: 1. Open . - 1. Create a **Personal Access Token**. + 1. Create a **Personal Access Token**. 1. Enter a **Token description** and update the scope to allow `repo` so that GitLab can access your project and update commit statuses. 1. In GitLab, create a project: diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 27c808791e5..365e2ee31de 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -7,7 +7,7 @@ type: index, howto # GitLab CI/CD for external repositories **(PREMIUM)** ->[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4642) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6. +>[Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4642) in GitLab 10.6. GitLab CI/CD can be used with: @@ -38,7 +38,7 @@ To connect to an external repository: ## Pipelines for external pull requests -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/65139) in GitLab Premium 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/65139) in GitLab 12.3. When using GitLab CI/CD with an [external repository on GitHub](github_integration.md), it's possible to run a pipeline in the context of a Pull Request. diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md index a4b4fd9fd16..25b87366a30 100644 --- a/doc/ci/cloud_deployment/index.md +++ b/doc/ci/cloud_deployment/index.md @@ -95,7 +95,7 @@ GitLab provides a series of [CI templates that you can include in your project]( To automate deployments of your application to your [Amazon Elastic Container Service](https://aws.amazon.com/ecs/) (AWS ECS) cluster, you can `include` the `AWS/Deploy-ECS.gitlab-ci.yml` template in your `.gitlab-ci.yml` file. -GitLab also provides [Docker images](https://gitlab.com/gitlab-org/cloud-deploy/-/tree/master/aws) that can be used in your `gitlab-ci.yml` file to simplify working with AWS: +GitLab also provides [Docker images](https://gitlab.com/gitlab-org/cloud-deploy/-/tree/master/aws) that can be used in your `.gitlab-ci.yml` file to simplify working with AWS: - Use `registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest` to use AWS CLI commands. - Use `registry.gitlab.com/gitlab-org/cloud-deploy/aws-ecs:latest` to deploy your application to AWS ECS. diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index d965d4b83f9..11ba1e40b3e 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Directed Acyclic Graph +# Directed Acyclic Graph **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063) in GitLab 12.2. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/206902) in GitLab 12.10. diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index c56bc9a4dc8..d5adedc611c 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -23,7 +23,7 @@ To enable Docker commands for your CI/CD jobs, you can use: - [Docker socket binding](#use-docker-socket-binding) If you don't want to execute a runner in privileged mode, -but want to use `docker build`, you can also [use kaniko](using_kaniko.md). +but want to use `docker build`, you can also use [`kaniko`](using_kaniko.md) or [`buildah`](https://github.com/containers/buildah). If you are using shared runners on GitLab.com, [learn more about how these runners are configured](../runners/index.md). diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 421bca9e324..65c907b8e7b 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -7,34 +7,33 @@ type: howto # How to enable or disable GitLab CI/CD **(FREE)** -To effectively use GitLab CI/CD, you need: +To use GitLab CI/CD, you need: - A valid [`.gitlab-ci.yml`](yaml/index.md) file present at the root directory of your project. -- A [runner](runners/index.md) properly set up. +- A [runner](runners/index.md) ready to run jobs. You can read our [quick start guide](quick_start/index.md) to get you started. -If you are using an external CI/CD server like Jenkins or Drone CI, it is advised -to disable GitLab CI/CD in order to not have any conflicts with the commits status +If you use an external CI/CD server like Jenkins or Drone CI, you can +disable GitLab CI/CD to avoid conflicts with the commits status API. -GitLab CI/CD is exposed by using the `/pipelines` and `/jobs` pages of a project. -Disabling GitLab CI/CD in a project does not delete any previous jobs. -In fact, the `/pipelines` and `/jobs` pages can still be accessed, although -it's hidden from the left sidebar menu. +GitLab CI/CD is enabled by default on all new projects. You can: -GitLab CI/CD is enabled by default on new installations and can be disabled -either: +- Disable GitLab CI/CD [under each project's settings](#enable-cicd-in-a-project). +- Set GitLab CI/CD to be [disabled in all new projects on an instance](../administration/cicd.md). -- Individually under each project's settings. -- Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source - and Omnibus installations respectively. +If you disable GitLab CI/CD in a project: -This only applies to pipelines run as part of GitLab CI/CD. This doesn't enable or disable -pipelines that are run from an [external integration](../user/project/integrations/overview.md#integrations-listing). +- The **CI/CD** item in the left sidebar is removed. +- The `/pipelines` and `/jobs` pages are no longer available. +- Existing jobs and pipelines are not deleted. Re-enable CI/CD to access them again. -## Per-project user setting +The project or instance settings do not enable or disable pipelines run in an +[external integration](../user/project/integrations/overview.md#integrations-listing). + +## Enable CI/CD in a project To enable or disable GitLab CI/CD pipelines in your project: @@ -51,54 +50,6 @@ To enable or disable GitLab CI/CD pipelines in your project: Press **Save changes** for the settings to take effect. -## Make GitLab CI/CD disabled by default in new projects - -You can set GitLab CI/CD to be disabled by default in all new projects by modifying the settings in: - -- `gitlab.yml` for source installations. -- `gitlab.rb` for Omnibus GitLab installations. - -Existing projects that already had CI/CD enabled are unchanged. Also, this setting only changes -the project default, so project owners can still enable CI/CD in the project settings. - -For installations from source: - -1. Open `gitlab.yml` with your editor and set `builds` to `false`: - - ```yaml - ## Default project features settings - default_projects_features: - issues: true - merge_requests: true - wiki: true - snippets: false - builds: false - ``` - -1. Save the `gitlab.yml` file. - -1. Restart GitLab: - - ```shell - sudo service gitlab restart - ``` - -For Omnibus GitLab installations: - -1. Edit `/etc/gitlab/gitlab.rb` and add this line: - - ```ruby - gitlab_rails['gitlab_default_projects_features_builds'] = false - ``` - -1. Save the `/etc/gitlab/gitlab.rb` file. - -1. Reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -# End-to-end testing with GitLab CI/CD and WebdriverIO +# End-to-end testing with GitLab CI/CD and WebdriverIO **(FREE)** [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 @@ -20,7 +20,7 @@ environment, reducing the effort to assess the impact of changes. Thus, when we and it will immediately be clear that the application can still be properly built and deployed. After all, you can _see_ it running! -dependencies.io +![dependencies.io](img/deployed_dependency_update.png) However, looking at the freshly deployed code to check whether it still looks and behaves as expected is repetitive manual work, which means it is a prime candidate for automation. This is diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index 0569bb281b9..2c2c6ecd30f 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/index.md @@ -6,7 +6,7 @@ comments: false type: index --- -# GitLab CI/CD Examples +# GitLab CI/CD Examples **(FREE)** This page contains links to a variety of examples that can help you understand how to implement [GitLab CI/CD](../README.md) for your specific use case. @@ -33,7 +33,7 @@ The following table lists examples with step-by-step tutorials that are containe | npm with semantic-release | [Publish npm packages to the GitLab Package Registry using semantic-release](semantic-release.md). | | PHP with Laravel, Envoy | [Test and deploy Laravel applications with GitLab CI/CD and Envoy](laravel_with_gitlab_and_envoy/index.md). | | PHP with npm, SCP | [Running Composer and npm scripts with deployment via SCP in GitLab CI/CD](deployment/composer-npm-deploy.md). | -| PHP with PHPunit, `atoum` | [Testing PHP projects](php.md). | +| PHP with PHPunit, `atoum` | [Testing PHP projects](php.md). | | Secrets management with Vault | [Authenticating and Reading Secrets With HashiCorp Vault](authenticating-with-hashicorp-vault/index.md). | ### Contributed examples @@ -58,7 +58,7 @@ separate example projects: Get started with GitLab CI/CD and your favorite programming language or framework by using a `.gitlab-ci.yml` [template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). -When you create a `gitlab-ci.yml` file in the UI, you can +When you create a `.gitlab-ci.yml` file in the UI, you can choose one of these templates: - [Android (`Android.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Android.gitlab-ci.yml) @@ -76,7 +76,7 @@ choose one of these templates: - [dotNET Core (`dotNET-Core.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/dotNET-Core.gitlab-ci.yml) - [Elixir (`Elixir.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Elixir.gitlab-ci.yml) - [Flutter (`Flutter.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Flutter.gitlab-ci.yml) -- [goLang (`Go.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Go.gitlab-ci.yml) +- [Golang (`Go.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Go.gitlab-ci.yml) - [Gradle (`Gradle.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Gradle.gitlab-ci.yml) - [Grails (`Grails.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Grails.gitlab-ci.yml) - [iOS with fastlane (`iOS-Fastlane.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/iOS-Fastlane.gitlab-ci.yml) @@ -117,15 +117,16 @@ Note that older articles and videos may not reflect the state of the latest GitL For examples of setting up GitLab CI/CD for cloud-based environments, see: - [How to set up multi-account AWS SAM deployments with GitLab CI](https://about.gitlab.com/blog/2019/02/04/multi-account-aws-sam-deployments-with-gitlab-ci/) -- [Automating Kubernetes Deployments with GitLab CI/CD](https://www.youtube.com/watch?v=wEDRfAz6_Uw) +- Video: [Automating Kubernetes Deployments with GitLab CI/CD](https://www.youtube.com/watch?v=wEDRfAz6_Uw) - [How to autoscale continuous deployment with GitLab Runner on DigitalOcean](https://about.gitlab.com/blog/2018/06/19/autoscale-continuous-deployment-gitlab-runner-digital-ocean/) - [How to create a CI/CD pipeline with Auto Deploy to Kubernetes using GitLab and Helm](https://about.gitlab.com/blog/2017/09/21/how-to-create-ci-cd-pipeline-with-autodeploy-to-kubernetes-using-gitlab-and-helm/) -- [Demo - Deploying from GitLab to OpenShift Container Cluster](https://youtu.be/EwbhA53Jpp4) +- Video: [Demo - Deploying from GitLab to OpenShift Container Cluster](https://youtu.be/EwbhA53Jpp4) +- Tutorial: [Set up a GitLab.com Civo Kubernetes integration with GitPod](https://gitlab.com/k33g_org/k33g_org.gitlab.io/-/issues/82) See also the following video overviews: -- [Kubernetes, GitLab, and Cloud Native](https://www.youtube.com/watch?v=d-9awBxEbvQ). -- [Deploying to IBM Cloud with GitLab CI/CD](https://www.youtube.com/watch?v=6ZF4vgKMd-g). +- Video: [Kubernetes, GitLab, and Cloud Native](https://www.youtube.com/watch?v=d-9awBxEbvQ) +- Video: [Deploying to IBM Cloud with GitLab CI/CD](https://www.youtube.com/watch?v=6ZF4vgKMd-g) ### Customer stories @@ -160,7 +161,9 @@ For examples of others who have implemented GitLab CI/CD, see: ### Migrating to GitLab from third-party CI tools -- [Migrating from Jenkins to GitLab](https://youtu.be/RlEVGOpYF5Y) +- [Migrating from CircleCI to GitLab](../migration/circleci.md) +- [Migrating from Jenkins to GitLab](../migration/jenkins.md) +- Video: [Migrating from Jenkins to GitLab](https://youtu.be/RlEVGOpYF5Y) ### Integrating GitLab CI/CD with other systems diff --git a/doc/ci/index.md b/doc/ci/index.md index 9175c20f580..87b259af62a 100644 --- a/doc/ci/index.md +++ b/doc/ci/index.md @@ -9,33 +9,23 @@ type: index # GitLab CI/CD **(FREE)** -GitLab CI/CD is a tool built into GitLab for software development -through the [continuous methodologies](introduction/index.md): +GitLab CI/CD is a tool for software development using the continuous methodologies: -- Continuous Integration (CI) -- Continuous Delivery (CD) -- Continuous Deployment (CD) +- [Continuous Integration (CI)](introduction/index.md#continuous-integration) +- [Continuous Delivery (CD)](introduction/index.md#continuous-delivery) +- [Continuous Deployment (CD)](introduction/index.md#continuous-deployment) NOTE: Out-of-the-box management systems can decrease hours spent on maintaining toolchains by 10% or more. Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) -webcast to learn about continuous methods and how the GitLab built-in CI can help you simplify and scale software development. +webcast to learn about continuous methods and how GitLab CI/CD can help you simplify and scale software development. -Continuous Integration works by pushing small code chunks to your -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. - -Continuous Delivery and Deployment consist of a step further CI, -deploying your application to production at every -push to the default branch of the repository. - -These methodologies allow you to catch bugs and errors early in -the development cycle, ensuring that all the code deployed to +Use GitLab CI/CD to catch bugs and errors early in +the development cycle. Ensure that all the code deployed to production complies with the code standards you established for your app. -GitLab can also automatically detect, build, test, deploy, and +GitLab CI/CD can automatically build, test, deploy, and monitor your applications by using [Auto DevOps](../topics/autodevops/index.md). For a complete overview of these methodologies and GitLab CI/CD, @@ -48,7 +38,7 @@ read the [Introduction to CI/CD with GitLab](introduction/index.md). -## Concepts +## GitLab CI/CD concepts GitLab CI/CD uses a number of concepts to describe and run your build and deploy. @@ -63,7 +53,7 @@ GitLab CI/CD uses a number of concepts to describe and run your build and deploy | [Pipeline efficiency](pipelines/pipeline_efficiency.md) | Configure your pipelines to run quickly and efficiently. | | [Test cases](test_cases/index.md) | Create testing scenarios. | -## Configuration +## GitLab CI/CD configuration GitLab CI/CD supports numerous configuration options: @@ -82,21 +72,20 @@ GitLab CI/CD supports numerous configuration options: Certain operations can only be performed according to the [user](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions. -## Feature set +## GitLab CI/CD features -Use the vast GitLab CI/CD to easily configure it for specific purposes. -Its feature set is listed on the table below according to DevOps stages. +GitLab CI/CD features, grouped by DevOps stage, include: | Feature | Description | |:------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------| | **Configure** | | | [Auto DevOps](../topics/autodevops/index.md) | Set up your app's entire lifecycle. | -| [ChatOps](chatops/index.md) | Trigger CI jobs from chat, with results sent back to the channel. | +| [ChatOps](chatops/index.md) | Trigger CI jobs from chat, with results sent back to the channel. | |-------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------| | **Verify** | | | [Browser Performance Testing](../user/project/merge_requests/browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | | [Load Performance Testing](../user/project/merge_requests/load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | -| [CI services](services/index.md) | Link Docker containers with your base image. | +| [CI services](services/index.md) | Link Docker containers with your base image. | | [Code Quality](../user/project/merge_requests/code_quality.md) | Analyze your source code quality. | | [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md) **(PREMIUM)** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and Bitbucket Cloud. | | [Interactive Web Terminals](interactive_web_terminal/index.md) **(FREE SELF)** | Open an interactive web terminal to debug the running jobs. | @@ -107,7 +96,7 @@ Its feature set is listed on the table below according to DevOps stages. | [Auto Deploy](../topics/autodevops/stages.md#auto-deploy) | Deploy your application to a production environment in a Kubernetes cluster. | | [Building Docker images](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. | | [Canary Deployments](../user/project/canary_deployments.md) | Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature. | -| [Deploy Boards](../user/project/deploy_boards.md) | Check the current health and status of each CI/CD environment running on Kubernetes. | +| [Deploy boards](../user/project/deploy_boards.md) | Check the current health and status of each CI/CD environment running on Kubernetes. | | [Feature Flags](../operations/feature_flags.md) **(PREMIUM)** | Deploy your features behind Feature Flags. | | [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. | | [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. | @@ -120,29 +109,29 @@ Its feature set is listed on the table below according to DevOps stages. | [License Compliance](../user/compliance/license_compliance/index.md) **(ULTIMATE)** | Search your project dependencies for their licenses. | | [Security Test reports](../user/application_security/index.md) **(ULTIMATE)** | Check for app vulnerabilities. | -## Examples +## GitLab CI/CD examples -Find example project code and tutorials for using GitLab CI/CD with a variety of app frameworks, languages, and platforms -on the [CI Examples](examples/README.md) page. +See the [CI/CD examples](examples/README.md) page for example project code and tutorials for +using GitLab CI/CD with various: -## Administration **(FREE SELF)** +- App frameworks +- Languages +- Platforms -As a GitLab administrator, you can change the default behavior -of GitLab CI/CD for: +## GitLab CI/CD Administration -- An [entire GitLab instance](../user/admin_area/settings/continuous_integration.md). -- Specific projects, using [pipelines settings](pipelines/settings.md). +You can change the default behavior of GitLab CI/CD for: + +- An entire GitLab instance in the [CI/CD administration settings](../administration/index.md#cicd-settings). +- Specific projects in the [pipelines settings](pipelines/settings.md). See also: -- [How to enable or disable GitLab CI/CD](enable_or_disable_ci.md). -- Other [CI administration settings](../administration/index.md#continuous-integration-settings). +- [Enable or disable GitLab CI/CD in a project](enable_or_disable_ci.md). ## References -### Why GitLab CI/CD? - -Learn more about: +Learn more about GitLab CI/CD: - [Why you might choose GitLab CI/CD](https://about.gitlab.com/blog/2016/10/17/gitlab-ci-oohlala/). - [Reasons you might migrate from another platform](https://about.gitlab.com/blog/2016/07/22/building-our-web-app-on-gitlab-ci/). @@ -150,10 +139,10 @@ Learn more about: See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJaIOzCX4Vqg3dlwfELC3u2jEeCBbDk) presentation. -### Breaking changes +### Major version changes (breaking) As GitLab CI/CD has evolved, certain breaking changes have -been necessary. These are: +been necessary. #### 13.0 diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 7e72bd44503..5724c56b096 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -5,12 +5,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Interactive Web Terminals +# Interactive Web Terminals **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/50144) in GitLab 11.3. Interactive web terminals give the user access to a terminal in GitLab for -running one-off commands for their CI pipeline. Since this is giving the user +running one-off commands for their CI pipeline. You can think of it like a method for +debugging with SSH, but done directly from the job page. Since this is giving the user shell access to the environment where [GitLab Runner](https://docs.gitlab.com/runner/) is deployed, some [security precautions](../../administration/integration/terminal.md#security) were taken to protect the users. diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md new file mode 100644 index 00000000000..70c22d566e5 --- /dev/null +++ b/doc/ci/jobs/ci_job_token.md @@ -0,0 +1,165 @@ +--- +stage: Verify +group: Pipeline Execution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# GitLab CI/CD job token + +When a pipeline job is about to run, GitLab generates a unique token and injects it as the +[`CI_JOB_TOKEN` predefined variable](../variables/predefined_variables.md). + +You can use a GitLab CI/CD job token to authenticate with specific API endpoints: + +- Packages: + - [Package Registry](../../user/packages/package_registry/index.md). To push to the + Package Registry, you can use [deploy tokens](../../user/project/deploy_tokens/index.md). + - [Container Registry](../../user/packages/container_registry/index.md) + (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). + - [Container Registry API](../../api/container_registry.md) + (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled). +- [Get job artifacts](../../api/job_artifacts.md#get-job-artifacts). +- [Get job token's job](../../api/jobs.md#get-job-tokens-job). +- [Pipeline triggers](../../api/pipeline_triggers.md), using the `token=` parameter. +- [Release creation](../../api/releases/index.md#create-a-release). +- [Terraform plan](../../user/infrastructure/index.md). + +The token has the same permissions to access the API as the user that triggers the +pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../../user/permissions.md#gitlab-cicd-permissions). + +The token is valid only while the pipeline job runs. After the job finishes, you can't +use the token anymore. + +A job token can access a project's resources without any configuration, but it might +give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) +to redesign the feature for more strategic control of the access permissions. + +You can also use the job token to authenticate and clone a repository from a private project +in a CI/CD job: + +```shell +git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com// +``` + +## GitLab CI/CD job token security + +To make sure that this token doesn't leak, GitLab: + +- Masks the job token in job logs. +- Grants permissions to the job token only when the job is running. + +To make sure that this token doesn't leak, you should also configure +your [runners](../runners/index.md) to be secure. Avoid: + +- Using Docker's `privileged` mode if the machines are re-used. +- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs + run on the same machine. + +If you have an insecure GitLab Runner configuration, you increase the risk that someone +tries to steal tokens from other jobs. + +## Limit GitLab CI/CD job token access + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ci-job-token-scope-limit). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +You can limit the access scope of a project's CI/CD job token to increase the +job token's security. A job token might give extra permissions that aren't necessary +to access specific private resources. Limiting the job token access scope reduces the risk of a leaked +token being used to access private data that the user associated to the job can access. + +Control the job token access scope with an allowlist of other projects authorized +to be accessed by authenticating with the current project's job token. By default +the token scope only allows access to the same project where the token comes from. +Other projects can be added and removed by maintainers with access to both projects. + +This setting is enabled by default for all new projects, and disabled by default in projects +created before GitLab 14.1. It is strongly recommended that project maintainers enable this +setting at all times, and configure the allowlist for cross-project access if needed. + +For example, when the setting is enabled, jobs in a pipeline in project `A` have +a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token +to make an API request to a private project `B`, then `B` must be added to the allowlist for `A`. +If project `B` is public or internal, it doesn't need to be added to the allowlist. +The job token scope is only for controlling access to private projects. + +To enable and configure the job token scope limit: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Token Access**. +1. Toggle **Limit CI_JOB_TOKEN access** to enabled. +1. (Optional) Add existing projects to the token's access scope. The user adding a + project must have the [maintainer role](../../user/permissions.md) in both projects. + +If the job token scope limit is disabled, the token can potentially be used to authenticate +API requests to all projects accessible to the user that triggered the job. + +There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve +the feature with more strategic control of the access permissions. + +### Enable or disable CI job token scope limit **(FREE SELF)** + +The GitLab CI/CD job token access scope limit is under development and not ready for production +use. It is deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:ci_scoped_job_token) +``` + +To disable it: + +```ruby +Feature.disable(:ci_scoped_job_token) +``` + +## Trigger a multi-project pipeline by using a CI job token + +> `CI_JOB_TOKEN` for multi-project pipelines was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) from GitLab Premium to GitLab Free in 12.4. + +You can use the `CI_JOB_TOKEN` to trigger [multi-project pipelines](../pipelines/multi_project_pipelines.md) +from a CI/CD job. A pipeline triggered this way creates a dependent pipeline relation +that is visible on the [pipeline graph](../pipelines/multi_project_pipelines.md#multi-project-pipeline-visualization). + +For example: + +```yaml +trigger_pipeline: + stage: deploy + script: + - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" + rules: + - if: $CI_COMMIT_TAG +``` + +If you use the `CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md) +in a pipeline triggered this way, [the value is `pipeline` (not `triggered`)](../triggers/index.md#authentication-tokens). + +## Download an artifact from a different pipeline **(PREMIUM)** + +> `CI_JOB_TOKEN` for artifacts download with the API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in GitLab 9.5. + +You can use the `CI_JOB_TOKEN` to access artifacts from a job created by a previous +pipeline. You must specify which job you want to retrieve the artifacts from: + +```yaml +build_submodule: + stage: test + script: + - apt update && apt install -y unzip + - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" + - unzip artifacts.zip +``` + +Read more about the [jobs artifacts API](../../api/job_artifacts.md#download-the-artifacts-archive). diff --git a/doc/ci/jobs/img/job_group_v12_10.png b/doc/ci/jobs/img/job_group_v12_10.png deleted file mode 100644 index 27e6bfbfc0f..00000000000 Binary files a/doc/ci/jobs/img/job_group_v12_10.png and /dev/null differ diff --git a/doc/ci/jobs/img/pipeline_delayed_job_v14_2.png b/doc/ci/jobs/img/pipeline_delayed_job_v14_2.png new file mode 100644 index 00000000000..8dbb118406c Binary files /dev/null and b/doc/ci/jobs/img/pipeline_delayed_job_v14_2.png differ diff --git a/doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png b/doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png new file mode 100644 index 00000000000..28be633770b Binary files /dev/null and b/doc/ci/jobs/img/pipeline_grouped_jobs_v14_2.png differ diff --git a/doc/ci/jobs/img/pipeline_incremental_rollout.png b/doc/ci/jobs/img/pipeline_incremental_rollout.png deleted file mode 100644 index b3498e9a5a5..00000000000 Binary files a/doc/ci/jobs/img/pipeline_incremental_rollout.png and /dev/null differ diff --git a/doc/ci/jobs/img/pipelines_grouped.png b/doc/ci/jobs/img/pipelines_grouped.png deleted file mode 100644 index 82814754747..00000000000 Binary files a/doc/ci/jobs/img/pipelines_grouped.png and /dev/null differ diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index aa12e1181cb..54704d5574b 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -58,7 +58,7 @@ In each place, if you hover over the failed job you can see the reason it failed ![Pipeline detail](img/job_failure_reason.png) -In [GitLab 10.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814) and later, +In [GitLab 10.8 and later](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814), you can also see the reason it failed on the Job detail page. ## The order of jobs in a pipeline @@ -99,7 +99,7 @@ You can recognize when a pipeline has grouped jobs if you don't see the retry or cancel button inside them. Hovering over them shows the number of grouped jobs. Click to expand them. -![Grouped pipelines](img/pipelines_grouped.png) +![Grouped pipelines](img/pipeline_grouped_jobs_v14_2.png) To create a group of jobs, in the [CI/CD pipeline configuration file](../yaml/index.md), separate each job name with a number and one of the following: @@ -129,9 +129,7 @@ build ruby 3/3: - echo "ruby3" ``` -In the pipeline, the result is a group named `build ruby` with three jobs: - -![Job group](img/job_group_v12_10.png) +The pipeline graph displays a group named `build ruby` with three jobs. The jobs are ordered by comparing the numbers from left to right. You usually want the first number to be the index and the second number to be the total. @@ -179,7 +177,7 @@ For example, if you start rolling out new code and: - Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline and [rolling](../environments/index.md#retry-or-roll-back-a-deployment) back to the last stable version. -![Pipelines example](img/pipeline_incremental_rollout.png) +![Pipelines example](img/pipeline_delayed_job_v14_2.png) ## Expand and collapse job log sections diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index b8b05426297..ad2bbbc883c 100644 --- a/doc/ci/jobs/job_control.md +++ b/doc/ci/jobs/job_control.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- @@ -225,7 +225,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable: | `pipeline` | For [multi-project pipelines](../pipelines/multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../pipelines/multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](../yaml/index.md#trigger) keyword. | | `push` | For pipelines triggered by a `git push` event, including for branches and tags. | | `schedule` | For [scheduled pipelines](../pipelines/schedules.md). | -| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#trigger-token). | +| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | | `webide` | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md). | @@ -290,6 +290,35 @@ You can use the `$` character for both variables and paths. For example, if the `$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the `$` is interpreted as being part of a path. +## Reuse rules in different jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322992) in GitLab 14.3. + +Use [`!reference` tags](../yaml/index.md#reference-tags) to reuse rules in different +jobs. You can combine `!reference` rules with regular job-defined rules: + +```yaml +.default_rules: + rules: + - if: $CI_PIPELINE_SOURCE == "schedule" + when: never + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + +job1: + rules: + - !reference [.default_rules, rules] + script: + - echo "This job runs for the default branch, but not schedules." + +job2: + rules: + - !reference [.default_rules, rules] + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + script: + - echo "This job runs for the default branch, but not schedules." + - echo "It also runs for merge requests." +``` + ## Specify when jobs run with `only` and `except` You can use [`only`](../yaml/index.md#only--except) and [`except`](../yaml/index.md#only--except) @@ -306,7 +335,7 @@ to control when to add jobs to pipelines. In the following example, `job` runs only for: - Git tags -- [Triggers](../triggers/index.md#trigger-token) +- [Triggers](../triggers/index.md#authentication-tokens) - [Scheduled pipelines](../pipelines/schedules.md) ```yaml diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index c3b0cd79d2c..07b4cd80d6a 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -5,11 +5,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Optimizing GitLab for large repositories +# Optimize GitLab for large repositories **(FREE)** Large repositories consisting of more than 50k files in a worktree -often require special consideration because of -the time required to clone and check out. +may require more optimizations beyond +[pipeline efficiency](../pipelines/pipeline_efficiency.md) +because of the time required to clone and check out. GitLab and GitLab Runner handle this scenario well but require optimized configuration to efficiently perform its @@ -251,6 +252,8 @@ and does not require us to update each `.gitlab-ci.yml`. ## Pre-clone step +> [An issue exists](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/463) to remove the need for this optimization. + For very active repositories with a large number of references and files, you can also optimize your CI jobs by seeding repository data with GitLab Runner's [`pre_clone_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section). diff --git a/doc/ci/lint.md b/doc/ci/lint.md index 4e3ac8b9e93..e01bd6b79ff 100644 --- a/doc/ci/lint.md +++ b/doc/ci/lint.md @@ -3,11 +3,8 @@ stage: Verify group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- - - -# Validate .gitlab-ci.yml syntax with the CI Lint tool - - + +# Validate `.gitlab-ci.yml` syntax with the CI Lint tool If you want to test the validity of your GitLab CI/CD configuration before committing the changes, you can use the CI Lint tool. This tool checks for syntax and logical diff --git a/doc/ci/migration/circleci.md b/doc/ci/migration/circleci.md index 106f5b3d819..efaae873588 100644 --- a/doc/ci/migration/circleci.md +++ b/doc/ci/migration/circleci.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index, howto @@ -121,11 +121,11 @@ stages: - test - deploy -job 1: +job1: stage: build script: make build dependencies -job 2: +job2: stage: build script: make build artifacts @@ -216,12 +216,12 @@ jobs: Example of the same workflow using `rules` in GitLab CI/CD: ```yaml -deploy_prod: +deploy: stage: deploy script: - - echo "Deploy to production server" + - echo "Deploy job" rules: - - if: '$CI_COMMIT_BRANCH == "main"' + - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH =~ /^rc-/' ``` ### Caching diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index 1a987a0ce47..925dff8751c 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments comments: false type: index, howto @@ -130,7 +130,7 @@ There are some important differences in the way runners work in comparison to ag - Runners can be set up as [shared across an instance, be added at the group level, or set up at the project level](../runners/runners_scope.md). They self-select jobs from the scopes you've defined automatically. -- You can also [use tags](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) for finer control, and +- You can also [use tags](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) for finer control, and associate runners with specific jobs. For example, you can use a tag for jobs that require dedicated, more powerful, or specific hardware. - GitLab has [autoscaling for runners](https://docs.gitlab.com/runner/configuration/autoscale.html). @@ -199,7 +199,7 @@ GitLab takes advantage of our connected ecosystem to automatically pull these ki your Merge Requests, pipeline details pages, and other locations. You may find that you actually don't need to configure anything to have these appear. -If they aren't working as expected, or if you'd like to see what's available, our [CI feature index](../index.md#feature-set) has the full list +If they aren't working as expected, or if you'd like to see what's available, our [CI feature index](../index.md#gitlab-cicd-features) has the full list of bundled features and links to the documentation for each. ### Templates @@ -230,7 +230,7 @@ and is meant to be a mapping of concepts there to concepts in GitLab. The agent section is used to define how a pipeline executes. For GitLab, we use [runners](../runners/index.md) to provide this capability. You can configure your own runners in Kubernetes or on any host, or take advantage of our shared runner fleet (note that the shared runner fleet is only available for GitLab.com users). -We also support using [tags](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) to direct different jobs +We also support using [tags](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run) to direct different jobs to different runners (execution agents). The `agent` section also allows you to define which Docker images should be used for execution, for which we use diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 7132d47d324..10a6d34b076 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -56,7 +56,7 @@ reflected in the CI lint. It displays the same results as the existing [CI Lint > - [Moved to **CI/CD > Editor**](https://gitlab.com/gitlab-org/gitlab/-/issues/263141) in GitLab 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290117) in GitLab 13.12. -To view a visualization of your `gitlab-ci.yml` configuration, in your project, +To view a visualization of your `.gitlab-ci.yml` configuration, in your project, go to **CI/CD > Editor**, and then select the **Visualize** tab. The visualization shows all stages and jobs. Any [`needs`](../yaml/index.md#needs) relationships are displayed as lines connecting jobs together, showing the diff --git a/doc/ci/pipelines/img/manual_pipeline_v14_2.png b/doc/ci/pipelines/img/manual_pipeline_v14_2.png new file mode 100644 index 00000000000..df1c2a4760a Binary files /dev/null and b/doc/ci/pipelines/img/manual_pipeline_v14_2.png differ diff --git a/doc/ci/pipelines/img/pipelines.png b/doc/ci/pipelines/img/pipelines.png deleted file mode 100644 index a604fcb2587..00000000000 Binary files a/doc/ci/pipelines/img/pipelines.png and /dev/null differ diff --git a/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png deleted file mode 100644 index f2f38979e18..00000000000 Binary files a/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png and /dev/null differ diff --git a/doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png b/doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png new file mode 100644 index 00000000000..b0e9f63f743 Binary files /dev/null and b/doc/ci/pipelines/img/pipelines_graph_stage_view_v14_2.png differ diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 22f18235f99..1eacc799636 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments disqus_identifier: 'https://docs.gitlab.com/ee/ci/pipelines.html' type: reference @@ -122,6 +122,7 @@ you can filter the pipeline list by: - Branch name - 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)) +- Source ([GitLab 14.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/338347)) [Starting in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/26621), you can change the pipeline column to display the pipeline ID or the pipeline IID. @@ -170,9 +171,6 @@ variables: You cannot set job-level variables to be pre-filled when you run a pipeline manually. -Pre-filled variables do not show up when the CI/CD configuration is [external to the project](settings.md#specify-a-custom-cicd-configuration-file). -See the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336184) for more details. - ### Run a pipeline by using a URL query string > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24146) in GitLab 12.5. @@ -212,11 +210,11 @@ allow you to require manual interaction before moving forward in the pipeline. You can do this straight from the pipeline graph. Just click the play button to execute that particular job. -For example, your pipeline might start automatically, but it requires manual action to -[deploy to production](../environments/index.md#configure-manual-deployments). In the example below, the `production` -stage has a job with a manual action. +For example, your pipeline can start automatically, but require a manual action to +[deploy to production](../environments/index.md#configure-manual-deployments). +In the example below, the `production` stage has a job with a manual action: -![Pipelines example](img/pipelines.png) +![Pipelines example](img/manual_pipeline_v14_2.png) #### Start multiple manual actions in a stage @@ -348,9 +346,9 @@ all the jobs in the pipeline. You can group the jobs by: -- Stage, which arranges jobs in the same stage together in the same column. +- Stage, which arranges jobs in the same stage together in the same column: - ![jobs grouped by stage](img/pipelines_graph_stage_view_v13_12.png) + ![jobs grouped by stage](img/pipelines_graph_stage_view_v14_2.png) - [Job dependencies](#view-job-dependencies-in-the-pipeline-graph), which arranges jobs based on their [`needs`](../yaml/index.md#needs) dependencies. @@ -361,21 +359,16 @@ you visualize the entire pipeline, including all cross-project inter-dependencie ### View job dependencies in the pipeline graph > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298973) in GitLab 13.12. -> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 13.12. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 14.0. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 14.2. -This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). -Refer to this feature's version history for more details. - You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/index.md#needs) dependencies. Jobs in the leftmost column run first, and jobs that depend on them are grouped in the next columns. -For example, `build-job2` depends only on jobs in the first column, so it displays -in the second column from the left. `deploy-job2` depends on jobs in both the first +For example, `test-job1` depends only on jobs in the first column, so it displays +in the second column from the left. `deploy-job1` depends on jobs in both the first and second column and displays in the third column: ![jobs grouped by needs dependency](img/pipelines_graph_dependency_view_v13_12.png) diff --git a/doc/ci/pipelines/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md index 3007d91d1b4..d31ddcf736e 100644 --- a/doc/ci/pipelines/multi_project_pipelines.md +++ b/doc/ci/pipelines/multi_project_pipelines.md @@ -273,7 +273,7 @@ upstream_bridge: > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) to GitLab Free in 12.4. -When you use the [`CI_JOB_TOKEN` to trigger pipelines](../triggers/index.md#ci-job-token), +When you use the [`CI_JOB_TOKEN` to trigger pipelines](../jobs/ci_job_token.md), GitLab recognizes the source of the job token. The pipelines become related, so you can visualize their relationships on pipeline graphs. diff --git a/doc/ci/pipelines/parent_child_pipelines.md b/doc/ci/pipelines/parent_child_pipelines.md index b266a721d11..71f778d81b3 100644 --- a/doc/ci/pipelines/parent_child_pipelines.md +++ b/doc/ci/pipelines/parent_child_pipelines.md @@ -61,7 +61,8 @@ microservice_a: include: path/to/microservice_a.yml ``` -You can include multiple files when composing a child pipeline: +You can include multiple files when defining a child pipeline. The child pipeline's +configuration is composed of all configuration files merged together: ```yaml microservice_a: @@ -156,15 +157,11 @@ build a matrix of targets and architectures. For an overview, see [Create child pipelines using dynamically generated configurations](https://youtu.be/nMdfus2JWHM). - - We also have an example project using [Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet) which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. You could use a similar process for other templating languages like -[Dhall](https://dhall-lang.org/) or [`ytt`](https://get-ytt.io/). - - +[Dhall](https://dhall-lang.org/) or [ytt](https://get-ytt.io/). The artifact path is parsed by GitLab, not the runner, so the path must match the syntax for the OS running GitLab. If GitLab is running on Linux but using a Windows diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 91560a0420f..5c3cdd0633e 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -28,6 +28,7 @@ The easiest indicators to check for inefficient pipelines are the runtimes of th stages, and the total runtime of the pipeline itself. The total pipeline duration is heavily influenced by the: +- [Size of the repository](../large_repositories/index.md) - Total number of stages and jobs. - Dependencies between jobs. - The ["critical path"](#directed-acyclic-graphs-dag-visualization), which represents diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index b48c62dccc5..94d7e317104 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -124,7 +124,7 @@ If the CI/CD configuration file is on an external site, the URL must end with `. If the CI/CD configuration file is in a different project: -- The file must exist on its default branch. +- The file must exist on its default branch, or specify the branch as refname. - The path must be relative to the root directory in the other project. - The path must include the group and project name at the end. @@ -132,6 +132,7 @@ For example: - `.gitlab-ci.yml@mygroup/another-project` - `my/path/.my-custom-file.yml@mygroup/another-project` +- `my/path/.my-custom-file.yml@mygroup/another-project:refname` If the configuration file is in a separate project, you can more set more granular permissions. For example: diff --git a/doc/ci/quick_start/index.md b/doc/ci/quick_start/index.md index 257e170b0a5..e2381238318 100644 --- a/doc/ci/quick_start/index.md +++ b/doc/ci/quick_start/index.md @@ -7,8 +7,7 @@ type: reference # Get started with GitLab CI/CD **(FREE)** -Use this document to get started with -GitLab [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/). +Use this document to get started with [GitLab CI/CD](../index.md). Before you start, make sure you have: @@ -126,7 +125,7 @@ The pipeline starts when the commit is committed. ```yaml default: - image: ruby:2.7.2 + image: ruby:2.7.4 ``` This command tells the runner to use a Ruby image from Docker Hub @@ -141,8 +140,22 @@ The pipeline starts when the commit is committed. [CI Lint tool](../lint.md), which is available in every project. - You can also use [CI/CD configuration visualization](../pipeline_editor/index.md#visualize-ci-configuration) to view a graphical representation of your `.gitlab-ci.yml` file. -- For the complete `.gitlab-ci.yml` syntax, see - [the `.gitlab-ci.yml` reference topic](../yaml/index.md). +- Each job contains scripts and stages: + - The [`default`](../yaml/index.md#custom-default-keyword-values) keyword is for + custom defaults, for example with [`before_script`](../yaml/index.md#before_script) + and [`after_script`](../yaml/index.md#after_script). + - [`stage`](../yaml/index.md#stage) describes the sequential execution of jobs. + Jobs in a single stage run in parallel as long as there are available runners. + - Use [Directed Acyclic Graphs (DAG)](../directed_acyclic_graph/index.md) keywords + to run jobs out of stage order. +- You can set additional configuration to customize how your jobs and stages perform: + - Use the [`rules`](../yaml/index.md#rules) keyword to specify when to run or skip jobs. + The `only` and `except` legacy keywords are still supported, but can't be used + with `rules` in the same job. + - Keep information across jobs and stages persistent in a pipeline with [`cache`](../yaml/index.md#cache)) + and [`artifacts`](../yaml/index.md#artifacts). These keywords are ways to store + dependencies and job output, even when using ephemeral runners for each job. +- For the complete `.gitlab-ci.yml` syntax, see [the full `.gitlab-ci.yml` reference topic](../yaml/index.md). ### View the status of your pipeline and jobs diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 8af04388f92..1b926d506c4 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -57,7 +57,7 @@ The process of configuring Review Apps is as follows: 1. Set up the infrastructure to host and deploy the Review Apps (check the [examples](#review-apps-examples) below). 1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a runner to do deployment. -1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI/CD variable](../variables/index.md) `${CI_COMMIT_REF_NAME}` +1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI/CD variable](../variables/index.md) `${CI_COMMIT_REF_SLUG}` to create dynamic environments and restrict it to run only on branches. Alternatively, you can get a YML template for this job by [enabling review apps](#enable-review-apps-button) for your project. 1. Optionally, set a job that [manually stops](../environments/index.md#stop-an-environment) the Review Apps. diff --git a/doc/ci/runners/build_cloud/macos/environment.md b/doc/ci/runners/build_cloud/macos/environment.md index e84b7d0a207..5336890b931 100644 --- a/doc/ci/runners/build_cloud/macos/environment.md +++ b/doc/ci/runners/build_cloud/macos/environment.md @@ -4,12 +4,12 @@ group: Runner info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# VM instances and images for Build Cloud for macOS +# VM instances and images for Build Cloud for macOS When you use the Build Cloud for macOS: -- Each of your jobs runs in a newly provisioned VM, which is dedicated to the specific job. -- The VM is active only for the duration of the job and immediately deleted. +- Each of your jobs runs in a newly provisioned VM, which is dedicated to the specific job. +- The VM is active only for the duration of the job and immediately deleted. ## VM types diff --git a/doc/ci/runners/build_cloud/macos_build_cloud.md b/doc/ci/runners/build_cloud/macos_build_cloud.md index 1400c7e08db..794bc2e597d 100644 --- a/doc/ci/runners/build_cloud/macos_build_cloud.md +++ b/doc/ci/runners/build_cloud/macos_build_cloud.md @@ -12,11 +12,11 @@ of all the capabilities of the GitLab single DevOps platform and not have to man build environment. Build Cloud runners for macOS are in [Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) -and shouldn't be relied upon for mission-critical production jobs. +and shouldn't be relied upon for mission-critical production jobs. ## Quickstart -To start using Build Cloud for macOS Beta, you must submit an access request issue. After your +To start using Build Cloud for macOS Beta, you must submit an access request [issue](https://gitlab.com/gitlab-com/macos-buildcloud-runners-beta/-/issues/new?issuable_template=beta_access_request). After your access has been granted and your build environment configured, you must configure your `.gitlab-ci.yml` pipeline file: diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index 2f845a05a4e..13897b934c5 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Configuring runners +# Configuring runners **(FREE)** If you have installed your own runners, you can configure and secure them in GitLab. @@ -107,10 +107,10 @@ We're always looking for contributions that can mitigate these ### Reset the runner registration token for a project If you think that a registration token for a project was revealed, you should -reset it. A token can be used to register another runner for the project. That new runner -may then be used to obtain the values of secret variables or to clone project code. +reset it. A registration token can be used to register another runner for the project. +That new runner may then be used to obtain the values of secret variables or to clone project code. -To reset the token: +To reset the registration token: 1. Go to the project's **Settings > CI/CD**. 1. Expand the **General pipelines settings** section. @@ -124,6 +124,16 @@ any new runners to the project. If you are using any tools to provision and register new runners, the tokens used in those tools should be updated to reflect the value of the new token. +### Reset the runner authentication token + +If you think that an authentication token for a runner was revealed, you should +reset it. An attacker could use the token to [clone a runner](https://docs.gitlab.com/runner/security/#cloning-a-runner). + +To reset the authentication token, [unregister the runner](https://docs.gitlab.com/runner/commands/#gitlab-runner-unregister) +and then [register](https://docs.gitlab.com/runner/commands/#gitlab-runner-register) it again. + +To verify that the previous authentication token has been revoked, use the [Runners API](../../api/runners.md#verify-authentication-for-a-registered-runner). + ## Determine the IP address of a runner > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17286) in GitLab 10.6. @@ -142,7 +152,7 @@ different places. To view the IP address of a shared runner you must have admin access to the GitLab instance. To determine this: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Runners**. 1. Find the runner in the table and view the **IP Address** column. @@ -159,13 +169,13 @@ project. ![specific runner IP address](img/specific_runner_ip_address.png) -## Use tags to limit the number of jobs using the runner +## Use tags to control which jobs a runner can run You must set up a runner to be able to run all the different types of jobs that it may encounter on the projects it's shared over. This would be problematic for large amounts of projects, if it weren't for tags. -GitLab CI tags are not the same as Git tags. GitLab CI tags are associated with runners. +GitLab CI/CD tags are not the same as Git tags. GitLab CI/CD tags are associated with runners. Git tags are associated with commits. By tagging a runner for the types of jobs it can handle, you can make sure @@ -174,6 +184,8 @@ shared runners will [only run the jobs they are equipped to run](../yaml/index.m For instance, at GitLab we have runners tagged with `rails` if they contain the appropriate dependencies to run Rails test suites. +### Set a runner to run untagged jobs + When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick** [tagged jobs](../yaml/index.md#tags). To change this, you must have the [Owner role](../../user/permissions.md#project-members-permissions) for the project. @@ -228,6 +240,48 @@ Example 2: 1. A job that has no tags defined is executed and run. 1. A second job that has a `docker` tag defined is stuck. +### Use tags to run jobs on different platforms + +You can use tags to run different jobs on different platforms. For +example, if you have an OS X runner with tag `osx` and a Windows runner with tag +`windows`, you can run a job on each platform: + +```yaml +windows job: + stage: + - build + tags: + - windows + script: + - echo Hello, %USERNAME%! + +osx job: + stage: + - build + tags: + - osx + script: + - echo "Hello, $USER!" +``` + +### Use CI/CD variables in tags + +> Introduced in [GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/35742). + +You can use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: + +```yaml +variables: + KUBERNETES_RUNNER: kubernetes + + job: + tags: + - docker + - $KUBERNETES_RUNNER + script: + - echo "Hello runner selector feature" +``` + ## Configure runner behavior with variables You can use [CI/CD variables](../variables/index.md) to configure runner Git behavior @@ -546,7 +600,7 @@ the following stages: | Variable | Description | |---------------------------------|--------------------------------------------------------| | `ARTIFACT_DOWNLOAD_ATTEMPTS` | Number of attempts to download artifacts running a job | -| `EXECUTOR_JOB_SECTION_ATTEMPTS` | [In GitLab 12.10](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) and later, the number of attempts to run a section in a job after a [`No Such Container`](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4450) error ([Docker executor](https://docs.gitlab.com/runner/executors/docker.html) only). | +| `EXECUTOR_JOB_SECTION_ATTEMPTS` | In [GitLab 12.10 and later](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). | | `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 | diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index 6642913a9d8..9acca60c4b4 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab Build Cloud runners +# GitLab Build Cloud runners **(FREE)** If you are using self-managed GitLab or you want to use your own runners on GitLab.com, you can [install and configure your own runners](https://docs.gitlab.com/runner/install/). diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index 2af373384d2..b16957ae83c 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# The scope of runners +# The scope of runners **(FREE)** Runners are available based on who you want to have access: @@ -168,7 +168,7 @@ You must have the [Owner role](../../user/permissions.md#group-members-permissio | Attribute | Description | | ------------ | ----------- | - | Type | Displays the runner type: `group` or `specific`, together with the optional states `locked` and `paused` | + | Type | Displays the runner type: `group` or `specific`, and the optional state `paused` | | Runner token | Token used to identify the runner, and that the runner uses to communicate with the GitLab instance | | Description | Description given to the runner when it was created | | Version | GitLab Runner version | @@ -242,10 +242,10 @@ You can configure a specific runner so it is "locked" and cannot be enabled for This setting can be enabled when you first [register a runner](https://docs.gitlab.com/runner/register/), but can also be changed later. -To lock or unlock a runner: +To lock or unlock a specific runner: 1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. Find the runner you want to lock or unlock. Make sure it's enabled. +1. Find the specific runner you want to lock or unlock. Make sure it's enabled. You cannot lock shared or group runners. 1. Click the pencil button. 1. Check the **Lock to current projects** option. 1. Click **Save changes**. diff --git a/doc/ci/secrets/index.md b/doc/ci/secrets/index.md index d3c34a6922e..898d310598f 100644 --- a/doc/ci/secrets/index.md +++ b/doc/ci/secrets/index.md @@ -95,7 +95,7 @@ To configure your Vault server: ## Use Vault secrets in a CI job **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4 and GitLab Runner 13.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28321) in GitLab 13.4 and GitLab Runner 13.4. After [configuring your Vault server](#configure-your-vault-server), you can use the secrets stored in Vault by defining them with the `vault` keyword: diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index 558f53a9535..5ac66846ab7 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Use GitLab as a microservice +# Use GitLab as a microservice **(FREE)** Many applications need to access JSON APIs, so application tests might need access to APIs too. The following example shows how to use GitLab as a microservice to give @@ -24,10 +24,9 @@ tests access to the GitLab API. GITLAB_ROOT_PASSWORD: "password" # to access the api with user root:password ``` -1. To set values for the `GITLAB_HTTPS` and `GITLAB_ROOT_PASSWORD`, - [assign them to a variable in the user interface](../variables/index.md#add-a-cicd-variable-to-a-project). - Then assign that variable to the corresponding variable in your - `.gitlab-ci.yml` file. +NOTE: +Variables set in the GitLab UI are not passed down to the service containers. +[Learn more](../variables/index.md#). Then, commands in `script:` sections in your `.gitlab-ci.yml` file can access the API at `http://gitlab/api/v4`. diff --git a/doc/ci/services/index.md b/doc/ci/services/index.md index c7891998a37..4114833d1c8 100644 --- a/doc/ci/services/index.md +++ b/doc/ci/services/index.md @@ -6,7 +6,7 @@ comments: false type: index --- -# Services +# Services **(FREE)** The `services` keyword defines a Docker image that runs during a `job` linked to the Docker image that the image keyword defines. This allows @@ -186,6 +186,34 @@ following these rules: To override the default behavior, you can [specify a service alias](#available-settings-for-services). +### Connecting services + +You can use inter-dependent services with complex jobs, like end-to-end tests where an +external API needs to communicate with its own database. + +For example, for an end-to-end test for a front-end application that uses an API, and where the API needs a database: + +```yaml +end-to-end-tests: + image: node:latest + services: + - name: selenium/standalone-firefox:${FIREFOX_VERSION} + alias: firefox + - name: registry.gitlab.com/organization/private-api:latest + alias: backend-api + - postgres:9.6.19 + variables: + FF_NETWORK_PER_BUILD: 1 + POSTGRES_PASSWORD: supersecretpassword + BACKEND_POSTGRES_HOST: postgres + script: + - npm install + - npm test +``` + +For this solution to work, you must use +[the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job). + ## Passing CI/CD variables to services You can also pass custom CI/CD [variables](../variables/index.md) @@ -311,6 +339,34 @@ services: The syntax of `command` is similar to [Dockerfile's `CMD`](https://docs.docker.com/engine/reference/builder/#cmd). +## Using `services` with `docker run` (Docker-in-Docker) side-by-side + +Containers started with `docker run` can also connect to services provided by GitLab. + +When booting the service is expensive or time consuming, you can use +this technique to run tests from different client environments, +while only booting up the tested service once. + +```yaml +access-service: + stage: build + image: docker:19.03.1 + services: + - docker:dind # necessary for docker run + - tutum/wordpress:latest + variables: + FF_NETWORK_PER_BUILD: "true" # activate container-to-container networking + script: | + docker run --rm --name curl \ + --volume "$(pwd)":"$(pwd)" \ + --workdir "$(pwd)" \ + --network=host \ + curlimages/curl:7.74.0 curl "http://tutum-wordpress" +``` + +For this solution to work, you must use +[the networking mode that creates a new network for each job](https://docs.gitlab.com/runner/executors/docker.html#create-a-network-for-each-job). + ## How Docker integration works Below is a high level overview of the steps performed by Docker during job diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index c691a6ef33d..d0ac123ba62 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using MySQL +# Using MySQL **(FREE)** Many applications depend on MySQL as their database, and you may need it for your tests to run. @@ -16,11 +16,9 @@ If you want to use a MySQL container, you can use [GitLab Runner](../runners/ind This example shows you how to set a username and password that GitLab uses to access the MySQL container. If you do not set a username and password, you must use `root`. -1. [Create CI/CD variables](../variables/index.md#custom-cicd-variables) for your - MySQL database and password by going to **Settings > CI/CD**, expanding **Variables**, - and clicking **Add Variable**. - - This example uses `$MYSQL_DB` and `$MYSQL_PASS` as the keys. +NOTE: +Variables set in the GitLab UI are not passed down to the service containers. +[Learn more](../variables/index.md). 1. To specify a MySQL image, add the following to your `.gitlab-ci.yml` file: @@ -39,8 +37,8 @@ This example shows you how to set a username and password that GitLab uses to ac ```yaml variables: # Configure mysql environment variables (https://hub.docker.com/_/mysql/) - MYSQL_DATABASE: $MYSQL_DB - MYSQL_ROOT_PASSWORD: $MYSQL_PASS + MYSQL_DATABASE: $MYSQL_DATABASE + MYSQL_ROOT_PASSWORD: $MYSQL_ROOT_PASSWORD ``` The MySQL container uses `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` to connect to the database. diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index 8d14e4795d2..62838e04969 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using PostgreSQL +# Using PostgreSQL **(FREE)** As many applications depend on PostgreSQL as their database, you eventually need it in order for your tests to run. Below you are guided how to @@ -16,6 +16,10 @@ do this with the Docker and Shell executors of GitLab Runner. If you're using [GitLab Runner](../runners/index.md) with the Docker executor, you basically have everything set up already. +NOTE: +Variables set in the GitLab UI are not passed down to the service containers. +[Learn more](../variables/index.md). + First, in your `.gitlab-ci.yml` add: ```yaml @@ -23,25 +27,19 @@ services: - postgres:12.2-alpine variables: - POSTGRES_DB: nice_marmot - POSTGRES_USER: runner - POSTGRES_PASSWORD: "" + POSTGRES_DB: $POSTGRES_DB + POSTGRES_USER: $POSTGRES_USER + POSTGRES_PASSWORD: $POSTGRES_PASSWORD POSTGRES_HOST_AUTH_METHOD: trust ``` -To set values for the `POSTGRES_DB`, `POSTGRES_USER`, -`POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD`, -[assign them to a CI/CD variable in the user interface](../variables/index.md#custom-cicd-variables), -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: ```yaml Host: postgres -User: runner -Password: '' -Database: nice_marmot +User: $PG_USER +Password: $PG_PASSWORD +Database: $PG_DB ``` If you're wondering why we used `postgres` for the `Host`, read more at diff --git a/doc/ci/services/redis.md b/doc/ci/services/redis.md index d8c7b805864..a3446fc2677 100644 --- a/doc/ci/services/redis.md +++ b/doc/ci/services/redis.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# Using Redis +# Using Redis **(FREE)** As many applications depend on Redis as their key-value store, you eventually need it in order for your tests to run. Below you are guided how to diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index 880473d402d..a2dd4ac91d5 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -14,8 +14,8 @@ tag) with an API call. The following methods of authentication are supported: -- [Trigger token](#trigger-token) -- [CI job token](#ci-job-token) +- Trigger tokens: A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). +- [CI job tokens](../jobs/ci_job_token.md). If using the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md) to limit which jobs run in a pipeline, the value could be either `pipeline` or `trigger`, @@ -28,71 +28,6 @@ depending on which trigger method is used. This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/index.md#only--except). -### Trigger token - -A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger). - -WARNING: -Passing plain text tokens in public projects is a security issue. Potential -attackers can impersonate the user that exposed their trigger token publicly in -their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/index.md) -to protect trigger tokens. - -### CI job token - -You can use the `CI_JOB_TOKEN` [CI/CD variable](../variables/index.md#predefined-cicd-variables) (used to authenticate -with the [GitLab Container Registry](../../user/packages/container_registry/index.md)) in the following cases. - -#### When used with multi-project pipelines - -> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2017) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.3. -> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [made available](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) in all tiers in GitLab 12.4. - -This way of triggering can only be used when invoked inside `.gitlab-ci.yml`, -and it creates a dependent pipeline relation visible on the -[pipeline graph](../pipelines/multi_project_pipelines.md). For example: - -```yaml -trigger_pipeline: - stage: deploy - script: - - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline" - rules: - - if: $CI_COMMIT_TAG -``` - -Pipelines triggered that way also expose a special variable: -`CI_PIPELINE_SOURCE=pipeline`. - -Read more about the [pipelines trigger API](../../api/pipeline_triggers.md). - -#### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)** - -> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.5. - -With the introduction of dependencies between different projects, one of -them may need to access artifacts created by a previous one. This process -must be granted for authorized accesses, and it can be done using the -`CI_JOB_TOKEN` variable that identifies a specific job. For example: - -```yaml -build_submodule: - image: debian - stage: test - script: - - apt update && apt install -y unzip - - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" - - unzip artifacts.zip - rules: - - if: $CI_COMMIT_TAG -``` - -This allows you to use that for multi-project pipelines and download artifacts -from any project to which you have access as this follows the same principles -with the [permission model](../../user/permissions.md#job-permissions). - -Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts-archive). - ## Adding a new trigger Go to your @@ -106,6 +41,12 @@ overview of the time the triggers were last used. ![Triggers page overview](img/triggers_page.png) +WARNING: +Passing plain text tokens in public projects is a security issue. Potential +attackers can impersonate the user that exposed their trigger token publicly in +their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/index.md) +to protect trigger tokens. + ## Revoking a trigger You can revoke a trigger any time by going at your project's diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index df9b20d1708..827a89fa99c 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -29,7 +29,7 @@ with your editor of choice. ### Verify syntax with CI Lint tool The [CI Lint tool](lint.md) is a simple way to ensure the syntax of a CI/CD configuration -file is correct. Paste in full `gitlab-ci.yml` files or individual jobs configuration, +file is correct. Paste in full `.gitlab-ci.yml` files or individual jobs configuration, to verify the basic syntax. When a `.gitlab-ci.yml` file is present in a project, you can also use the CI Lint @@ -49,7 +49,7 @@ and check if their values are what you expect. ## GitLab CI/CD documentation -The [complete `gitlab-ci.yml` reference](yaml/index.md) contains a full list of +The [complete `.gitlab-ci.yml` reference](yaml/index.md) contains a full list of every keyword you may need to use to configure your pipelines. You can also look at a large number of pipeline configuration [examples](examples/index.md) diff --git a/doc/ci/variables/index.md b/doc/ci/variables/index.md index a00b8b678ec..fa4bc6e39fb 100644 --- a/doc/ci/variables/index.md +++ b/doc/ci/variables/index.md @@ -20,6 +20,15 @@ You can use [predefined CI/CD variables](#predefined-cicd-variables) or define c - [Group CI/CD variables](#add-a-cicd-variable-to-a-group). - [Instance CI/CD variables](#add-a-cicd-variable-to-an-instance). +NOTE: +Variables set in the GitLab UI are **not** passed down to [service containers](../docker/using_docker_images.md). +To set them, assign them to variables in the UI, then re-assign them in your `.gitlab-ci.yml`: + +```yaml +variables: + SA_PASSWORD: $SA_PASSWORD +``` + > For more information about advanced use of GitLab CI/CD: > > -  Get to productivity faster with these [7 advanced GitLab CI workflow hacks](https://about.gitlab.com/webcast/7cicd-hacks/) @@ -116,7 +125,7 @@ Use the [`value` and `description`](../yaml/index.md#prefill-variables-in-manual keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) for [manually-triggered pipelines](../pipelines/index.md#run-a-pipeline-manually). -### Use variables or `$` in other variables +### Use variables in other variables You can use variables inside other variables: @@ -129,7 +138,9 @@ job: - 'eval "$LS_CMD"' # Executes 'ls -al' ``` -If you do not want the `$` interpreted as the start of a variable, use `$$` instead: +#### Use the `$` character in variables + +If you do not want the `$` character interpreted as the start of a variable, use `$$` instead: ```yaml job: @@ -228,7 +239,7 @@ You can define instance variables via the UI or [API](../../api/instance_level_c To add an instance variable: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Settings > CI/CD** and expand the **Variables** section. 1. Select the **Add variable** button, and fill in the details: @@ -295,6 +306,26 @@ echo "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem" kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem" ``` +#### Store multiple values in one variable + +It is not possible to create a CI/CD variable that is an array of values, but you +can use shell scripting techniques for similar behavior. + +For example, you can store multiple variables separated by a space in a variable, +then loop through the values with a script: + +```yaml +job1: + variables: + FOLDERS: src test docs + script: + - | + for FOLDER in $FOLDERS + do + echo "The path is root/${FOLDER}" + done +``` + ### Mask a CI/CD variable > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13784) in GitLab 11.10 diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index b5999a555c9..c8688d2433e 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -41,7 +41,8 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to the CI/CD configuration file. Defaults to `.gitlab-ci.yml`. Read-only inside a running pipeline. | | `CI_DEBUG_TRACE` | all | 1.7 | `true` if [debug logging (tracing)](index.md#debug-logging) is enabled. | | `CI_DEFAULT_BRANCH` | 12.4 | all | The name of the project's default branch. | -| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX` | 13.7 | all | The top-level group image prefix for pulling images through the Dependency Proxy. | +| `CI_DEPENDENCY_PROXY_DIRECT_GROUP_IMAGE_PREFIX` | 14.3 | all | The direct group image prefix for pulling images through the Dependency Proxy. | | `CI_DEPENDENCY_PROXY_PASSWORD` | 13.7 | all | The password to pull images through the Dependency Proxy. | | `CI_DEPENDENCY_PROXY_SERVER` | 13.7 | all | The server for logging in to the Dependency Proxy. This is equivalent to `$CI_SERVER_HOST:$CI_SERVER_PORT`. | | `CI_DEPENDENCY_PROXY_USER` | 13.7 | all | The username to pull images through the Dependency Proxy. | @@ -62,7 +63,7 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job. | | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the job's stage. | | `CI_JOB_STATUS` | all | 13.5 | The status of the job as each runner stage is executed. Use with [`after_script`](../yaml/index.md#after_script). Can be `success`, `failed`, or `canceled`. | -| `CI_JOB_TOKEN` | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../../api/index.md#gitlab-cicd-job-token). The token is valid as long as the job is running. | +| `CI_JOB_TOKEN` | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../jobs/ci_job_token.md). The token is valid as long as the job is running. | | `CI_JOB_URL` | 11.1 | 0.5 | The job details URL. | | `CI_JOB_STARTED_AT` | 13.10 | all | The UTC datetime when a job started, in [ISO 8601](https://tools.ietf.org/html/rfc3339#appendix-A) format. | | `CI_KUBERNETES_ACTIVE` | 13.0 | all | Only available if the pipeline has a Kubernetes cluster available for deployments. `true` when available. | @@ -82,7 +83,7 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_PROJECT_ID` | all | all | The ID of the current project. This ID is unique across all projects on the GitLab instance. | | `CI_PROJECT_NAME` | 8.10 | 0.5 | The name of the directory for the project. For example if the project URL is `gitlab.example.com/group-name/project-1`, `CI_PROJECT_NAME` is `project-1`. | | `CI_PROJECT_NAMESPACE` | 8.10 | 0.5 | The project namespace (username or group name) of the job. | -| `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-`. Use in URLs and domain names. | +| `CI_PROJECT_PATH_SLUG` | 9.3 | all | `$CI_PROJECT_PATH` in lowercase with characters that are not `a-z` or `0-9` replaced with `-` and shortened to 63 bytes. Use in URLs and domain names. | | `CI_PROJECT_PATH` | 8.10 | 0.5 | The project namespace with the project name included. | | `CI_PROJECT_REPOSITORY_LANGUAGES` | 12.3 | all | A comma-separated, lowercase list of the languages used in the repository. For example `ruby,javascript,html,css`. | | `CI_PROJECT_ROOT_NAMESPACE` | 13.2 | 0.5 | The root project namespace (username or group name) of the job. For example, if `CI_PROJECT_NAMESPACE` is `root-group/child-group/grandchild-group`, `CI_PROJECT_ROOT_NAMESPACE` is `root-group`. | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 8009687dbca..0f9339657fe 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -26,7 +26,7 @@ There are two places defined variables can be used. On the: |:-------------------------------------------|:-----------------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `environment:url` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab.

Supported are all variables defined for a job (project/group variables, variables from `.gitlab-ci.yml`, variables from triggers, variables from pipeline schedules).

Not supported are variables defined in the GitLab Runner `config.toml` and variables created in the job's `script`. | | `environment:name` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:

- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).
- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).
- [Persisted variables](#persisted-variables). | -| `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:

- Variables that are based on the environment's name (`CI_ENVIRONMENT_NAME`, `CI_ENVIRONMENT_SLUG`).
- Any other variables related to environment (currently only `CI_ENVIRONMENT_URL`).
- [Persisted variables](#persisted-variables). | +| `resource_group` | yes | GitLab | Similar to `environment:url`, but the variables expansion doesn't support the following:
- `CI_ENVIRONMENT_URL`
- [Persisted variables](#persisted-variables) | | `include` | yes | GitLab | The variable expansion is made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab.

Predefined project variables are supported: `GITLAB_FEATURES`, `CI_DEFAULT_BRANCH`, and all variables that start with `CI_PROJECT_` (for example `CI_PROJECT_NAME`). | | `variables` | yes | GitLab/Runner | The variable expansion is first made by the [internal variable expansion mechanism](#gitlab-internal-variable-expansion-mechanism) in GitLab, and then any unrecognized or unavailable variables are expanded by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism). | | `image` | yes | Runner | The variable expansion is made by GitLab Runner's [internal variable expansion mechanism](#gitlab-runner-internal-variable-expansion-mechanism) | @@ -63,11 +63,11 @@ because the expansion is done in GitLab before any runner gets the job. #### Nested variable expansion -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48627) in GitLab 13.10. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It can be enabled or disabled for a single project. -> - It's disabled on GitLab.com. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-nested-variable-expansion-feature). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/48627) in GitLab 13.10. [Deployed behind the `variable_inside_variable` feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/297382) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is disabled. To enable the feature per project or for your entire instance, ask an administrator to [enable the `variable_inside_variable` flag](../../administration/feature_flags.md). GitLab expands job variable values recursively before sending them to the runner. For example: @@ -86,29 +86,6 @@ References to unavailable variables are left intact. In this case, the runner [attempts to expand the variable value](#gitlab-runner-internal-variable-expansion-mechanism) at runtime. For example, a variable like `CI_BUILDS_DIR` is known by the runner only at runtime. -##### Enabling the nested variable expansion feature **(FREE SELF)** - -This feature comes with the `:variable_inside_variable` feature flag disabled by default. - -To enable this feature, ask a GitLab administrator with [Rails console access](../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the -following command: - -```ruby -# For the instance -Feature.enable(:variable_inside_variable) -# For a single project -Feature.enable(:variable_inside_variable, Project.find()) -``` - -To disable it: - -```ruby -# For the instance -Feature.disable(:variable_inside_variable) -# For a single project -Feature.disable(:variable_inside_variable, Project.find()) -``` - ### GitLab Runner internal variable expansion mechanism - Supported: project/group variables, `.gitlab-ci.yml` variables, `config.toml` variables, and diff --git a/doc/ci/yaml/gitlab_ci_yaml.md b/doc/ci/yaml/gitlab_ci_yaml.md index 6cd900123e0..ea05aa45b0b 100644 --- a/doc/ci/yaml/gitlab_ci_yaml.md +++ b/doc/ci/yaml/gitlab_ci_yaml.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers type: reference --- diff --git a/doc/ci/yaml/includes.md b/doc/ci/yaml/includes.md index 673a4e75c35..92bf44cca7f 100644 --- a/doc/ci/yaml/includes.md +++ b/doc/ci/yaml/includes.md @@ -1,76 +1,81 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- # GitLab CI/CD include examples **(FREE)** -In addition to the [`includes` examples](index.md#include) listed in the -[GitLab CI YAML reference](index.md), this page lists more variations of `include` -usage. +You can use [`include`](index.md#include) to include external YAML files in your CI/CD jobs. -## Single string or array of multiple values +## Include a single configuration file -You can include your extra YAML file(s) either as a single string or -an array of multiple values. The following examples are all valid. +To include a single configuration file, use either of these syntax options: -Single string with the `include:local` method implied: +- `include` by itself with a single file, which is the same as + [`include:local`](index.md#includelocal): -```yaml -include: '/templates/.after-script-template.yml' -``` + ```yaml + include: '/templates/.after-script-template.yml' + ``` -Array with `include` method implied: +- `include` with a single file, and you specify the `include` type: -```yaml -include: - - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' - - '/templates/.after-script-template.yml' -``` + ```yaml + include: + remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + ``` -Single string with `include` method specified explicitly: +## Include an array of configuration files -```yaml -include: - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' -``` +You can include an array of configuration files: -Array with `include:remote` being the single item: +- If you do not specify an `include` type, the type defaults to [`include:local`](index.md#includelocal): -```yaml -include: - - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' -``` + ```yaml + include: + - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + - '/templates/.after-script-template.yml' + ``` -Array with multiple `include` methods specified explicitly: +- You can define a single item array: -```yaml -include: - - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' - - local: '/templates/.after-script-template.yml' - - template: Auto-DevOps.gitlab-ci.yml -``` + ```yaml + include: + - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + ``` -Array mixed syntax: +- You can define an array and explicitly specify multiple `include` types: -```yaml -include: - - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' - - '/templates/.after-script-template.yml' - - template: Auto-DevOps.gitlab-ci.yml - - project: 'my-group/my-project' - ref: main - file: '/templates/.gitlab-ci-template.yml' -``` + ```yaml + include: + - remote: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + - local: '/templates/.after-script-template.yml' + - template: Auto-DevOps.gitlab-ci.yml + ``` + +- You can define an array that combines both default and specific `include` type: + + ```yaml + include: + - 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' + - '/templates/.after-script-template.yml' + - template: Auto-DevOps.gitlab-ci.yml + - project: 'my-group/my-project' + ref: main + file: '/templates/.gitlab-ci-template.yml' + ``` -## Re-using a `before_script` template +## Use `default` configuration from an included configuration file -In the following example, the content of `.before-script-template.yml` is -automatically fetched and evaluated along with the content of `.gitlab-ci.yml`. +You can define a [`default`](index.md#custom-default-keyword-values) section in a +configuration file. When you use a `default` section with the `include` keyword, the defaults apply to +all jobs in the pipeline. -Content of `https://gitlab.com/awesome-project/raw/main/.before-script-template.yml`: +For example, you can use a `default` section with [`before_script`](index.md#before_script). + +Content of a custom configuration file named `/templates/.before-script-template.yml`: ```yaml default: @@ -83,19 +88,29 @@ default: Content of `.gitlab-ci.yml`: ```yaml -include: 'https://gitlab.com/awesome-project/raw/main/.before-script-template.yml' +include: '/templates/.before-script-template.yml' -rspec: +rspec1: + script: + - bundle exec rspec + +rspec2: script: - bundle exec rspec ``` -## Overriding external template values +The default `before_script` commands execute in both `rspec` jobs, before the `script` commands. + +## Override included configuration values -The following example shows specific YAML-defined variables and details of the -`production` job from an include file being customized in `.gitlab-ci.yml`. +When you use the `include` keyword, you can override the included configuration values to adapt them +to your pipeline requirements. -Content of `https://company.com/autodevops-template.yml`: +The following example shows an `include` file that is customized in the +`.gitlab-ci.yml` file. Specific YAML-defined variables and details of the +`production` job are overridden. + +Content of a custom configuration file named `autodevops-template.yml`: ```yaml variables: @@ -136,17 +151,18 @@ production: url: https://domain.com ``` -In this case, the variables `POSTGRES_USER` and `POSTGRES_PASSWORD` along -with the environment URL of the `production` job defined in -`autodevops-template.yml` have been overridden by new values defined in -`.gitlab-ci.yml`. +The `POSTGRES_USER` and `POSTGRES_PASSWORD` variables +and the `environment:url` of the `production` job defined in the `.gitlab-ci.yml` file +override the values defined in the `autodevops-template.yml` file. The other keywords +do not change. This method is called *merging*. + +## Override included configuration arrays -The merging lets you extend and override dictionary mappings, but -you cannot add or modify items to an included array. For example, to add -an additional item to the production job script, you must repeat the -existing script items: +You can use merging to extend and override configuration in an included template, but +you cannot add or modify individual items in an array. For example, to add +an additional `notify_owner` command to the extended `production` job's `script` array: -Content of `https://company.com/autodevops-template.yml`: +Content of `autodevops-template.yml`: ```yaml production: @@ -159,7 +175,7 @@ production: Content of `.gitlab-ci.yml`: ```yaml -include: 'https://company.com/autodevops-template.yml' +include: 'autodevops-template.yml' stages: - production @@ -171,51 +187,32 @@ production: - notify_owner ``` -In this case, if `install_dependencies` and `deploy` were not repeated in -`.gitlab-ci.yml`, they would not be part of the script for the `production` -job in the combined CI configuration. +If `install_dependencies` and `deploy` are not repeated in +the `.gitlab-ci.yml` file, the `production` job would have only `notify_owner` in the script. -## Using nested includes +## Use nested includes -The examples below show how includes can be nested from different sources -using a combination of different methods. +You can nest `include` sections in configuration files that are then included +in another configuration. For example, for `include` keywords nested three deep: -In this example, `.gitlab-ci.yml` includes local the file `/.gitlab-ci/another-config.yml`: +Content of `.gitlab-ci.yml`: ```yaml include: - local: /.gitlab-ci/another-config.yml ``` -The `/.gitlab-ci/another-config.yml` includes a template and the `/templates/docker-workflow.yml` file -from another project: +Content of `/.gitlab-ci/another-config.yml`: ```yaml include: - - template: Bash.gitlab-ci.yml - - project: group/my-project - file: /templates/docker-workflow.yml + - local: /.gitlab-ci/config-defaults.yml ``` -The `/templates/docker-workflow.yml` present in `group/my-project` includes two local files -of the `group/my-project`: +Content of `/.gitlab-ci/config-defaults.yml`: ```yaml -include: - - local: /templates/docker-build.yml - - local: /templates/docker-testing.yml -``` - -Our `/templates/docker-build.yml` present in `group/my-project` adds a `docker-build` job: - -```yaml -docker-build: - script: docker build -t my-image . -``` - -Our second `/templates/docker-test.yml` present in `group/my-project` adds a `docker-test` job: - -```yaml -docker-test: - script: docker run my-image /run/tests.sh +default: + after_script: + - echo "Job complete." ``` diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 63f626e524e..fb5748788f7 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -1,15 +1,11 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- - - -# Keyword reference for the .gitlab-ci.yml file **(FREE)** - - +# Keyword reference for the `.gitlab-ci.yml` file **(FREE)** This document lists the configuration options for your GitLab `.gitlab-ci.yml` file. @@ -331,7 +327,7 @@ include: #### Switch between branch pipelines and merge request pipelines -> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) GitLab 13.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) in GitLab 13.8. To make the pipeline switch from branch pipelines to merge request pipelines after a merge request is created, add a `workflow: rules` section to your `.gitlab-ci.yml` file. @@ -386,7 +382,7 @@ does not block triggered pipelines. > [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Free in 11.4. Use `include` to include external YAML files in your CI/CD configuration. -You can break down one long `gitlab-ci.yml` file into multiple files to increase readability, +You can break down one long `.gitlab-ci.yml` file into multiple files to increase readability, or reduce duplication of the same configuration in multiple places. You can also store template files in a central repository and `include` them in projects. @@ -434,7 +430,7 @@ In `include` sections in your `.gitlab-ci.yml` file, you can use: - [Project variables](../variables/index.md#add-a-cicd-variable-to-a-project) - [Group variables](../variables/index.md#add-a-cicd-variable-to-a-group) - [Instance variables](../variables/index.md#add-a-cicd-variable-to-an-instance) -- Project [predefined variables](../variables/predefined_variables.md). +- Project [predefined variables](../variables/predefined_variables.md). ```yaml include: @@ -450,12 +446,12 @@ that proposes expanding this feature to support more variables. #### `rules` with `include` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276515) in GitLab 14.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276515) in GitLab 14.2. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3 and is ready for production use. +> - [Enabled with `ci_include_rules` flag](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) for self-managed GitLab in GitLab 14.3 and is ready for production use. -NOTE: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the `ci_include_rules` flag](../../administration/feature_flags.md). -On GitLab.com, this feature is not available. The feature is not ready for production use. +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the `ci_include_rules` flag](../../administration/feature_flags.md). On GitLab.com, this feature is available. You can use [`rules`](#rules) with `include` to conditionally include other configuration files. You can only use `rules:if` in `include` with [certain variables](#variables-with-include). @@ -626,7 +622,7 @@ Use nested includes to compose a set of includes. You can have up to 100 includes, but you can't have duplicate includes. -In [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/28212) and later, the time limit +In [GitLab 12.4 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/28212), the time limit to resolve all files is 30 seconds. #### Additional `includes` examples @@ -1141,6 +1137,9 @@ The job is not added to the pipeline: - If no rules match. - If a rule matches and has `when: never`. +You can use [`!reference` tags](#reference-tags) to [reuse `rules` configuration](../jobs/job_control.md#reuse-rules-in-different-jobs) +in different jobs. + #### `rules:if` Use `rules:if` clauses to specify when to add a job to a pipeline: @@ -1368,7 +1367,7 @@ pipeline based on branch names or pipeline types. | `pushes` | For pipelines triggered by a `git push` event, including for branches and tags. | | `schedules` | For [scheduled pipelines](../pipelines/schedules.md). | | `tags` | When the Git reference for a pipeline is a tag. | - | `triggers` | For pipelines created by using a [trigger token](../triggers/index.md#trigger-token). | + | `triggers` | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). | | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | **Example of `only:refs` and `except:refs`**: @@ -1591,27 +1590,23 @@ production: #### Requirements and limitations -- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you - can refer to jobs in the same stage as the job you are configuring. This feature is - enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) - this feature is available by default. To hide the feature, ask an administrator to - [disable the `ci_same_stage_job_needs` flag](../../administration/feature_flags.md). -- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. -- In GitLab 13.9 and older, if `needs:` refers to a job that might not be added to - a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. - 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). + - For self-managed instances, the default limit is 50. This limit [can be changed](#changing-the-needs-job-limit). - If `needs:` refers to a job that uses the [`parallel`](#parallel) keyword, it depends on all jobs created in parallel, not just one job. It also downloads artifacts from all the parallel jobs by default. If the artifacts have the same name, they overwrite each other and only the last one downloaded is saved. -- `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 [an issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/30632). -- Stages must be explicitly defined for all jobs - that have the keyword `needs:` or are referred to by one. +- In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) you + can refer to jobs in the same stage as the job you are configuring. This feature is + enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) + this feature is available by default. +- In GitLab 14.0 and older, you can only refer to jobs in earlier stages. Stages must be + explicitly defined for all jobs that use the `needs:` keyword, or are referenced + in a job's `needs:` section. +- In GitLab 13.9 and older, if `needs:` refers to a job that might not be added to + a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. ##### Changing the `needs:` job limit **(FREE SELF)** @@ -1628,7 +1623,7 @@ To disable directed acyclic graphs (DAG), set the limit to `0`. #### Artifact downloads with `needs` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.6. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.6. When a job uses `needs`, it no longer downloads all artifacts from previous stages by default, because jobs with `needs` can start before earlier stages complete. With @@ -1680,7 +1675,7 @@ with `needs`. #### Cross project artifact downloads with `needs` **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab v12.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14311) in GitLab 12.7. Use `needs` to download artifacts from up to five jobs in pipelines: @@ -1753,7 +1748,7 @@ pipelines running on the same ref could override the artifacts. #### Artifact downloads to child pipelines -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab v13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/255983) in GitLab 13.7. A [child pipeline](../pipelines/parent_child_pipelines.md) can download artifacts from a job in its parent pipeline or another child pipeline in the same parent-child pipeline hierarchy. @@ -1832,14 +1827,25 @@ rspec: ### `tags` +> - A limit of 50 tags per job [enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/338929) in GitLab 14.3. +> - A limit of 50 tags per job [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/339855) in GitLab 14.3. + Use `tags` to select a specific runner from the list of all runners that are available for the project. When you register a runner, you can specify the runner's tags, for -example `ruby`, `postgres`, `development`. +example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner must +be assigned every tag listed in the job. + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default:` section](#custom-default-keyword-values). + +**Possible inputs**: -In the following example, the job is run by a runner that -has both `ruby` and `postgres` tags defined. +- An array of tag names. +- [CI/CD variables](../runners/configure_runners.md#use-cicd-variables-in-tags) in GitLab 14.1 and later. + +**Example of `tags`**: ```yaml job: @@ -1848,75 +1854,56 @@ job: - postgres ``` -You can use tags to run different jobs on different platforms. For -example, if you have an OS X runner with tag `osx` and a Windows runner with tag -`windows`, you can run a job on each platform: +In this example, only runners with *both* the `ruby` and `postgres` tags can run the job. -```yaml -windows job: - stage: - - build - tags: - - windows - script: - - echo Hello, %USERNAME%! +**Additional details**: -osx job: - stage: - - build - tags: - - osx - script: - - echo "Hello, $USER!" -``` +- In [GitLab 14.3](https://gitlab.com/gitlab-org/gitlab/-/issues/338479) and later, + the number of tags must be less than `50`. -In [GitLab 14.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/35742), you can -use [CI/CD variables](../variables/index.md) with `tags` for dynamic runner selection: +**Related topics**: -```yaml -variables: - KUBERNETES_RUNNER: kubernetes - - job: - tags: - - docker - - $KUBERNETES_RUNNER - script: - - echo "Hello runner selector feature" -``` +- [Use tags to control which jobs a runner can run](../runners/configure_runners.md#use-tags-to-control-which-jobs-a-runner-can-run). ### `allow_failure` -Use `allow_failure` when you want to let a job fail without impacting the rest of the CI -suite. The default value is `false`, except for [manual](../jobs/job_control.md#create-a-job-that-must-be-run-manually) jobs that use -the [`when: manual`](#when) syntax. +Use `allow_failure` to determine whether a pipeline should continue running when a job fails. + +- To let the pipeline continue running subsequent jobs, use `allow_failure: true`. +- To stop the pipeline from running subsequent jobs, use `allow_failure: false`. -In jobs that use [`rules:`](#rules), all jobs default to `allow_failure: false`, -*including* `when: manual` jobs. +When jobs are allowed to fail (`allow_failure: true`) an orange warning (**{status_warning}**) +indicates that a job failed. However, the pipeline is successful and the associated commit +is marked as passed with no warnings. -When `allow_failure` is set to `true` and the job fails, the job shows an orange warning in the UI. -However, the logical flow of the pipeline considers the job a -success/passed, and is not blocked. +This same warning is displayed when: -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. +- All other jobs in the stage are successful. +- All other jobs in the pipeline are successful. -In the following example, `job1` and `job2` run in parallel. If `job1` -fails, it doesn't stop the next stage from running, because it's marked with -`allow_failure: true`: +The default value for `allow_failure` is: + +- `true` for [manual jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually). +- `false` for manual jobs that also use [`rules`](#rules). +- `false` in all other cases. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: `true` or `false`. + +**Example of `allow_failure`**: ```yaml job1: stage: test script: - - execute_script_that_will_fail - allow_failure: true + - execute_script_1 job2: stage: test script: - - execute_script_that_will_succeed + - execute_script_2 + allow_failure: true job3: stage: deploy @@ -1924,14 +1911,35 @@ job3: - deploy_to_staging ``` +In this example, `job1` and `job2` run in parallel: + +- If `job1` fails, jobs in the `deploy` stage do not start. +- If `job2` fails, jobs in the `deploy` stage can still start. + +**Additional details**: + +- You can use `allow_failure` as a subkey of [`rules:`](#rulesallow_failure). +- You can use `allow_failure: false` with a manual job to create a [blocking manual job](../jobs/job_control.md#types-of-manual-jobs). + A blocked pipeline does not run any jobs in later stages until the manual job + is started and completes successfully. + #### `allow_failure:exit_codes` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273157) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/292024) in GitLab 13.9. -Use `allow_failure:exit_codes` to dynamically control if a job should be allowed -to fail. You can list which exit codes are not considered failures. The job fails -for any other exit code: +Use `allow_failure:exit_codes` to control when a job should be +allowed to fail. The job is `allow_failure: true` for any of the listed exit codes, +and `allow_failure` false for any other exit code. + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: + +- A single exit code. +- An array of exit codes. + +**Example of `allow_failure`**: ```yaml test_job_1: @@ -2017,7 +2025,7 @@ In this example, the script: **Additional details**: -- In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you +- In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), 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`. - The default behavior of `allow_failure` changes to `true` with `when: manual`. @@ -2136,7 +2144,7 @@ review_app: stage: deploy script: make deploy-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review_app @@ -2147,7 +2155,7 @@ stop_review_app: script: make delete-app when: manual environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG action: stop ``` @@ -2197,7 +2205,7 @@ For example, review_app: script: deploy-review-app environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG auto_stop_in: 1 day ``` @@ -2267,12 +2275,12 @@ deploy as review app: stage: deploy script: make deploy environment: - name: review/$CI_COMMIT_REF_NAME + name: review/$CI_COMMIT_REF_SLUG url: https://$CI_ENVIRONMENT_SLUG.example.com/ ``` The `deploy as review app` job is marked as a deployment to dynamically -create the `review/$CI_COMMIT_REF_NAME` environment. `$CI_COMMIT_REF_NAME` +create the `review/$CI_COMMIT_REF_SLUG` environment. `$CI_COMMIT_REF_SLUG` is a [CI/CD variable](../variables/index.md) set by the runner. The `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable for inclusion in URLs. If the `deploy as review app` job runs in a branch named @@ -2301,7 +2309,7 @@ Use the `cache:paths` keyword to choose which files or directories to cache. You can use wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns: -- In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, +- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620), [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). - In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match). @@ -2377,7 +2385,7 @@ cache-job: ##### `cache:key:files` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. Use the `cache:key:files` keyword to generate a new key when one or two specific files change. `cache:key:files` lets you reuse some caches, and rebuild them less often, @@ -2415,7 +2423,7 @@ fallback key is `default`. ##### `cache:key:prefix` -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab v12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18986) in GitLab 12.5. Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles). @@ -2864,7 +2872,7 @@ Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't direct link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and: -- In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, +- In [GitLab Runner 13.0 and later](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620), [`doublestar.Glob`](https://pkg.go.dev/github.com/bmatcuk/doublestar@v1.2.2?tab=doc#Match). - In GitLab Runner 12.10 and earlier, [`filepath.Match`](https://pkg.go.dev/path/filepath#Match). @@ -3120,7 +3128,7 @@ dashboards. ##### `artifacts:reports:load_performance` **(PREMIUM)** -> - Introduced in [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35260) in GitLab 13.2. > - Requires GitLab Runner 11.5 and above. The `load_performance` report collects [Load Performance Testing metrics](../../user/project/merge_requests/load_performance_testing.md) @@ -3163,7 +3171,7 @@ marked as Satisfied. ##### `artifacts:reports:sast` > - Introduced in GitLab 11.5. -> - Made [available in all tiers](https://gitlab.com/groups/gitlab-org/-/epics/2098) in GitLab 13.3. +> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. > - Requires GitLab Runner 11.5 and above. The `sast` report collects [SAST vulnerabilities](../../user/application_security/sast/index.md) @@ -3176,8 +3184,7 @@ dashboards. ##### `artifacts:reports:secret_detection` > - Introduced in GitLab 13.1. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) in GitLab - 13.3. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) to GitLab Free in 13.3. > - Requires GitLab Runner 11.5 and above. The `secret-detection` report collects [detected secrets](../../user/application_security/secret_detection/index.md) @@ -3192,10 +3199,10 @@ dashboards. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207528) in GitLab 13.0. > - Requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 and above. -The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/mr_integration.md#configure-terraform-report-artifacts). The collected Terraform +The `terraform` report obtains a Terraform `tfplan.json` file. [JQ processing required to remove credentials](../../user/infrastructure/iac/mr_integration.md#configure-terraform-report-artifacts). The collected Terraform plan report uploads to GitLab as an artifact and displays in merge requests. For more information, see -[Output `terraform plan` information into a merge request](../../user/infrastructure/mr_integration.md). +[Output `terraform plan` information into a merge request](../../user/infrastructure/iac/mr_integration.md). #### `artifacts:untracked` @@ -3404,7 +3411,22 @@ You can specify the number of [retry attempts for certain stages of job executio > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14887) in GitLab 12.3. -Use `timeout` to configure a timeout for a specific job. For example: +Use `timeout` to configure a timeout for a specific job. If the job runs for longer +than the timeout, the job fails. + +The job-level timeout can be longer than the [project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run). +but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). + +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default:` section](#custom-default-keyword-values). + +**Possible inputs**: A period of time written in natural language. For example, these are all equivalent: + +- `3600 seconds` +- `60 minutes` +- `one hour` + +**Example of `timeout`**: ```yaml build: @@ -3416,10 +3438,6 @@ test: timeout: 3h 30m ``` -The job-level timeout can exceed the -[project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) but can't -exceed the runner-specific timeout. - ### `parallel` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5. @@ -3583,7 +3601,7 @@ deploystacks: ### `trigger` -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8997) in GitLab Premium 11.8. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/199224) to GitLab Free in 12.8. Use `trigger` to define a downstream pipeline trigger. When GitLab starts a `trigger` job, @@ -3598,11 +3616,11 @@ You can use this keyword to create two different types of downstream pipelines: - [Multi-project pipelines](../pipelines/multi_project_pipelines.md#define-multi-project-pipelines-in-your-gitlab-ciyml-file) - [Child pipelines](../pipelines/parent_child_pipelines.md) -[In GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/) and later, you can +In [GitLab 13.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/), you can view which job triggered a downstream pipeline. In the [pipeline graph](../pipelines/index.md#visualize-pipelines), hover over the downstream pipeline job. -In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/201938) and later, you +In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201938), you can use [`when:manual`](#when) 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`. You [cannot start `manual` trigger jobs with the API](https://gitlab.com/gitlab-org/gitlab/-/issues/284086). @@ -3756,25 +3774,19 @@ The trigger token is different than the [`trigger`](#trigger) keyword. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. -Use `interruptible` to indicate that a running job should be canceled if made redundant by a newer pipeline run. -Defaults to `false` (uninterruptible). Jobs that have not started yet (pending) are considered interruptible -and safe to be cancelled. -This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-redundant-pipelines) -is enabled. - -When enabled, a pipeline is immediately canceled when a new pipeline starts on the same branch if either of the following is true: +Use `interruptible` if a job should be canceled when a newer pipeline starts before the job completes. -- All jobs in the pipeline are set as interruptible. -- Any uninterruptible jobs have not started yet. +This keyword is used with the [automatic cancellation of redundant pipelines](../pipelines/settings.md#auto-cancel-redundant-pipelines) +feature. When enabled, a running job with `interruptible: true` can be cancelled when +a new pipeline starts on the same branch. -Set jobs as interruptible that can be safely canceled once started (for instance, a build job). +You can't cancel subsequent jobs after a job with `interruptible: false` starts. -In the following example, a new pipeline run causes an existing running pipeline to be: +**Keyword type**: Job keyword. You can use it only as part of a job. -- Canceled, if only `step-1` is running or pending. -- Not canceled, once `step-2` starts running. +**Possible inputs**: `true` or `false` (default). -After an uninterruptible job starts running, the pipeline cannot be canceled. +**Example of `interruptible`**: ```yaml stages: @@ -3800,15 +3812,27 @@ step-3: interruptible: true ``` +In this example, a new pipeline causes a running pipeline to be: + +- Canceled, if only `step-1` is running or pending. +- Not canceled, after `step-2` starts. + +**Additional details**: + +- Only set `interruptible: true` if the job can be safely canceled after it has started, + like a build job. Deployment jobs usually shouldn't be cancelled, to prevent partial deployments. +- To completely cancel a running pipeline, all jobs must have `interruptible: true`, + or `interruptible: false` jobs must not have started. + ### `resource_group` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7. -Sometimes running multiple jobs or pipelines at the same time in an environment +Sometimes running multiple jobs at the same time in an environment can lead to errors during the deployment. To avoid these errors, use the `resource_group` attribute to make sure that -the runner doesn't run certain jobs simultaneously. Resource groups behave similar +the runner doesn't run certain jobs concurrently. Resource groups behave similar to semaphores in other programming languages. When the `resource_group` keyword is defined for a job in the `.gitlab-ci.yml` file, @@ -4333,15 +4357,12 @@ name level and not in the `vault` section. ### `pages` -Use `pages` to upload static content to GitLab. The content -is then published as a website. You must: +Use `pages` to define a [GitLab Pages](../../user/project/pages/index.md) job that +uploads static content to GitLab. The content is then published as a website. -- Place any static content in a `public/` directory. -- Define [`artifacts`](#artifacts) with a path to the `public/` directory. +**Keyword type**: Job name. -The following example moves all files from the root of the project to the -`public/` directory. The `.public` workaround is so `cp` does not also copy -`public/` to itself in an infinite loop: +**Example of `pages`**: ```yaml pages: @@ -4357,7 +4378,15 @@ pages: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` -View the [GitLab Pages user documentation](../../user/project/pages/index.md). +This example moves all files from the root of the project to the `public/` directory. +The `.public` workaround is so `cp` does not also copy `public/` to itself in an infinite loop. + +**Additional details**: + +You must: + +- Place any static content in a `public/` directory. +- Define [`artifacts`](#artifacts) with a path to the `public/` directory. ### `inherit` @@ -4481,7 +4510,7 @@ deploy_review_job: You can use only integers and strings for the variable's name and value. -If you define a variable at the top level of the `gitlab-ci.yml` file, it is global, +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 in a job, it's available to that job only. @@ -4495,7 +4524,7 @@ You can use [YAML anchors for variables](#yaml-anchors-for-variables). ### Prefill variables in manual pipelines -> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) in GitLab 13.7. Use the `value` and `description` keywords to define [pipeline-level (global) variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines) when [running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually): @@ -4763,6 +4792,7 @@ into templates. ### `!reference` tags > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/266173) in GitLab 13.9. +> - `rules` keyword support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322992) in GitLab 14.3. Use the `!reference` custom YAML tag to select keyword configuration from other job sections and reuse it in the current section. Unlike [YAML anchors](#anchors), you can diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index 93c1a6afe69..626ede21fa5 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- diff --git a/doc/development/adding_service_component.md b/doc/development/adding_service_component.md index 503d1b7e55b..f5acf0d26eb 100644 --- a/doc/development/adding_service_component.md +++ b/doc/development/adding_service_component.md @@ -47,8 +47,7 @@ Adding a new service follows the same [merge request workflow](contributing/merg The first iteration should be to add the ability to connect and use the service as an externally installed component. Often this involves providing settings in GitLab to connect to the service, or allow connections from it. And then shipping documentation on how to install and configure the service with GitLab. -NOTE: -[Elasticsearch](../integration/elasticsearch.md#installing-elasticsearch) is an example of a service that has been integrated this way. And many of the other services, including internal projects like Gitaly, started off as separately installed alternatives. +[Elasticsearch](../integration/elasticsearch.md#install-elasticsearch) is an example of a service that has been integrated this way. Many of the other services, including internal projects like Gitaly, started off as separately installed alternatives. **For services that depend on the existing GitLab codebase:** diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 40cc8f5ec45..9a17ac4c813 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -532,7 +532,7 @@ Example: ```ruby field :foo, GraphQL::Types::String, null: true, - description: 'Some test field. Will always return `null`' \ + description: 'Some test field. Returns `null`' \ 'if `my_feature_flag` feature flag is disabled.' def foo @@ -940,7 +940,9 @@ class PostResolver < BaseResolver end ``` -You should never re-use resolvers directly. Resolvers have a complex life-cycle, with +While you can use the same resolver class in two different places, +such as in two different fields where the same object is exposed, +you should never re-use resolver objects directly. Resolvers have a complex life-cycle, with authorization, readiness and resolution orchestrated by the framework, and at each stage [lazy values](#laziness) can be returned to take advantage of batching opportunities. Never instantiate a resolver or a mutation in application code. diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md index b606cda1124..2075e7cda3c 100644 --- a/doc/development/application_limits.md +++ b/doc/development/application_limits.md @@ -40,9 +40,7 @@ It's recommended to create two separate migration script files. desired limit using `create_or_update_plan_limit` migration helper, such as: ```ruby - class InsertProjectHooksPlanLimits < ActiveRecord::Migration[5.2] - include Gitlab::Database::MigrationHelpers - + class InsertProjectHooksPlanLimits < Gitlab::Database::Migration[1.0] def up create_or_update_plan_limit('project_hooks', 'default', 0) create_or_update_plan_limit('project_hooks', 'free', 10) diff --git a/doc/development/architecture.md b/doc/development/architecture.md index a487e84d090..fe2b621da29 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -603,14 +603,14 @@ 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 GitLab 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 bundle our own Logrotate +to make sure we were logging responsibly. This is just a packaged version of the common open source offering. #### Mattermost - [Project page](https://github.com/mattermost/mattermost-server/blob/master/README.md) - Configuration: - - [Omnibus](https://docs.gitlab.com/omnibus/gitlab-mattermost/) + - [Omnibus](../integration/mattermost/index.md) - [Charts](https://docs.mattermost.com/install/install-mmte-helm-gitlab-helm.html) - Layer: Core Service (Processor) - GitLab.com: [Mattermost](../user/project/integrations/mattermost.md) diff --git a/doc/development/avoiding_downtime_in_migrations.md b/doc/development/avoiding_downtime_in_migrations.md index b844415c94e..9418eafa487 100644 --- a/doc/development/avoiding_downtime_in_migrations.md +++ b/doc/development/avoiding_downtime_in_migrations.md @@ -95,9 +95,7 @@ renaming. For example ```ruby # A regular migration in db/migrate -class RenameUsersUpdatedAtToUpdatedAtTimestamp < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class RenameUsersUpdatedAtToUpdatedAtTimestamp < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -125,9 +123,7 @@ We can perform this cleanup using ```ruby # A post-deployment migration in db/post_migrate -class CleanupUsersUpdatedAtRename < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class CleanupUsersUpdatedAtRename < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -174,9 +170,7 @@ as follows: ```ruby # A regular migration in db/migrate -class ChangeUsersUsernameStringToText < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class ChangeUsersUsernameStringToText < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -195,9 +189,7 @@ Next we need to clean up our changes using a post-deployment migration: ```ruby # A post-deployment migration in db/post_migrate -class ChangeUsersUsernameStringToTextCleanup < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class ChangeUsersUsernameStringToTextCleanup < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -245,9 +237,7 @@ the work / load over a longer time period, without slowing down deployments. For example, to change the column type using a background migration: ```ruby -class ExampleMigration < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class ExampleMigration < Gitlab::Database::Migration[1.0] disable_ddl_transaction! class Issue < ActiveRecord::Base @@ -289,9 +279,7 @@ release) by a cleanup migration, which should steal from the queue and handle any remaining rows. For example: ```ruby -class MigrateRemainingIssuesClosedAt < ActiveRecord::Migration[4.2] - include Gitlab::Database::MigrationHelpers - +class MigrateRemainingIssuesClosedAt < Gitlab::Database::Migration[1.0] disable_ddl_transaction! class Issue < ActiveRecord::Base diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index 695c565ca83..c93b5b448f0 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -254,7 +254,7 @@ existing data. Since we're dealing with a lot of rows we'll schedule jobs in batches instead of doing this one by one: ```ruby -class ScheduleExtractServicesUrl < ActiveRecord::Migration[4.2] +class ScheduleExtractServicesUrl < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -281,7 +281,7 @@ jobs and manually run on any un-migrated rows. Such a migration would look like this: ```ruby -class ConsumeRemainingExtractServicesUrlJobs < ActiveRecord::Migration[4.2] +class ConsumeRemainingExtractServicesUrlJobs < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -463,8 +463,6 @@ end ```ruby # Post deployment migration -include Gitlab::Database::MigrationHelpers - MIGRATION = 'YourBackgroundMigrationName' DELAY_INTERVAL = 2.minutes.to_i # can be different BATCH_SIZE = 10_000 # can be different @@ -494,8 +492,6 @@ You can reschedule pending migrations from the `background_migration_jobs` table ```ruby # Post deployment migration -include Gitlab::Database::MigrationHelpers - MIGRATION = 'YourBackgroundMigrationName' DELAY_INTERVAL = 2.minutes @@ -511,3 +507,16 @@ end ``` See [`db/post_migrate/20210604070207_retry_backfill_traversal_ids.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/db/post_migrate/20210604070207_retry_backfill_traversal_ids.rb) for a full example. + +### Viewing failure error logs + +After running a background migration, if any jobs have failed, you can view the logs in [Kibana](https://log.gprd.gitlab.net/goto/3afc1393447c401d7602c1874793e2f6). +View the production Sidekiq log and filter for: + +- `json.class: BackgroundMigrationWorker` +- `json.job_status: fail` +- `json.args: ` + +Looking at the `json.error_class`, `json.error_message` and `json.error_backtrace` values may be helpful in understanding why the jobs failed. + +Depending on when and how the failure occurred, you may find other helpful information by filtering with `json.class: `. diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md index d1c5756fa2c..0fa0e220ba9 100644 --- a/doc/development/cascading_settings.md +++ b/doc/development/cascading_settings.md @@ -38,9 +38,11 @@ Settings are not cascading by default. To define a cascading setting, take the f `application_settings`. ```ruby - class AddDelayedProjectRemovalCascadingSetting < ActiveRecord::Migration[6.0] + class AddDelayedProjectRemovalCascadingSetting < Gitlab::Database::Migration[1.0] include Gitlab::Database::MigrationHelpers::CascadingNamespaceSettings + enable_lock_retries! + def up add_cascading_namespace_setting :delayed_project_removal, :boolean, default: false, null: false end diff --git a/doc/development/changelog.md b/doc/development/changelog.md index c96fe2c18c1..be46d61eb4c 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -98,6 +98,7 @@ EE: true database records created during Cycle Analytics model spec." - _Any_ contribution from a community member, no matter how small, **may** have a changelog entry regardless of these guidelines if the contributor wants one. +- Any [GLEX experiment](experiment_guide/gitlab_experiment.md) changes **should not** have a changelog entry. - [Removing](feature_flags/#changelog) a feature flag, when the new code is retained. ## Writing good changelog entries diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md index 33bc416d8bc..aa3888cd866 100644 --- a/doc/development/cicd/cicd_reference_documentation_guide.md +++ b/doc/development/cicd/cicd_reference_documentation_guide.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 76c756b0e95..b4e32066ba8 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -16,7 +16,7 @@ to learn how to update the [reference page](../../ci/yaml/index.md). ## CI Architecture overview -The following is a simplified diagram of the CI architecture. Some details are left out in order to focus on +The following is a simplified diagram of the CI architecture. Some details are left out to focus on the main components. ![CI software architecture](img/ci_architecture.png) @@ -73,7 +73,7 @@ which picks the next job and assigns it to the runner. At this point the job tra For more details read [Job scheduling](#job-scheduling)). While a job is being executed, the runner sends logs back to the server as well any possible artifacts -that need to be stored. Also, a job may depend on artifacts from previous jobs in order to run. In this +that must be stored. Also, a job may depend on artifacts from previous jobs to run. In this case the runner downloads them using a dedicated API endpoint. Artifacts are stored in object storage, while metadata is kept in the database. An important example of artifacts @@ -111,7 +111,7 @@ Once all jobs are completed for the current stage, the server "unlocks" all the ### Communication between runner and GitLab server -Once the runner is [registered](https://docs.gitlab.com/runner/register/) using the registration token, the server knows what type of jobs it can execute. This depends on: +After the runner is [registered](https://docs.gitlab.com/runner/register/) using the registration token, the server knows what type of jobs it can execute. This depends on: - The type of runner it is registered as: - a shared runner @@ -119,7 +119,7 @@ Once the runner is [registered](https://docs.gitlab.com/runner/register/) using - a project specific runner - Any associated tags. -The runner initiates the communication by requesting jobs to execute with `POST /api/v4/jobs/request`. Although this polling generally happens every few seconds we leverage caching via HTTP headers to reduce the server-side work load if the job queue doesn't change. +The runner initiates the communication by requesting jobs to execute with `POST /api/v4/jobs/request`. Although polling happens every few seconds, we leverage caching through HTTP headers to reduce the server-side work load if the job queue doesn't change. This API endpoint runs [`Ci::RegisterJobService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/register_job_service.rb), which: diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index 03823a4b712..3fc464e661f 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -178,10 +178,10 @@ This includes: - Repository/project requirements. - Expected behavior. -- Any places that need to be edited by users before using the template. +- Any places that must be edited by users before using the template. - If the template should be used by copy pasting it into a configuration file, or by using it with the `include` keyword in an existing pipeline. -- If any variables need to be saved in the project's CI/CD settings. +- If any variables must be saved in the project's CI/CD settings. ```yaml # Use this template to publish an application that uses the ABC server. @@ -289,9 +289,9 @@ If the `latest` template does not exist yet, you can copy [the stable template]( ### How to include an older stable template Users may want to use an older [stable template](#stable-version) that is not bundled -in the current GitLab package. For example, the stable templates in GitLab v13.0 and -GitLab v14.0 could be so different that a user wants to continue using the v13.0 template even -after upgrading to GitLab 14.0. +in the current GitLab package. For example, the stable templates in GitLab 13.0 and +GitLab 14.0 could be so different that a user wants to continue using the GitLab 13.0 +template even after upgrading to GitLab 14.0. You can add a note in the template or in documentation explaining how to use `include:remote` to include older template versions. If other templates are included with `include: template`, @@ -335,7 +335,7 @@ follow the progress. ## Testing -Each CI/CD template must be tested in order to make sure that it's safe to be published. +Each CI/CD template must be tested to make sure that it's safe to be published. ### Manual QA @@ -380,7 +380,7 @@ is updated in a major version GitLab release. A template could contain malicious code. For example, a template that contains the `export` shell command in a job might accidentally expose secret project CI/CD variables in a job log. -If you're unsure if it's secure or not, you need to ask security experts for cross-validation. +If you're unsure if it's secure or not, you must ask security experts for cross-validation. ## Contribute CI/CD template merge requests diff --git a/doc/development/code_intelligence/index.md b/doc/development/code_intelligence/index.md index 790ba1539b7..e1e2105298c 100644 --- a/doc/development/code_intelligence/index.md +++ b/doc/development/code_intelligence/index.md @@ -37,7 +37,7 @@ sequenceDiagram 1. The CI/CD job generates a document in an LSIF format (usually `dump.lsif`) using [an indexer](https://lsif.dev) for the language of a project. The format - [describes](https://github.com/sourcegraph/sourcegraph/blob/master/doc/user/code_intelligence/writing_an_indexer.md) + [describes](https://github.com/sourcegraph/sourcegraph/blob/main/doc/code_intelligence/explanations/writing_an_indexer.md) interactions between a method or function and its definition(s) or references. The document is marked to be stored as an LSIF report artifact. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index d66f246ac8c..12cc63ef56d 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -10,7 +10,7 @@ This guide contains advice and best practices for performing code review, and having your code reviewed. All merge requests for GitLab CE and EE, whether written by a GitLab team member -or a volunteer contributor, must go through a code review process to ensure the +or a wider community member, must go through a code review process to ensure the code is effective, understandable, maintainable, and secure. ## Getting your merge request reviewed, approved, and merged @@ -35,7 +35,7 @@ If you need assistance with security scans or comments, feel free to include the Application Security Team (`@gitlab-com/gl-security/appsec`) in the review. Depending on the areas your merge request touches, it must be **approved** by one -or more [maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#maintainer): +or more [maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#maintainer). For approvals, we use the approval functionality found in the merge request widget. For reviewers, we use the [reviewer functionality](../user/project/merge_requests/getting_started.md#reviewer) in the sidebar. @@ -46,9 +46,11 @@ more than one approval, the last maintainer to review and approve merges it. ### Domain experts -Domain experts are team members who have substantial experience with a specific technology, product feature or area of the codebase. Team members are encouraged to self-identify as domain experts and add it to their [team profile](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/team.yml). +Domain experts are team members who have substantial experience with a specific technology, +product feature, or area of the codebase. Team members are encouraged to self-identify as +domain experts and add it to their [team profiles](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/team_members/person/README.md). -When self-identifying as a domain expert, it is recommended to assign the MR changing the `team.yml` to be merged by an already established Domain Expert or a corresponding Engineering Manager. +When self-identifying as a domain expert, it is recommended to assign the MR changing the `.yml` file to be merged by an already established Domain Expert or a corresponding Engineering Manager. We make the following assumption with regards to automatically being considered a domain expert: @@ -107,7 +109,7 @@ with [domain expertise](#domain-experts). 1. If your merge request includes adding a new JavaScript library (*1*)... - If the library significantly increases the [bundle size](https://gitlab.com/gitlab-org/frontend/playground/webpack-memory-metrics/-/blob/master/doc/report.md), it must - be **approved by a [frontend foundations member](https://about.gitlab.com/direction/create/ecosystem/frontend-ux-foundations/)**. + be **approved by a [frontend foundations member](https://about.gitlab.com/direction/ecosystem/foundations/)**. - If the license used by the new library hasn't been approved for use in GitLab, the license must be **approved by a [legal department member](https://about.gitlab.com/handbook/legal/)**. More information about license compatibility can be found in our @@ -117,11 +119,12 @@ with [domain expertise](#domain-experts). 1. If your merge request includes documentation changes, it must be **approved by a [Technical writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)**, based on assignments in the appropriate [DevOps stage group](https://about.gitlab.com/handbook/product/categories/#devops-stages). +1. If your merge request includes changes to development guidelines, follow the [review process](index.md#development-guidelines-review) and get the approvals accordingly. 1. If your merge request includes end-to-end **and** non-end-to-end changes (*4*), it must be **approved by a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors)**. 1. If your merge request only includes end-to-end changes (*4*) **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 Intelligence (telemetry or analytics) changes, it should be reviewed and approved by a [Product Intelligence engineer](https://gitlab.com/gitlab-org/growth/product_intelligence/engineers). +1. If your merge request includes Product Intelligence (telemetry or analytics) changes, it should be reviewed and approved by a [Product Intelligence engineer](https://gitlab.com/gitlab-org/growth/product-intelligence/engineers). 1. If your merge request includes an addition of, or changes to a [Feature spec](testing_guide/testing_levels.md#frontend-feature-tests), it must be **approved by a [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa) or [Quality reviewer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_reviewers_qa)**. 1. If your merge request introduces a new service to GitLab (Puma, Sidekiq, Gitaly are examples), it must be **approved by a [product manager](https://about.gitlab.com/company/team/)**. See the [process for adding a service component to GitLab](adding_service_component.md) for details. @@ -134,15 +137,60 @@ with [domain expertise](#domain-experts). the content. - (*4*): End-to-end changes include all files within the `qa` directory. -#### Security requirements +#### Acceptance checklist -View the updated documentation regarding [internal application security reviews](https://about.gitlab.com/handbook/engineering/security/#internal-application-security-reviews) for **when** and **how** to request a security review. +This checklist encourages the authors, reviewers, and maintainers of merge requests (MRs) to confirm changes were analyzed for high-impact risks to quality, performance, reliability, security, and maintainability. + +Using checklists improves quality in software engineering. This checklist is a straightforward tool to support and bolster the skills of contributors to the GitLab codebase. + +##### Quality + +See the [test engineering process](https://about.gitlab.com/handbook/engineering/quality/test-engineering/) for further quality guidelines. + +1. I have self-reviewed this MR per [code review guidelines](code_review.md). +1. For the code that this change impacts, I believe that the automated tests ([Testing Guide](testing_guide/index.md)) validate functionality that is highly important to users (including consideration of [all test levels](testing_guide/testing_levels.md)). +1. If the existing automated tests do not cover the above functionality, I have added the necessary additional tests or added an issue to describe the automation testing gap and linked it to this MR. +1. I have considered the technical aspects of this change's impact on GitLab.com hosted customers and self-managed customers. +1. I have considered the impact of this change on the frontend, backend, and database portions of the system where appropriate and applied the `~frontend`, `~backend`, and `~database` labels accordingly. +1. I have tested this MR in [all supported browsers](../install/requirements.md#supported-web-browsers), or determined that this testing is not needed. +1. I have confirmed that this change is [backwards compatible across updates](multi_version_compatibility.md), or I have decided that this does not apply. +1. I have properly separated EE content from FOSS, or this MR is FOSS only. + - [Where should EE code go?](ee_features.md#separation-of-ee-code) +1. If I am introducing a new expectation for existing data, I have confirmed that existing data meets this expectation or I have made this expectation optional rather than required. + +##### Performance, reliability, and availability + +1. I am confident that this MR does not harm performance, or I have asked a reviewer to help assess the performance impact. ([Merge request performance guidelines](merge_request_performance_guidelines.md)) +1. I have added [information for database reviewers in the MR description](database_review.md#required), or I have decided that it is unnecessary. + - [Does this MR have database-related changes?](database_review.md) +1. I have considered the availability and reliability risks of this change. +1. I have considered the scalability risk based on future predicted growth. +1. I have considered the performance, reliability, and availability impacts of this change on large customers who may have significantly more data than the average customer. + +##### Documentation + +1. I have included changelog trailers, or I have decided that they are not needed. + - [Does this MR need a changelog?](changelog.md#what-warrants-a-changelog-entry) +1. I have added/updated documentation or decided that documentation changes are unnecessary for this MR. + - [Is documentation required?](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#when-documentation-is-required) + +##### Security + +1. I have confirmed that if this MR contains changes to processing or storing of credentials or tokens, authorization, and authentication methods, or other items described in [the security review guidelines](https://about.gitlab.com/handbook/engineering/security/#when-to-request-a-security-review), I have added the `~security` label and I have `@`-mentioned `@gitlab-com/gl-security/appsec`. +1. I have reviewed the documentation regarding [internal application security reviews](https://about.gitlab.com/handbook/engineering/security/#internal-application-security-reviews) for **when** and **how** to request a security review and requested a security review if this is warranted for this change. + +##### Deployment + +1. I have considered using a feature flag for this change because the change may be high risk. +1. If I am using a feature flag, I plan to test the change in staging before I test it in production, and I have considered rolling it out to a subset of production customers before rolling it out to all customers. + - [When to use a feature flag](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags) +1. I have informed the Infrastructure department of a default setting or new setting change per [definition of done](contributing/merge_request_workflow.md#definition-of-done), or decided that this is unnecessary. ### The responsibility of the merge request author The responsibility to find the best solution and implement it lies with the merge request author. The author or [directly responsible individual](https://about.gitlab.com/handbook/people-group/directly-responsible-individuals/) -will stay assigned to the merge request as the assignee throughout +(DRI) stays assigned to the merge request as the assignee throughout the code review lifecycle. If you are unable to set yourself as an assignee, ask a [reviewer](https://about.gitlab.com/handbook/engineering/workflow/code-review/#reviewer) to do this for you. Before requesting a review from a maintainer to approve and merge, they @@ -169,7 +217,7 @@ database specialists to get input on the data model or specific queries, or to any other developer to get an in-depth review of the solution. If an author is unsure if a merge request needs a [domain expert's](#domain-experts) opinion, -that indicates it does. Without it it's unlikely they have the required level of confidence in their +then that indicates it does. Without it, it's unlikely they have the required level of confidence in their solution. Before the review, the author is requested to submit comments on the merge @@ -249,7 +297,7 @@ without duly verifying them. Note that certain Merge Requests may target a stable branch. These are rare events. These types of Merge Requests cannot be merged by the Maintainer. -Instead these should be sent to the [Release Manager](https://about.gitlab.com/community/release-managers/). +Instead, these should be sent to the [Release Manager](https://about.gitlab.com/community/release-managers/). After merging, a maintainer should stay as the reviewer listed on the merge request. @@ -305,8 +353,8 @@ first time. codebase. Thorough descriptions help all reviewers understand your request and test effectively. - If you know your change depends on another being merged first, note it in the - description and set an [merge request dependency](../user/project/merge_requests/merge_request_dependencies.md). -- Be grateful for the reviewer's suggestions. (`Good call. I'll make that change.`) + description and set a [merge request dependency](../user/project/merge_requests/merge_request_dependencies.md). +- Be grateful for the reviewer's suggestions. ("Good call. I'll make that change.") - Don't take it personally. The review is of the code, not of you. - Explain why the code exists. ("It's like that because of these reasons. Would it be more clear if I rename this class/file/method/variable?") @@ -425,20 +473,20 @@ WARNING: - Start a new merge request pipeline with the `Run pipeline` button in the merge request's "Pipelines" tab, and enable "Merge When Pipeline Succeeds" (MWPS). Note that: - - If **[main is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), + - If **[the default branch is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), do not merge the merge request** except for [very specific cases](https://about.gitlab.com/handbook/engineering/workflow/#criteria-for-merging-during-broken-master). For other cases, follow these [handbook instructions](https://about.gitlab.com/handbook/engineering/workflow/#merging-during-broken-master). - If the latest pipeline was created before the merge request was approved, start a new pipeline to ensure that full RSpec suite has been run. You may skip this step only if the merge request does not contain any backend change. - If the **latest [Pipeline for Merged Results](../ci/pipelines/pipelines_for_merged_results.md)** finished less than 2 hours ago, you - might merge without starting a new pipeline as the merge request is close + may merge without starting a new pipeline as the merge request is close enough to `main`. - When you set the MR to "Merge When Pipeline Succeeds", you should take over subsequent revisions for anything that would be spotted after that. - For merge requests that have had [Squash and merge](../user/project/merge_requests/squash_and_merge.md#squash-and-merge) set, - the squashed commit’s default commit message is taken from the merge request title. - You're encouraged to [select a commit with a more informative commit message](../user/project/merge_requests/squash_and_merge.md#overview) before merging. + the squashed commit's default commit message is taken from the merge request title. + You're encouraged to [select a commit with a more informative commit message](../user/project/merge_requests/squash_and_merge.md) before merging. Thanks to **Pipeline for Merged Results**, authors no longer have to rebase their branch as frequently anymore (only when there are conflicts) because the Merge @@ -526,7 +574,7 @@ author. GitLab is used in a lot of places. Many users use our [Omnibus packages](https://about.gitlab.com/install/), but some use -the [Docker images](https://docs.gitlab.com/omnibus/docker/), some are +the [Docker images](../install/docker.md), some are [installed from source](../install/installation.md), and there are other installation methods available. GitLab.com itself is a large Enterprise Edition instance. This has some implications: @@ -566,7 +614,7 @@ Enterprise Edition instance. This has some implications: If you're adding a new setting in `gitlab.yml`: 1. Try to avoid that, and add to `ApplicationSetting` instead. 1. Ensure that it is also - [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml). + [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml#adding-a-new-setting-to-gitlabyml). 1. **File system access** is not possible in a [cloud-native architecture](architecture.md#adapting-existing-and-introducing-new-components). Ensure that we support object storage for any file storage we need to perform. For more information, see the [uploads documentation](uploads.md). @@ -613,7 +661,7 @@ A merge request may benefit from being considered a customer critical priority b Properties of customer critical merge requests: -- The [VP of Development](https://about.gitlab.com/job-families/engineering/development/management/vp) ([@clefelhocz1](https://gitlab.com/clefelhocz1)) is the DRI for deciding if a merge request qualifies as customer critical. +- The [VP of Development](https://about.gitlab.com/job-families/engineering/development/management/vp/) ([@clefelhocz1](https://gitlab.com/clefelhocz1)) is the DRI for deciding if a merge request qualifies as customer critical. - The DRI applies the `customer-critical-merge-request` label to the merge request. - It is required that the reviewer(s) and maintainer(s) involved with a customer critical merge request are engaged as soon as this decision is made. - It is required to prioritize work for those involved on a customer critical merge request so that they have the time available necessary to focus on it. @@ -650,7 +698,3 @@ A good example of collaboration on an MR touching multiple parts of the codebase ### Credits Largely based on the [`thoughtbot` code review guide](https://github.com/thoughtbot/guides/tree/master/code-review). - ---- - -[Return to Development documentation](index.md) diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index 3804aa7f8a8..37c3c24a7d1 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -16,7 +16,3 @@ GitLab community members and their privileges/responsibilities. | Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account | [List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce). - ---- - -[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index c1dd5ff4c0b..9e8375fcbdd 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -11,32 +11,28 @@ For guidance on UX implementation at GitLab, please refer to our [Design System] The UX team uses labels to manage their workflow. -The ~"UX" label on an issue is a signal to the UX team that it will need UX attention. +The `~UX` label on an issue is a signal to the UX team that it will need UX attention. To better understand the priority by which UX tackles issues, see the [UX section](https://about.gitlab.com/handbook/engineering/ux/) of the handbook. -Once an issue has been worked on and is ready for development, a UXer removes the ~"UX" label and applies the ~"UX ready" label to that issue. +Once an issue has been worked on and is ready for development, a UXer removes the `~UX` label and applies the `~"UX ready"` label to that issue. -There is a special type label called ~"product discovery" intended for UX, -PM, FE, and BE. It represents a discovery issue to discuss the problem and +There is a special type label called `~"product discovery"` intended for UX (user experience), +PM (product manager), FE (frontend), and BE (backend). It represents a discovery issue to discuss the problem and potential solutions. The final output for this issue could be a doc of requirements, a design artifact, or even a prototype. The solution will be developed in a subsequent milestone. -~"product discovery" issues are like any other issue and should contain a milestone label, ~"Deliverable" or ~"Stretch", when scheduled in the current milestone. +`~"product discovery"` issues are like any other issue and should contain a milestone label, `~Deliverable` or `~Stretch`, when scheduled in the current milestone. The initial issue should be about the problem we are solving. If a separate [product discovery issue](https://about.gitlab.com/handbook/engineering/ux/ux-department-workflow/#how-we-use-labels) is needed for additional research and design work, it will be created by a PM or UX person. -Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and +Assign the `~UX`, `~"product discovery"` and `~Deliverable` labels, add a milestone and use a title that makes it clear that the scheduled issue is product discovery (for example, `Product discovery for XYZ`). In order to complete a product discovery issue in a release, you must complete the following: -1. UXer removes the ~UX label, adds the ~"UX ready" label. +1. UXer removes the `~UX` label, adds the `~"UX ready"` label. 1. Modify the issue description in the product discovery issue to contain the final design. If it makes sense, the original information indicating the need for the design can be moved to a lower "Original Information" section. 1. Copy the design to the description of the delivery issue for which the product discovery issue was created. Do not simply refer to the product discovery issue as a separate source of truth. 1. In some cases, a product discovery issue also identifies future enhancements that will not go into the issue that originated the product discovery issue. For these items, create new issues containing the designs to ensure they are not lost. Put the issues in the backlog if they are agreed upon as good ideas. Otherwise leave them for triage. - ---- - -[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 1dfe560d68d..29f6eb57160 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -15,9 +15,7 @@ feature proposal. Show your support with an award emoji and/or join the discussion. Please submit bugs using the ['Bug' issue template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Bug.md) provided on the issue tracker. -The text in the parenthesis is there to help you with what to include. Omit it -when submitting the actual issue. You can copy-paste it and then edit as you -see fit. +The text in the comments (``) is there to help you with what to include. ## Issue triaging @@ -30,12 +28,12 @@ The most important thing is making sure valid issues receive feedback from the development team. Therefore the priority is mentioning developers that can help on those issues. Please select someone with relevant experience from the [GitLab team](https://about.gitlab.com/company/team/). -If there is nobody mentioned with that expertise look in the commit history for +If there is nobody mentioned with that expertise, look in the commit history for the affected files to find someone. We also use [GitLab Triage](https://gitlab.com/gitlab-org/gitlab-triage) to automate some triaging policies. This is currently set up as a scheduled pipeline -(`https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/editpipeline_schedules/10512/edit`, +(`https://gitlab.com/gitlab-org/quality/triage-ops/-/pipeline_schedules/10512/edit`, must have at least the Developer role in the project) running on [quality/triage-ops](https://gitlab.com/gitlab-org/quality/triage-ops) project. @@ -132,9 +130,9 @@ their color is `#A8D695`. , with `_` replaced with a space. -For instance, the "Continuous Integration" group is represented by the -~"group::continuous integration" label in the `gitlab-org` group since its key -under `stages.manage.groups` is `continuous_integration`. +For instance, the "Pipeline Execution" group is represented by the +~"group::pipeline execution" label in the `gitlab-org` group since its key +under `stages.manage.groups` is `pipeline_execution`. The current group labels can be found by [searching the labels list for `group::`](https://gitlab.com/groups/gitlab-org/-/labels?search=group::). @@ -146,17 +144,6 @@ You can find the groups listed in the [Product Stages, Groups, and Categories](h We use the term group to map down product requirements from our product stages. As a team needs some way to collect the work their members are planning to be assigned to, we use the `~group::` labels to do so. -Normally there is a 1:1 relationship between Stage labels and Group labels. In -the spirit of "Everyone can contribute", any issue can be picked up by any group, -depending on current priorities. When picking up an issue belonging to a different -group, it should be relabeled. For example, if an issue labeled `~"devops::create"` -and `~"group::knowledge"` is picked up by someone in the Access group of the Plan stage, -the issue should be relabeled as `~"group::access"` while keeping the original -`~"devops::create"` unchanged. - -We also use stage and group labels to help measure our [merge request rates](https://about.gitlab.com/handbook/engineering/metrics/#merge-request-rate). -Please read [Stage and Group labels](https://about.gitlab.com/handbook/engineering/metrics/#stage-and-group-labels) for more information on how the labels are used in this context. - ### Category labels From the handbook's @@ -384,7 +371,7 @@ below will make it easy to manage this, without unnecessary overhead. 1. If you don't agree with a set weight, discuss with other developers until consensus is reached about the weight 1. Issue weights are an abstract measurement of complexity of the issue. Do not - relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring) + relate issue weight directly to time. This is called [anchoring](https://en.wikipedia.org/wiki/Anchoring_(cognitive_bias)) and something you want to avoid. 1. Something that has a weight of 1 (or no weight) is really small and simple. Something that is 9 is rewriting a large fundamental part of GitLab, @@ -476,7 +463,3 @@ should be of the same quality as those created [in the usual manner](#technical-and-ux-debt) - in particular, the issue title **must not** begin with `Follow-up`! The creating maintainer should also expect to be involved in some capacity when work begins on the follow-up issue. - ---- - -[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 534150e4d37..25561764bd6 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -223,11 +223,19 @@ the contribution acceptance criteria below: ## Definition of done -If you contribute to GitLab please know that changes involve more than just +If you contribute to GitLab, please know that changes involve more than just code. We use the following [definition of done](https://www.agilealliance.org/glossary/definition-of-done). -Your contribution is not *done* until you have made sure it meets all of these +To reach the definition of done, the merge request must create no regressions and meet all these criteria: + +- Verified as working in production on GitLab.com. +- Verified as working for self-managed instances. + +If a regression occurs, we prefer you revert the change. We break the definition of done into two phases: [MR Merge](#mr-merge) and [Production use](#production-use). +Your contribution is *incomplete* until you have made sure it meets all of these requirements. +### MR Merge + 1. Clear description explaining the relevancy of the contribution. 1. Working and clean code that is commented where needed. 1. [Unit, integration, and system tests](../testing_guide/index.md) that all pass @@ -238,17 +246,30 @@ 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 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. Reviewed by relevant reviewers, and all concerns are addressed for Availability, Regressions, and Security. Documentation reviews should take place as soon as possible, but they should not block a merge request. +1. The [MR acceptance checklist](../code_review.md#acceptance-checklist) has been checked as confirmed in the MR. 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) with no new [Sentry](https://about.gitlab.com/handbook/engineering/#sentry) errors or on GitLab.com once the contribution is deployed. -1. Added to the [release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/), - if relevant. -1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml), if relevant. 1. [Black-box tests/end-to-end tests](../testing_guide/testing_levels.md#black-box-tests-at-the-system-level-aka-end-to-end-tests) added if required. Please contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams) with any questions. +1. The change is tested in a review app where possible and if appropriate. 1. The new feature does not degrade the user experience of the product. +1. The change is evaluated to [limit the impact of far-reaching work](https://about.gitlab.com/handbook/engineering/development/#reducing-the-impact-of-far-reaching-work). +1. An agreed-upon rollout plan. +1. Merged by a project maintainer. + +### Production use + +1. Confirmed to be working in staging before implementing the change in production, where possible. +1. Confirmed to be working in the production with no new [Sentry](https://about.gitlab.com/handbook/engineering/#sentry) errors after the contribution is deployed. +1. Confirmed that the rollout plan has been completed. +1. If there is a performance risk in the change, I have analyzed the performance of the system before and after the change. +1. *If the merge request uses feature flags, per-project or per-group enablement, and a staged rollout:* + - Confirmed to be working on GitLab projects. + - Confirmed to be working at each stage for all projects added. +1. Added to the [release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/), + if relevant. +1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml), if relevant. Contributions do not require approval from the [Product team](https://about.gitlab.com/handbook/product/product-processes/#gitlab-pms-arent-the-arbiters-of-community-contributions). diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 1b339b7f252..754e6c7aec6 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -177,11 +177,10 @@ This ensures that our list isn't mistakenly removed by another auto generation o the `.rubocop_todo.yml`. This also allows us greater visibility into the exceptions which are currently being resolved. -One way to generate the initial list is to run the `todo` auto generation, -with `exclude limit` set to a high number. +One way to generate the initial list is to run the Rake task `rubocop:todo:generate`: ```shell -bundle exec rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit=100000 +bundle exec rake rubocop:todo:generate ``` You can then move the list from the freshly generated `.rubocop_todo.yml` for the Cop being actively @@ -242,7 +241,3 @@ See the dedicated [Python Development Guidelines](../python_guide/index.md). ## Misc Code should be written in [US English](https://en.wikipedia.org/wiki/American_English). - ---- - -[Return to Contributing documentation](index.md) 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 f83dc35b4a6..d74f826cc14 100644 --- a/doc/development/database/add_foreign_key_to_existing_column.md +++ b/doc/development/database/add_foreign_key_to_existing_column.md @@ -4,11 +4,17 @@ group: Database info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Adding foreign key constraint to an existing column +# Add a 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. +Foreign keys 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. -Starting with Rails version 4, Rails includes migration helpers to add foreign key constraints to database tables. Before Rails 4, the only way for ensuring some level of consistency was the [`dependent`](https://guides.rubyonrails.org/association_basics.html#options-for-belongs-to-dependent) option within the association definition. Ensuring data consistency on the application level could fail in some unfortunate cases, so we might end up with inconsistent data in the table. This is mostly affecting older tables, where we simply didn't have the framework support to ensure consistency on the database level. These data inconsistencies can easily cause unexpected application behavior or bugs. +Starting with Rails version 4, Rails includes migration helpers to add foreign key constraints +to database tables. Before Rails 4, the only way for ensuring some level of consistency was the +[`dependent`](https://guides.rubyonrails.org/association_basics.html#options-for-belongs-to-dependent) +option in the association definition. Ensuring data consistency on the application level could fail +in some unfortunate cases, so we might end up with inconsistent data in the table. This mostly affects +older tables, where we didn't have the framework support to ensure consistency on the database level. +These data inconsistencies can cause unexpected application behavior or bugs. Adding a foreign key to an existing database column requires database structure changes and potential data changes. In case the table is in use, we should always assume that there is inconsistent data. @@ -45,7 +51,7 @@ class Email < ActiveRecord::Base end ``` -Problem: when the user is removed, the email records related to the removed user will stay in the `emails` table: +Problem: when the user is removed, the email records related to the removed user stays in the `emails` table: ```ruby user = User.find(1) @@ -66,9 +72,7 @@ In the example above, you'd be still able to update records in the `emails` tabl Migration file for adding `NOT VALID` foreign key: ```ruby -class AddNotValidForeignKeyToEmailsUser < ActiveRecord::Migration[5.2] - include Gitlab::Database::MigrationHelpers - +class AddNotValidForeignKeyToEmailsUser < Gitlab::Database::Migration[1.0] def up # safe to use: it requires short lock on the table since we don't validate the foreign key add_foreign_key :emails, :users, on_delete: :cascade, validate: false @@ -85,16 +89,16 @@ Avoid using the `add_foreign_key` constraint more than once per migration file, #### Data migration to fix existing records -The approach here depends on the data volume and the cleanup strategy. If we can easily find "invalid" records by doing a simple database query and the record count is not that high, then the data migration can be executed within a Rails migration. +The approach here depends on the data volume and the cleanup strategy. If we can find "invalid" +records by doing a database query and the record count is not high, then the data migration can +be executed in a Rails migration. In case the data volume is higher (>1000 records), it's better to create a background migration. If unsure, please contact the database team for advice. -Example for cleaning up records in the `emails` table within a database migration: +Example for cleaning up records in the `emails` table in a database migration: ```ruby -class RemoveRecordsWithoutUserFromEmailsTable < ActiveRecord::Migration[5.2] - include Gitlab::Database::MigrationHelpers - +class RemoveRecordsWithoutUserFromEmailsTable < Gitlab::Database::Migration[1.0] disable_ddl_transaction! class Email < ActiveRecord::Base @@ -116,7 +120,7 @@ end ### Validate the foreign key -Validating the foreign key will scan the whole table and make sure that each relation is correct. +Validating the foreign key scans the whole table and makes sure that each relation is correct. NOTE: When using [background migrations](../background_migrations.md), foreign key validation should happen in the next GitLab release. @@ -126,9 +130,7 @@ Migration file for validating the foreign key: ```ruby # frozen_string_literal: true -class ValidateForeignKeyOnEmailUsers < ActiveRecord::Migration[5.2] - include Gitlab::Database::MigrationHelpers - +class ValidateForeignKeyOnEmailUsers < Gitlab::Database::Migration[1.0] def up validate_foreign_key :emails, :user_id end diff --git a/doc/development/database/constraint_naming_convention.md b/doc/development/database/constraint_naming_convention.md index 3faef8aee09..a22ddc1551c 100644 --- a/doc/development/database/constraint_naming_convention.md +++ b/doc/development/database/constraint_naming_convention.md @@ -6,7 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Constraints naming conventions -The most common option is to let Rails pick the name for database constraints and indexes or let PostgreSQL use the defaults (when applicable). However, when needing to define custom names in Rails or working in Go applications where no ORM is used, it is important to follow strict naming conventions to improve consistency and discoverability. +The most common option is to let Rails pick the name for database constraints and indexes or let +PostgreSQL use the defaults (when applicable). However, when defining custom names in Rails, or +working in Go applications where no ORM is used, it is important to follow strict naming conventions +to improve consistency and discoverability. The table below describes the naming conventions for custom PostgreSQL constraints. The intent is not to retroactively change names in existing databases but rather ensure consistency of future changes. diff --git a/doc/development/database/database_reviewer_guidelines.md b/doc/development/database/database_reviewer_guidelines.md index 7a9c08d9d49..59653c6dde3 100644 --- a/doc/development/database/database_reviewer_guidelines.md +++ b/doc/development/database/database_reviewer_guidelines.md @@ -19,7 +19,7 @@ Database reviewers are domain experts who have substantial experience with datab A database review is required whenever an application update [touches the database](../database_review.md#general-process). The database reviewer is tasked with reviewing the database specific updates and -making sure that any queries or modifications will perform without issues +making sure that any queries or modifications perform without issues at the scale of GitLab.com. For more information on the database review process, check the [database review guidelines](../database_review.md). @@ -72,7 +72,7 @@ topics and use cases. The most frequently required during database reviewing are - [Avoiding downtime in migrations](../avoiding_downtime_in_migrations.md). - [SQL guidelines](../sql.md) for working with SQL queries. -## How to apply for becoming a database maintainer +## How to apply to become a database maintainer Once a database reviewer feels confident on switching to a database maintainer, they can update their [team profile](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/team.yml) diff --git a/doc/development/database/efficient_in_operator_queries.md b/doc/development/database/efficient_in_operator_queries.md new file mode 100644 index 00000000000..bc72bce30bf --- /dev/null +++ b/doc/development/database/efficient_in_operator_queries.md @@ -0,0 +1,949 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Efficient `IN` operator queries + +This document describes a technique for building efficient ordered database queries with the `IN` +SQL operator and the usage of a GitLab utility module to help apply the technique. + +NOTE: +The described technique makes heavy use of +[keyset pagination](pagination_guidelines.md#keyset-pagination). +It's advised to get familiar with the topic first. + +## Motivation + +In GitLab, many domain objects like `Issue` live under nested hierarchies of projects and groups. +To fetch nested database records for domain objects at the group-level, +we often perform queries with the `IN` SQL operator. +We are usually interested in ordering the records by some attributes +and limiting the number of records using `ORDER BY` and `LIMIT` clauses for performance. +Pagination may be used to fetch subsequent records. + +Example tasks requiring querying nested domain objects from the group level: + +- Show first 20 issues by creation date or due date from the group `gitlab-org`. +- Show first 20 merge_requests by merged at date from the group `gitlab-com`. + +Unfortunately, ordered group-level queries typically perform badly +as their executions require heavy I/O, memory, and computations. +Let's do an in-depth examination of executing one such query. + +### Performance problems with `IN` queries + +Consider the task of fetching the twenty oldest created issues +from the group `gitlab-org` with the following query: + +```sql +SELECT "issues".* +FROM "issues" +WHERE "issues"."project_id" IN + (SELECT "projects"."id" + FROM "projects" + WHERE "projects"."namespace_id" IN + (SELECT traversal_ids[array_length(traversal_ids, 1)] AS id + FROM "namespaces" + WHERE (traversal_ids @> ('{9970}')))) +ORDER BY "issues"."created_at" ASC, + "issues"."id" ASC +LIMIT 20 +``` + +NOTE: +For pagination, ordering by the `created_at` column is not enough, +we must add the `id` column as a +[tie-breaker](pagination_performance_guidelines.md#tie-breaker-column). + +The execution of the query can be largely broken down into three steps: + +1. The database accesses both `namespaces` and `projects` tables + to find all projects from all groups in the group hierarchy. +1. The database retrieves `issues` records for each project causing heavy disk I/O. + Ideally, an appropriate index configuration should optimize this process. +1. The database sorts the `issues` rows in memory by `created_at` and returns `LIMIT 20` rows to + the end-user. For large groups, this final step requires both large memory and CPU resources. + +
+Expand this sentence to see the execution plan for this DB query. +

+ Limit  (cost=90170.07..90170.12 rows=20 width=1329) (actual time=967.597..967.607 rows=20 loops=1)
+   Buffers: shared hit=239127 read=3060
+   I/O Timings: read=336.879
+   ->  Sort  (cost=90170.07..90224.02 rows=21578 width=1329) (actual time=967.596..967.603 rows=20 loops=1)
+         Sort Key: issues.created_at, issues.id
+         Sort Method: top-N heapsort  Memory: 74kB
+         Buffers: shared hit=239127 read=3060
+         I/O Timings: read=336.879
+         ->  Nested Loop  (cost=1305.66..89595.89 rows=21578 width=1329) (actual time=4.709..797.659 rows=241534 loops=1)
+               Buffers: shared hit=239121 read=3060
+               I/O Timings: read=336.879
+               ->  HashAggregate  (cost=1305.10..1360.22 rows=5512 width=4) (actual time=4.657..5.370 rows=1528 loops=1)
+                     Group Key: projects.id
+                     Buffers: shared hit=2597
+                     ->  Nested Loop  (cost=576.76..1291.32 rows=5512 width=4) (actual time=2.427..4.244 rows=1528 loops=1)
+                           Buffers: shared hit=2597
+                           ->  HashAggregate  (cost=576.32..579.06 rows=274 width=25) (actual time=2.406..2.447 rows=265 loops=1)
+                                 Group Key: namespaces.traversal_ids[array_length(namespaces.traversal_ids, 1)]
+                                 Buffers: shared hit=334
+                                 ->  Bitmap Heap Scan on namespaces  (cost=141.62..575.63 rows=274 width=25) (actual time=1.933..2.330 rows=265 loops=1)
+                                       Recheck Cond: (traversal_ids @> '{9970}'::integer[])
+                                       Heap Blocks: exact=243
+                                       Buffers: shared hit=334
+                                       ->  Bitmap Index Scan on index_namespaces_on_traversal_ids  (cost=0.00..141.55 rows=274 width=0) (actual time=1.897..1.898 rows=265 loops=1)
+                                             Index Cond: (traversal_ids @> '{9970}'::integer[])
+                                             Buffers: shared hit=91
+                           ->  Index Only Scan using index_projects_on_namespace_id_and_id on projects  (cost=0.44..2.40 rows=20 width=8) (actual time=0.004..0.006 rows=6 loops=265)
+                                 Index Cond: (namespace_id = (namespaces.traversal_ids)[array_length(namespaces.traversal_ids, 1)])
+                                 Heap Fetches: 51
+                                 Buffers: shared hit=2263
+               ->  Index Scan using index_issues_on_project_id_and_iid on issues  (cost=0.57..10.57 rows=544 width=1329) (actual time=0.114..0.484 rows=158 loops=1528)
+                     Index Cond: (project_id = projects.id)
+                     Buffers: shared hit=236524 read=3060
+                     I/O Timings: read=336.879
+ Planning Time: 7.750 ms
+ Execution Time: 967.973 ms
+(36 rows)
+
+
+ +The performance of the query depends on the number of rows in the database. +On average, we can say the following: + +- Number of groups in the group-hierarchy: less than 1 000 +- Number of projects: less than 5 000 +- Number of issues: less than 100 000 + +From the list, it's apparent that the number of `issues` records has +the largest impact on the performance. +As per normal usage, we can say that the number of issue records grows +at a faster rate than the `namespaces` and the `projects` records. + +This problem affects most of our group-level features where records are listed +in a specific order, such as group-level issues, merge requests pages, and APIs. +For very large groups the database queries can easily time out, causing HTTP 500 errors. + +## Optimizing ordered `IN` queries + +In the talk +["How to teach an elephant to dance rock'n'roll"](https://www.youtube.com/watch?v=Ha38lcjVyhQ), +Maxim Boguk demonstrated a technique to optimize a special class of ordered `IN` queries, +such as our ordered group-level queries. + +A typical ordered `IN` query may look like this: + +```sql +SELECT t.* FROM t +WHERE t.fkey IN (value_set) +ORDER BY t.pkey +LIMIT N; +``` + +Here's the key insight used in the technique: we need at most `|value_set| + N` record lookups, +rather than retrieving all records satisfying the condition `t.fkey IN value_set` (`|value_set|` +is the number of values in `value_set`). + +We adopted and generalized the technique for use in GitLab by implementing utilities in the +`Gitlab::Pagination::Keyset::InOperatorOptimization` class to facilitate building efficient `IN` +queries. + +### Requirements + +The technique is not a drop-in replacement for the existing group-level queries using `IN` operator. +The technique can only optimize `IN` queries that satisfy the following requirements: + +- `LIMIT` is present, which usually means that the query is paginated + (offset or keyset pagination). +- The column used with the `IN` query and the columns in the `ORDER BY` + clause are covered with a database index. The columns in the index must be + in the following order: `column_for_the_in_query`, `order by column 1`, and + `order by column 2`. +- The columns in the `ORDER BY` clause are distinct + (the combination of the columns uniquely identifies one particular column in the table). + +WARNING: +This technique will not improve the performance of the `COUNT(*)` queries. + +## The `InOperatorOptimization` module + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67352) in GitLab 14.3. + +The `Gitlab::Pagination::Keyset::InOperatorOptimization` module implements utilities for applying a generalized version of +the efficient `IN` query technique described in the previous section. + +To build optimized, ordered `IN` queries that meet [the requirements](#requirements), +use the utility class `QueryBuilder` from the module. + +NOTE: +The generic keyset pagination module introduced in the merge request +[51481](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51481) +plays a fundamental role in the generalized implementation of the technique +in `Gitlab::Pagination::Keyset::InOperatorOptimization`. + +### Basic usage of `QueryBuilder` + +To illustrate a basic usage, we will build a query that +fetches 20 issues with the oldest `created_at` from the group `gitlab-org`. + +The following ActiveRecord query would produce a query similar to +[the unoptimized query](#performance-problems-with-in-queries) that we examined earlier: + +```ruby +scope = Issue + .where(project_id: Group.find(9970).all_projects.select(:id)) # `gitlab-org` group and its subgroups + .order(:created_at, :id) + .limit(20) +``` + +Instead, use the query builder `InOperatorOptimization::QueryBuilder` to produce an optimized +version: + +```ruby +scope = Issue.order(:created_at, :id) +array_scope = Group.find(9970).all_projects.select(:id) +array_mapping_scope = -> (id_expression) { Issue.where(Issue.arel_table[:project_id].eq(id_expression)) } +finder_query = -> (created_at_expression, id_expression) { Issue.where(Issue.arel_table[:id].eq(id_expression)) } + +Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder.new( + scope: scope, + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query +).execute.limit(20) +``` + +- `scope` represents the original `ActiveRecord::Relation` object without the `IN` query. The + relation should define an order which must be supported by the + [keyset pagination library](keyset_pagination.md#usage). +- `array_scope` contains the `ActiveRecord::Relation` object, which represents the original + `IN (subquery)`. The select values must contain the columns by which the subquery is "connected" + to the main query: the `id` of the project record. +- `array_mapping_scope` defines a lambda returning an `ActiveRecord::Relation` object. The lambda + matches (`=`) single select values from the `array_scope`. The lambda yields as many + arguments as the select values defined in the `array_scope`. The arguments are Arel SQL expressions. +- `finder_query` loads the actual record row from the database. It must also be a lambda, where + the order by column expressions is available for locating the record. In this example, the + yielded values are `created_at` and `id` SQL expressions. Finding a record is very fast via the + primary key, so we don't use the `created_at` value. + +The following database index on the `issues` table must be present +to make the query execute efficiently: + +```sql +"idx_issues_on_project_id_and_created_at_and_id" btree (project_id, created_at, id) +``` + +
+Expand this sentence to see the SQL query. +

+SELECT "issues".*
+FROM
+  (WITH RECURSIVE "array_cte" AS MATERIALIZED
+     (SELECT "projects"."id"
+ FROM "projects"
+ WHERE "projects"."namespace_id" IN
+     (SELECT traversal_ids[array_length(traversal_ids, 1)] AS id
+      FROM "namespaces"
+      WHERE (traversal_ids @> ('{9970}')))),
+                  "recursive_keyset_cte" AS (  -- initializer row start
+                                               (SELECT NULL::issues AS records,
+                                                       array_cte_id_array,
+                                                       issues_created_at_array,
+                                                       issues_id_array,
+                                                       0::bigint AS COUNT
+                                                FROM
+                                                  (SELECT ARRAY_AGG("array_cte"."id") AS array_cte_id_array,
+                                                          ARRAY_AGG("issues"."created_at") AS issues_created_at_array,
+                                                          ARRAY_AGG("issues"."id") AS issues_id_array
+                                                   FROM
+                                                     (SELECT "array_cte"."id"
+                                                      FROM array_cte) array_cte
+                                                   LEFT JOIN LATERAL
+                                                     (SELECT "issues"."created_at",
+                                                             "issues"."id"
+                                                      FROM "issues"
+                                                      WHERE "issues"."project_id" = "array_cte"."id"
+                                                      ORDER BY "issues"."created_at" ASC, "issues"."id" ASC
+                                                      LIMIT 1) issues ON TRUE
+                                                   WHERE "issues"."created_at" IS NOT NULL
+                                                     AND "issues"."id" IS NOT NULL) array_scope_lateral_query
+                                                LIMIT 1)
+                                                -- initializer row finished
+                                             UNION ALL
+                                               (SELECT
+                                                  -- result row start
+                                                  (SELECT issues -- record finder query as the first column
+                                                   FROM "issues"
+                                                   WHERE "issues"."id" = recursive_keyset_cte.issues_id_array[position]
+                                                   LIMIT 1),
+                                                   array_cte_id_array,
+                                                   recursive_keyset_cte.issues_created_at_array[:position_query.position-1]||next_cursor_values.created_at||recursive_keyset_cte.issues_created_at_array[position_query.position+1:],
+                                                   recursive_keyset_cte.issues_id_array[:position_query.position-1]||next_cursor_values.id||recursive_keyset_cte.issues_id_array[position_query.position+1:],
+                                                   recursive_keyset_cte.count + 1
+                                                -- result row finished
+                                                FROM recursive_keyset_cte,
+                                                     LATERAL
+                                                  -- finding the cursor values of the next record start
+                                                  (SELECT created_at,
+                                                          id,
+                                                          position
+                                                   FROM UNNEST(issues_created_at_array, issues_id_array) WITH
+                                                   ORDINALITY AS u(created_at, id, position)
+                                                   WHERE created_at IS NOT NULL
+                                                     AND id IS NOT NULL
+                                                   ORDER BY "created_at" ASC, "id" ASC
+                                                   LIMIT 1) AS position_query,
+                                                  -- finding the cursor values of the next record end
+                                                  -- finding the next cursor values (next_cursor_values_query) start
+                                                             LATERAL
+                                                  (SELECT "record"."created_at",
+                                                          "record"."id"
+                                                   FROM (
+                                                         VALUES (NULL,
+                                                                 NULL)) AS nulls
+                                                   LEFT JOIN
+                                                     (SELECT "issues"."created_at",
+                                                             "issues"."id"
+                                                      FROM (
+                                                              (SELECT "issues"."created_at",
+                                                                      "issues"."id"
+                                                               FROM "issues"
+                                                               WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[position]
+                                                                 AND recursive_keyset_cte.issues_created_at_array[position] IS NULL
+                                                                 AND "issues"."created_at" IS NULL
+                                                                 AND "issues"."id" > recursive_keyset_cte.issues_id_array[position]
+                                                               ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)
+                                                            UNION ALL
+                                                              (SELECT "issues"."created_at",
+                                                                      "issues"."id"
+                                                               FROM "issues"
+                                                               WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[position]
+                                                                 AND recursive_keyset_cte.issues_created_at_array[position] IS NOT NULL
+                                                                 AND "issues"."created_at" IS NULL
+                                                               ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)
+                                                            UNION ALL
+                                                              (SELECT "issues"."created_at",
+                                                                      "issues"."id"
+                                                               FROM "issues"
+                                                               WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[position]
+                                                                 AND recursive_keyset_cte.issues_created_at_array[position] IS NOT NULL
+                                                                 AND "issues"."created_at" > recursive_keyset_cte.issues_created_at_array[position]
+                                                               ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)
+                                                            UNION ALL
+                                                              (SELECT "issues"."created_at",
+                                                                      "issues"."id"
+                                                               FROM "issues"
+                                                               WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[position]
+                                                                 AND recursive_keyset_cte.issues_created_at_array[position] IS NOT NULL
+                                                                 AND "issues"."created_at" = recursive_keyset_cte.issues_created_at_array[position]
+                                                                 AND "issues"."id" > recursive_keyset_cte.issues_id_array[position]
+                                                               ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)) issues
+                                                      ORDER BY "issues"."created_at" ASC, "issues"."id" ASC
+                                                      LIMIT 1) record ON TRUE
+                                                   LIMIT 1) AS next_cursor_values))
+                                                  -- finding the next cursor values (next_cursor_values_query) END
+SELECT (records).*
+   FROM "recursive_keyset_cte" AS "issues"
+   WHERE (COUNT <> 0)) issues -- filtering out the initializer row
+LIMIT 20
+
+
+ +### Using the `IN` query optimization + +#### Adding more filters + +In this example, let's add an extra filter by `milestone_id`. + +Be careful when adding extra filters to the query. If the column is not covered by the same index, +then the query might perform worse than the non-optimized query. The `milestone_id` column in the +`issues` table is currently covered by a different index: + +```sql +"index_issues_on_milestone_id" btree (milestone_id) +``` + +Adding the `miletone_id = X` filter to the `scope` argument or to the optimized scope causes bad performance. + +Example (bad): + +```ruby +Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder.new( + scope: scope, + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query +).execute + .where(milestone_id: 5) + .limit(20) +``` + +To address this concern, we could define another index: + +```sql +"idx_issues_on_project_id_and_milestone_id_and_created_at_and_id" btree (project_id, milestone_id, created_at, id) +``` + +Adding more indexes to the `issues` table could significantly affect the performance of +the `UPDATE` queries. In this case, it's better to rely on the original query. It means that if we +want to use the optimization for the unfiltered page we need to add extra logic in the application code: + +```ruby +if optimization_possible? # no extra params or params covered with the same index as the ORDER BY clause + run_optimized_query +else + run_normal_in_query +end +``` + +#### Multiple `IN` queries + +Let's assume that we want to extend the group-level queries to include only incident and test case +issue types. + +The original ActiveRecord query would look like this: + +```ruby +scope = Issue + .where(project_id: Group.find(9970).all_projects.select(:id)) # `gitlab-org` group and its subgroups + .where(issue_type: [:incident, :test_case]) # 1, 2 + .order(:created_at, :id) + .limit(20) +``` + +To construct the array scope, we'll need to take the Cartesian product of the `project_id IN` and +the `issue_type IN` queries. `issue_type` is an ActiveRecord enum, so we need to +construct the following table: + +| `project_id` | `issue_type_value` | +| ------------ | ------------------ | +| 2 | 1 | +| 2 | 2 | +| 5 | 1 | +| 5 | 2 | +| 10 | 1 | +| 10 | 2 | +| 9 | 1 | +| 9 | 2 | + +For the `issue_types` query we can construct a value list without querying a table: + +```ruby +value_list = Arel::Nodes::ValuesList.new([[Issue.issue_types[:incident]],[Issue.issue_types[:test_case]]]) +issue_type_values = Arel::Nodes::Grouping.new(value_list).as('issue_type_values (value)').to_sql + +array_scope = Group + .find(9970) + .all_projects + .from("#{Project.table_name}, #{issue_type_values}") + .select(:id, :value) +``` + +Building the `array_mapping_scope` query requires two arguments: `id` and `issue_type_value`: + +```ruby +array_mapping_scope = -> (id_expression, issue_type_value_expression) { Issue.where(Issue.arel_table[:project_id].eq(id_expression)).where(Issue.arel_table[:issue_type].eq(issue_type_value_expression)) } +``` + +The `scope` and the `finder` queries don't change: + +```ruby +scope = Issue.order(:created_at, :id) +finder_query = -> (created_at_expression, id_expression) { Issue.where(Issue.arel_table[:id].eq(id_expression)) } + +Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder.new( + scope: scope, + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query +).execute.limit(20) +``` + +
+Expand this sentence to see the SQL query. +

+SELECT "issues".*
+FROM
+  (WITH RECURSIVE "array_cte" AS MATERIALIZED
+     (SELECT "projects"."id", "value"
+      FROM projects, (
+                      VALUES (1), (2)) AS issue_type_values (value)
+      WHERE "projects"."namespace_id" IN
+          (WITH RECURSIVE "base_and_descendants" AS (
+                                                       (SELECT "namespaces".*
+                                                        FROM "namespaces"
+                                                        WHERE "namespaces"."type" = 'Group'
+                                                          AND "namespaces"."id" = 9970)
+                                                     UNION
+                                                       (SELECT "namespaces".*
+                                                        FROM "namespaces", "base_and_descendants"
+                                                        WHERE "namespaces"."type" = 'Group'
+                                                          AND "namespaces"."parent_id" = "base_and_descendants"."id")) SELECT "id"
+           FROM "base_and_descendants" AS "namespaces")),
+                  "recursive_keyset_cte" AS (
+                                               (SELECT NULL::issues AS records,
+                                                       array_cte_id_array,
+                                                       array_cte_value_array,
+                                                       issues_created_at_array,
+                                                       issues_id_array,
+                                                       0::bigint AS COUNT
+                                                FROM
+                                                  (SELECT ARRAY_AGG("array_cte"."id") AS array_cte_id_array,
+                                                          ARRAY_AGG("array_cte"."value") AS array_cte_value_array,
+                                                          ARRAY_AGG("issues"."created_at") AS issues_created_at_array,
+                                                          ARRAY_AGG("issues"."id") AS issues_id_array
+                                                   FROM
+                                                     (SELECT "array_cte"."id",
+                                                             "array_cte"."value"
+                                                      FROM array_cte) array_cte
+                                                   LEFT JOIN LATERAL
+                                                     (SELECT "issues"."created_at",
+                                                             "issues"."id"
+                                                      FROM "issues"
+                                                      WHERE "issues"."project_id" = "array_cte"."id"
+                                                        AND "issues"."issue_type" = "array_cte"."value"
+                                                      ORDER BY "issues"."created_at" ASC, "issues"."id" ASC
+                                                      LIMIT 1) issues ON TRUE
+                                                   WHERE "issues"."created_at" IS NOT NULL
+                                                     AND "issues"."id" IS NOT NULL) array_scope_lateral_query
+                                                LIMIT 1)
+                                             UNION ALL
+                                               (SELECT
+                                                  (SELECT issues
+                                                   FROM "issues"
+                                                   WHERE "issues"."id" = recursive_keyset_cte.issues_id_array[POSITION]
+                                                   LIMIT 1), array_cte_id_array,
+                                                             array_cte_value_array,
+                                                             recursive_keyset_cte.issues_created_at_array[:position_query.position-1]||next_cursor_values.created_at||recursive_keyset_cte.issues_created_at_array[position_query.position+1:], recursive_keyset_cte.issues_id_array[:position_query.position-1]||next_cursor_values.id||recursive_keyset_cte.issues_id_array[position_query.position+1:], recursive_keyset_cte.count + 1
+                                                FROM recursive_keyset_cte,
+                                                     LATERAL
+                                                  (SELECT created_at,
+                                                          id,
+                                                          POSITION
+                                                   FROM UNNEST(issues_created_at_array, issues_id_array) WITH
+                                                   ORDINALITY AS u(created_at, id, POSITION)
+                                                   WHERE created_at IS NOT NULL
+                                                     AND id IS NOT NULL
+                                                   ORDER BY "created_at" ASC, "id" ASC
+                                                   LIMIT 1) AS position_query,
+                                                             LATERAL
+                                                  (SELECT "record"."created_at",
+                                                          "record"."id"
+                                                   FROM (
+                                                         VALUES (NULL,
+                                                                 NULL)) AS nulls
+                                                   LEFT JOIN
+                                                     (SELECT "issues"."created_at",
+                                                             "issues"."id"
+                                                      FROM (
+                                                              (SELECT "issues"."created_at",
+                                                                      "issues"."id"
+                                                               FROM "issues"
+                                                               WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[POSITION]
+                                                                 AND "issues"."issue_type" = recursive_keyset_cte.array_cte_value_array[POSITION]
+                                                                 AND recursive_keyset_cte.issues_created_at_array[POSITION] IS NULL
+                                                                 AND "issues"."created_at" IS NULL
+                                                                 AND "issues"."id" > recursive_keyset_cte.issues_id_array[POSITION]
+                                                               ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)
+                                                            UNION ALL
+                                                              (SELECT "issues"."created_at",
+                                                                      "issues"."id"
+                                                               FROM "issues"
+                                                               WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[POSITION]
+                                                                 AND "issues"."issue_type" = recursive_keyset_cte.array_cte_value_array[POSITION]
+                                                                 AND recursive_keyset_cte.issues_created_at_array[POSITION] IS NOT NULL
+                                                                 AND "issues"."created_at" IS NULL
+                                                               ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)
+                                                            UNION ALL
+                                                              (SELECT "issues"."created_at",
+                                                                      "issues"."id"
+                                                               FROM "issues"
+                                                               WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[POSITION]
+                                                                 AND "issues"."issue_type" = recursive_keyset_cte.array_cte_value_array[POSITION]
+                                                                 AND recursive_keyset_cte.issues_created_at_array[POSITION] IS NOT NULL
+                                                                 AND "issues"."created_at" > recursive_keyset_cte.issues_created_at_array[POSITION]
+                                                               ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)
+                                                            UNION ALL
+                                                              (SELECT "issues"."created_at",
+                                                                      "issues"."id"
+                                                               FROM "issues"
+                                                               WHERE "issues"."project_id" = recursive_keyset_cte.array_cte_id_array[POSITION]
+                                                                 AND "issues"."issue_type" = recursive_keyset_cte.array_cte_value_array[POSITION]
+                                                                 AND recursive_keyset_cte.issues_created_at_array[POSITION] IS NOT NULL
+                                                                 AND "issues"."created_at" = recursive_keyset_cte.issues_created_at_array[POSITION]
+                                                                 AND "issues"."id" > recursive_keyset_cte.issues_id_array[POSITION]
+                                                               ORDER BY "issues"."created_at" ASC, "issues"."id" ASC)) issues
+                                                      ORDER BY "issues"."created_at" ASC, "issues"."id" ASC
+                                                      LIMIT 1) record ON TRUE
+                                                   LIMIT 1) AS next_cursor_values)) SELECT (records).*
+   FROM "recursive_keyset_cte" AS "issues"
+   WHERE (COUNT <> 0)) issues
+LIMIT 20
+
+
+
+ +NOTE: +To make the query efficient, the following columns need to be covered with an index: `project_id`, `issue_type`, `created_at`, and `id`. + +#### Batch iteration + +Batch iteration over the records is possible via the keyset `Iterator` class. + +```ruby +scope = Issue.order(:created_at, :id) +array_scope = Group.find(9970).all_projects.select(:id) +array_mapping_scope = -> (id_expression) { Issue.where(Issue.arel_table[:project_id].eq(id_expression)) } +finder_query = -> (created_at_expression, id_expression) { Issue.where(Issue.arel_table[:id].eq(id_expression)) } + +opts = { + in_operator_optimization_options: { + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query + } +} + +Gitlab::Pagination::Keyset::Iterator.new(scope: scope, **opts).each_batch(of: 100) do |records| + puts records.select(:id).map { |r| [r.id] } +end +``` + +#### Keyset pagination + +The optimization works out of the box with GraphQL and the `keyset_paginate` helper method. +Read more about [keyset pagination](keyset_pagination.md). + +```ruby +array_scope = Group.find(9970).all_projects.select(:id) +array_mapping_scope = -> (id_expression) { Issue.where(Issue.arel_table[:project_id].eq(id_expression)) } +finder_query = -> (created_at_expression, id_expression) { Issue.where(Issue.arel_table[:id].eq(id_expression)) } + +opts = { + in_operator_optimization_options: { + array_scope: array_scope, + array_mapping_scope: array_mapping_scope, + finder_query: finder_query + } +} + +issues = Issue + .order(:created_at, :id) + .keyset_paginate(per_page: 20, keyset_order_options: opts) + .records +``` + +#### Offset pagination with Kaminari + +The `ActiveRecord` scope produced by the `InOperatorOptimization` class can be used in +[offset-paginated](pagination_guidelines.md#offset-pagination) +queries. + +```ruby +Gitlab::Pagination::Keyset::InOperatorOptimization::QueryBuilder + .new(...) + .execute + .page(1) + .per(20) + .without_count +``` + +## Generalized `IN` optimization technique + +Let's dive into how `QueryBuilder` builds the optimized query +to fetch the twenty oldest created issues from the group `gitlab-org` +using the generalized `IN` optimization technique. + +### Array CTE + +As the first step, we use a common table expression (CTE) for collecting the `projects.id` values. +This is done by wrapping the incoming `array_scope` ActiveRecord relation parameter with a CTE. + +```sql +WITH array_cte AS MATERIALIZED ( + SELECT "projects"."id" + FROM "projects" + WHERE "projects"."namespace_id" IN + (SELECT traversal_ids[array_length(traversal_ids, 1)] AS id + FROM "namespaces" + WHERE (traversal_ids @> ('{9970}'))) +) +``` + +This query produces the following result set with only one column (`projects.id`): + +| ID | +| --- | +| 9 | +| 2 | +| 5 | +| 10 | + +### Array mapping + +For each project (that is, each record storing a project ID in `array_cte`), +we will fetch the cursor value identifying the first issue respecting the `ORDER BY` clause. + +As an example, let's pick the first record `ID=9` from `array_cte`. +The following query should fetch the cursor value `(created_at, id)` identifying +the first issue record respecting the `ORDER BY` clause for the project with `ID=9`: + +```sql +SELECT "issues"."created_at", "issues"."id" +FROM "issues"."project_id"=9 +ORDER BY "issues"."created_at" ASC, "issues"."id" ASC +LIMIT 1; +``` + +We will use `LATERAL JOIN` to loop over the records in the `array_cte` and find the +cursor value for each project. The query would be built using the `array_mapping_scope` lambda +function. + +```sql +SELECT ARRAY_AGG("array_cte"."id") AS array_cte_id_array, + ARRAY_AGG("issues"."created_at") AS issues_created_at_array, + ARRAY_AGG("issues"."id") AS issues_id_array +FROM ( + SELECT "array_cte"."id" FROM array_cte +) array_cte +LEFT JOIN LATERAL +( + SELECT "issues"."created_at", "issues"."id" + FROM "issues" + WHERE "issues"."project_id" = "array_cte"."id" + ORDER BY "issues"."created_at" ASC, "issues"."id" ASC + LIMIT 1 +) issues ON TRUE +``` + +Since we have an index on `project_id`, `created_at`, and `id`, +index-only scans should quickly locate all the cursor values. + +This is how the query could be translated to Ruby: + +```ruby +created_at_values = [] +id_values = [] +project_ids.map do |project_id| + created_at, id = Issue.select(:created_at, :id).where(project_id: project_id).order(:created_at, :id).limit(1).first # N+1 but it's fast + created_at_values << created_at + id_values << id +end +``` + +This is what the result set would look like: + +| `project_ids` | `created_at_values` | `id_values` | +| ------------- | ------------------- | ----------- | +| 2 | 2020-01-10 | 5 | +| 5 | 2020-01-05 | 4 | +| 10 | 2020-01-15 | 7 | +| 9 | 2020-01-05 | 3 | + +The table shows the cursor values (`created_at, id`) of the first record for each project +respecting the `ORDER BY` clause. + +At this point, we have the initial data. To start collecting the actual records from the database, +we'll use a recursive CTE query where each recursion locates one row until +the `LIMIT` is reached or no more data can be found. + +Here's an outline of the steps we will take in the recursive CTE query +(expressing the steps in SQL is non-trivial but will be explained next): + +1. Sort the initial resultset according to the `ORDER BY` clause. +1. Pick the top cursor to fetch the record, this is our first record. In the example, +this cursor would be (`2020-01-05`, `3`) for `project_id=9`. +1. We can use (`2020-01-05`, `3`) to fetch the next issue respecting the `ORDER BY` clause +`project_id=9` filter. This produces an updated resultset. + + | `project_ids` | `created_at_values` | `id_values` | + | ------------- | ------------------- | ----------- | + | 2 | 2020-01-10 | 5 | + | 5 | 2020-01-05 | 4 | + | 10 | 2020-01-15 | 7 | + | **9** | **2020-01-06** | **6** | + +1. Repeat 1 to 3 with the updated resultset until we have fetched `N=20` records. + +### Initializing the recursive CTE query + +For the initial recursive query, we'll need to produce exactly one row, we call this the +initializer query (`initializer_query`). + +Use `ARRAY_AGG` function to compact the initial result set into a single row +and use the row as the initial value for the recursive CTE query: + +Example initializer row: + +| `records` | `project_ids` | `created_at_values` | `id_values` | `Count` | `Position` | +| -------------- | --------------- | ------------------- | ----------- | ------- | ---------- | +| `NULL::issues` | `[9, 2, 5, 10]` | `[...]` | `[...]` | `0` | `NULL` | + +- The `records` column contains our sorted database records, and the initializer query sets the +first value to `NULL`, which is filtered out later. +- The `count` column tracks the number of records found. We use this column to filter out the +initializer row from the result set. + +### Recursive portion of the CTE query + +The result row is produced with the following steps: + +1. [Order the keyset arrays.](#order-the-keyset-arrays) +1. [Find the next cursor.](#find-the-next-cursor) +1. [Produce a new row.](#produce-a-new-row) + +#### Order the keyset arrays + +Order the keyset arrays according to the original `ORDER BY` clause with `LIMIT 1` using the +`UNNEST [] WITH ORDINALITY` table function. The function locates the "lowest" keyset cursor +values and gives us the array position. These cursor values are used to locate the record. + +NOTE: +At this point, we haven't read anything from the database tables, because we relied on +fast index-only scans. + +| `project_ids` | `created_at_values` | `id_values` | +| ------------- | ------------------- | ----------- | +| 2 | 2020-01-10 | 5 | +| 5 | 2020-01-05 | 4 | +| 10 | 2020-01-15 | 7 | +| 9 | 2020-01-05 | 3 | + +The first row is the 4th one (`position = 4`), because it has the lowest `created_at` and +`id` values. The `UNNEST` function also exposes the position using an extra column (note: +PostgreSQL uses 1-based index). + +Demonstration of the `UNNEST [] WITH ORDINALITY` table function: + +```sql +SELECT position FROM unnest('{2020-01-10, 2020-01-05, 2020-01-15, 2020-01-05}'::timestamp[], '{5, 4, 7, 3}'::int[]) + WITH ORDINALITY AS t(created_at, id, position) ORDER BY created_at ASC, id ASC LIMIT 1; +``` + +Result: + +```sql +position +---------- + 4 +(1 row) +``` + +#### Find the next cursor + +Now, let's find the next cursor values (`next_cursor_values_query`) for the project with `id = 9`. +To do that, we build a keyset pagination SQL query. Find the next row after +`created_at = 2020-01-05` and `id = 3`. Because we order by two database columns, there can be two +cases: + +- There are rows with `created_at = 2020-01-05` and `id > 3`. +- There are rows with `created_at > 2020-01-05`. + +Generating this query is done by the generic keyset pagination library. After the query is done, +we have a temporary table with the next cursor values: + +| `created_at` | ID | +| ------------ | --- | +| 2020-01-06 | 6 | + +#### Produce a new row + +As the final step, we need to produce a new row by manipulating the initializer row +(`data_collector_query` method). Two things happen here: + +- Read the full row from the DB and return it in the `records` columns. (`result_collector_columns` +method) +- Replace the cursor values at the current position with the results from the keyset query. + +Reading the full row from the database is only one index scan by the primary key. We use the +ActiveRecord query passed as the `finder_query`: + +```sql +(SELECT "issues".* FROM issues WHERE id = id_values[position] LIMIT 1) +``` + +By adding parentheses, the result row can be put into the `records` column. + +Replacing the cursor values at `position` can be done via standard PostgreSQL array operators: + +```sql +-- created_at_values column value +created_at_values[:position-1]||next_cursor_values.created_at||created_at_values[position+1:] + +-- id_values column value +id_values[:position-1]||next_cursor_values.id||id_values[position+1:] +``` + +The Ruby equivalent would be the following: + +```ruby +id_values[0..(position - 1)] + [next_cursor_values.id] + id_values[(position + 1)..-1] +``` + +After this, the recursion starts again by finding the next lowest cursor value. + +### Finalizing the query + +For producing the final `issues` rows, we're going to wrap the query with another `SELECT` statement: + +```sql +SELECT "issues".* +FROM ( + SELECT (records).* -- similar to ruby splat operator + FROM recursive_keyset_cte + WHERE recursive_keyset_cte.count <> 0 -- filter out the initializer row +) AS issues +``` + +### Performance comparison + +Assuming that we have the correct database index in place, we can compare the query performance by +looking at the number of database rows accessed by the query. + +- Number of groups: 100 +- Number of projects: 500 +- Number of issues (in the group hierarchy): 50 000 + +Standard `IN` query: + +| Query | Entries read from index | Rows read from the table | Rows sorted in memory | +| ------------------------ | ----------------------- | ------------------------ | --------------------- | +| group hierarchy subquery | 100 | 0 | 0 | +| project lookup query | 500 | 0 | 0 | +| issue lookup query | 50 000 | 20 | 50 000 | + +Optimized `IN` query: + +| Query | Entries read from index | Rows read from the table | Rows sorted in memory | +| ------------------------ | ----------------------- | ------------------------ | --------------------- | +| group hierarchy subquery | 100 | 0 | 0 | +| project lookup query | 500 | 0 | 0 | +| issue lookup query | 519 | 20 | 10 000 | + +The group and project queries are not using sorting, the necessary columns are read from database +indexes. These values are accessed frequently so it's very likely that most of the data will be +in the PostgreSQL's buffer cache. + +The optimized `IN` query will read maximum 519 entries (cursor values) from the index: + +- 500 index-only scans for populating the arrays for each project. The cursor values of the first +record will be here. +- Maximum 19 additional index-only scans for the consecutive records. + +The optimized `IN` query will sort the array (cursor values per project array) 20 times, which +means we'll sort 20 x 500 rows. However, this might be a less memory-intensive task than +sorting 10 000 rows at once. + +Performance comparison for the `gitlab-org` group: + +| Query | Number of 8K Buffers involved | Uncached execution time | Cached execution time | +| -------------------- | ----------------------------- | ----------------------- | --------------------- | +| `IN` query | 240833 | 1.2s | 660ms | +| Optimized `IN` query | 9783 | 450ms | 22ms | + +NOTE: +Before taking measurements, the group lookup query was executed separately in order to make +the group data available in the buffer cache. Since it's a frequently called query, it's going to +hit many shared buffers during the query execution in the production environment. diff --git a/doc/development/database/index.md b/doc/development/database/index.md index b61a71ffb8e..a7b752e14ef 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -62,6 +62,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [Query performance guidelines](../query_performance.md) - [Pagination guidelines](pagination_guidelines.md) - [Pagination performance guidelines](pagination_performance_guidelines.md) +- [Efficient `IN` operator queries](efficient_in_operator_queries.md) ## Case studies diff --git a/doc/development/database/keyset_pagination.md b/doc/development/database/keyset_pagination.md index e30c3cc8832..fd62c36b753 100644 --- a/doc/development/database/keyset_pagination.md +++ b/doc/development/database/keyset_pagination.md @@ -36,7 +36,8 @@ Keyset pagination works without any configuration for simple ActiveRecord querie - Order by one column. - Order by two columns, where the last column is the primary key. -The library can detect nullable and non-distinct columns and based on these, it will add extra ordering using the primary key. This is necessary because keyset pagination expects distinct order by values: +The library detects nullable and non-distinct columns and based on these, adds extra ordering +using the primary key. This is necessary because keyset pagination expects distinct order by values: ```ruby Project.order(:created_at).keyset_paginate.records # ORDER BY created_at, id @@ -79,7 +80,7 @@ cursor = paginator.cursor_for_next_page # encoded column attributes for the next paginator = Project.order(:name).keyset_paginate(cursor: cursor).records # loading the next page ``` -Since keyset pagination does not support page numbers, we are restricted to go to the following pages: +Because keyset pagination does not support page numbers, we are restricted to go to the following pages: - Next page - Previous page @@ -111,7 +112,8 @@ In the HAML file, we can render the records: The performance of the keyset pagination depends on the database index configuration and the number of columns we use in the `ORDER BY` clause. -In case we order by the primary key (`id`), then the generated queries will be efficient since the primary key is covered by a database index. +In case we order by the primary key (`id`), then the generated queries are efficient because +the primary key is covered by a database index. When two or more columns are used in the `ORDER BY` clause, it's advised to check the generated database query and make sure that the correct index configuration is used. More information can be found on the [pagination guideline page](pagination_guidelines.md#index-coverage). @@ -149,7 +151,9 @@ puts paginator2.records.to_a # UNION query ## Complex order configuration -Common `ORDER BY` configurations will be handled by the `keyset_paginate` method automatically so no manual configuration is needed. There are a few edge cases where order object configuration is necessary: +Common `ORDER BY` configurations are handled by the `keyset_paginate` method automatically +so no manual configuration is needed. There are a few edge cases where order object +configuration is necessary: - `NULLS LAST` ordering. - Function-based ordering. @@ -170,12 +174,13 @@ scope.keyset_paginate # raises: Gitlab::Pagination::Keyset::Paginator::Unsupport The `keyset_paginate` method raises an error because the order value on the query is a custom SQL string and not an [`Arel`](https://www.rubydoc.info/gems/arel) AST node. The keyset library cannot automatically infer configuration values from these kinds of queries. -To make keyset pagination work, we need to configure custom order objects, to do so, we need to collect information about the order columns: +To make keyset pagination work, we must configure custom order objects, to do so, we must +collect information about the order columns: -- `relative_position` can have duplicated values since no unique index is present. -- `relative_position` can have null values because we don't have a not null constraint on the column. For this, we need to determine where will we see NULL values, at the beginning of the resultset or the end (`NULLS LAST`). -- Keyset pagination requires distinct order columns, so we'll need to add the primary key (`id`) to make the order distinct. -- Jumping to the last page and paginating backwards actually reverses the `ORDER BY` clause. For this, we'll need to provide the reversed `ORDER BY` clause. +- `relative_position` can have duplicated values because no unique index is present. +- `relative_position` can have null values because we don't have a not null constraint on the column. For this, we must determine where we see NULL values, at the beginning of the result set, or the end (`NULLS LAST`). +- Keyset pagination requires distinct order columns, so we must add the primary key (`id`) to make the order distinct. +- Jumping to the last page and paginating backwards actually reverses the `ORDER BY` clause. For this, we must provide the reversed `ORDER BY` clause. Example: @@ -206,7 +211,8 @@ scope.keyset_paginate.records # works ### Function-based ordering -In the following example, we multiply the `id` by 10 and ordering by that value. Since the `id` column is unique, we need to define only one column: +In the following example, we multiply the `id` by 10 and order by that value. Because the `id` +column is unique, we define only one column: ```ruby order = Gitlab::Pagination::Keyset::Order.build([ @@ -233,7 +239,8 @@ The `add_to_projections` flag tells the paginator to expose the column expressio ### `iid` based ordering -When ordering issues, the database ensures that we'll have distinct `iid` values within a project. Ordering by one column is enough to make the pagination work if the `project_id` filter is present: +When ordering issues, the database ensures that we have distinct `iid` values in a project. +Ordering by one column is enough to make the pagination work if the `project_id` filter is present: ```ruby order = Gitlab::Pagination::Keyset::Order.build([ diff --git a/doc/development/database/multiple_databases.md b/doc/development/database/multiple_databases.md index 71dcc5bb866..0fd9f821fab 100644 --- a/doc/development/database/multiple_databases.md +++ b/doc/development/database/multiple_databases.md @@ -24,24 +24,26 @@ configurations. For example, given a `config/database.yml` like below: ```yaml development: - adapter: postgresql - encoding: unicode - database: gitlabhq_development - host: /path/to/gdk/postgresql - pool: 10 - prepared_statements: false - variables: - statement_timeout: 120s + main: + adapter: postgresql + encoding: unicode + database: gitlabhq_development + host: /path/to/gdk/postgresql + pool: 10 + prepared_statements: false + variables: + statement_timeout: 120s test: &test - adapter: postgresql - encoding: unicode - database: gitlabhq_test - host: /path/to/gdk/postgresql - pool: 10 - prepared_statements: false - variables: - statement_timeout: 120s + main: + adapter: postgresql + encoding: unicode + database: gitlabhq_test + host: /path/to/gdk/postgresql + pool: 10 + prepared_statements: false + variables: + statement_timeout: 120s ``` Edit the `config/database.yml` to look like this: @@ -98,18 +100,45 @@ and their tables must be placed in two directories for now: We aim to keep the schema for both tables the same across both databases. + + ### Removing joins between `ci_*` and non `ci_*` tables -We are planning on moving all the `ci_*` tables to a separate database so +Queries that join across databases raise an error. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68620) +in GitLab 14.3, for new queries only. Pre-existing queries do not raise an error. + +We are planning on moving all the `ci_*` tables to a separate database, so referencing `ci_*` tables with other tables will not be possible. This means, that using any kind of `JOIN` in SQL queries will not work. We have identified already many such examples that need to be fixed in . -The following are some real examples that have resulted from this and these -patterns may apply to future cases. +#### Path to removing cross-database joins + +The following steps are the process to remove cross-database joins between +`ci_*` and non `ci_*` tables: + +1. **{check-circle}** Add all failing specs to the [`cross-join-allowlist.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/f5de89daeb468fc45e1e95a76d1b5297aa53da11/spec/support/database/cross-join-allowlist.yml) + file. +1. **{dotted-circle}** Find the code that caused the spec failure and wrap the isolated code + in [`allow_cross_joins_across_databases`](#allowlist-for-existing-cross-joins). + Link to a new issue assigned to the correct team to remove the specs from the + `cross-join-allowlist.yml` file. +1. **{dotted-circle}** Remove the `cross-join-allowlist.yml` file and stop allowing + whole test files. +1. **{dotted-circle}** Fix the problem and remove the `allow_cross_joins_across_databases` call. +1. **{dotted-circle}** Fix all the cross-joins and remove the `allow_cross_joins_across_databases` method. + +#### Suggestions for removing cross-database joins -#### Remove the code +The following sections are some real examples that were identified as joining across databases, +along with possible suggestions on how to fix them. + +##### Remove the code The simplest solution we've seen several times now has been an existing scope that is unused. This is the easiest example to fix. So the first step is to @@ -131,7 +160,7 @@ to evaluate, because `UsageData` is not critical to users and it may be possible to get a similarly useful metric with a simpler approach. Alternatively we may find that nobody is using these metrics, so we can remove them. -#### Use `preload` instead of `includes` +##### Use `preload` instead of `includes` The `includes` and `preload` methods in Rails are both ways to avoid an N+1 query. The `includes` method in Rails uses a heuristic approach to determine @@ -145,7 +174,7 @@ allows you to avoid the join, while still avoiding the N+1 query. You can see a real example of this solution being used in . -#### De-normalize some foreign key to the table +##### De-normalize some foreign key to the table De-normalization refers to adding redundant precomputed (duplicated) data to a table to simplify certain queries or to improve performance. In this @@ -198,7 +227,7 @@ You can see this approach implemented in . This MR also de-normalizes `pipeline_id` to fix a similar query. -#### De-normalize into an extra table +##### De-normalize into an extra table Sometimes the previous de-normalization (adding an extra column) doesn't work for your specific case. This may be due to the fact that your data is not 1:1, or @@ -245,18 +274,88 @@ logic to delete these rows if or whenever necessary in your domain. Finally, this de-normalization and new query also improves performance because it does less joins and needs less filtering. -#### Summary of cross-join removal patterns +##### Use `disable_joins` for `has_one` or `has_many` `through:` relations + +Sometimes a join query is caused by using `has_one ... through:` or `has_many +... through:` across tables that span the different databases. These joins +sometimes can be solved by adding +[`disable_joins:true`](https://edgeguides.rubyonrails.org/active_record_multiple_databases.html#handling-associations-with-joins-across-databases). +This is a Rails feature which we +[backported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66400). We +also extended the feature to allow a lambda syntax for enabling `disable_joins` +with a feature flag. If you use this feature we encourage using a feature flag +as it mitigates risk if there is some serious performance regression. + +You can see an example where this was used in +. + +With any change to DB queries it is important to analyze and compare the SQL +before and after the change. `disable_joins` can introduce very poorly performing +code depending on the actual logic of the `has_many` or `has_one` relationship. +The key thing to look for is whether any of the intermediate result sets +used to construct the final result set have an unbounded amount of data loaded. +The best way to tell is by looking at the SQL generated and confirming that +each one is limited in some way. You can tell by either a `LIMIT 1` clause or +by `WHERE` clause that is limiting based on a unique column. Any unbounded +intermediate dataset could lead to loading too many IDs into memory. + +An example where you may see very poor performance is the following +hypothetical code: + +```ruby +class Project + has_many :pipelines + has_many :builds, through: :pipelines +end + +class Pipeline + has_many :builds +end + +class Build + belongs_to :pipeline +end + +def some_action + @builds = Project.find(5).builds.order(created_at: :desc).limit(10) +end +``` + +In the above case `some_action` will generate a query like: + +```sql +select * from builds +inner join pipelines on builds.pipeline_id = pipelines.id +where pipelines.project_id = 5 +order by builds.created_at desc +limit 10 +``` + +However, if you changed the relation to be: + +```ruby +class Project + has_many :pipelines + has_many :builds, through: :pipelines, disable_joins: true +end +``` -A quick checklist for fixing a specific join query would be: +Then you would get the following 2 queries: -1. Is the code even used? If not just remove it -1. If the code is used, then is this feature even used or can we implement the - feature in a simpler way and still meet the requirements. Always prefer the - simplest option. -1. Can we remove the join if we de-normalize the data you are joining to by - adding a new column -1. Can we remove the join by adding a new table in the correct database that - replicates the minimum data needed to do the join +```sql +select id from pipelines where project_id = 5; + +select * from builds where pipeline_id in (...) +order by created_at desc +limit 10; +``` + +Because the first query does not limit by any unique column or +have a `LIMIT` clause, it can load an unlimited number of +pipeline IDs into memory, which are then sent in the following query. +This can lead to very poor performance in the Rails application and the +database. In cases like this, you might need to re-write the +query or look at other patterns described above for removing cross-joins. #### How to validate you have correctly removed a cross-join @@ -291,3 +390,74 @@ end You can see a real example of using this method for fixing a cross-join in . + +#### Allowlist for existing cross-joins + +A cross-join across databases can be explicitly allowed by wrapping the code in the +`::Gitlab::Database.allow_cross_joins_across_databases` helper method. + +This method should only be used: + +- For existing code. +- If the code is required to help migrate away from a cross-join. For example, + in a migration that backfills data for future use to remove a cross-join. + +The `allow_cross_joins_across_databases` helper method can be used as follows: + +```ruby +::Gitlab::Database.allow_cross_joins_across_databases(url: 'https://gitlab.com/gitlab-org/gitlab/-/issues/336590') do + subject.perform(1, 4) +end +``` + +The `url` parameter should point to an issue with a milestone for when we intend +to fix the cross-join. If the cross-join is being used in a migration, we do not +need to fix the code. See +for more details. + +## `config/database.yml` + +GitLab will support running multiple databases in the future, for example to [separate tables for the continuous integration features](https://gitlab.com/groups/gitlab-org/-/epics/6167) from the main database. In order to prepare for this change, we [validate the structure of the configuration](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67877) in `database.yml` to ensure that only known databases are used. + +Previously, the `config/database.yml` would look like this: + +```yaml +production: + adapter: postgresql + encoding: unicode + database: gitlabhq_production + ... +``` + +With the support for many databases the support for this +syntax is deprecated and will be removed in [15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/338182). + +The new `config/database.yml` needs to include a database name +to define a database configuration. Only `main:` and `ci:` database +names are supported today. The `main:` needs to always be a first +entry in a hash. This change applies to decomposed and non-decomposed +change. If an invalidate or deprecated syntax is used the error +or warning will be printed during application start. + +```yaml +# Non-decomposed database +production: + main: + adapter: postgresql + encoding: unicode + database: gitlabhq_production + ... + +# Decomposed database +production: + main: + adapter: postgresql + encoding: unicode + database: gitlabhq_production + ... + ci: + adapter: postgresql + encoding: unicode + database: gitlabhq_production_ci + ... +``` diff --git a/doc/development/database/not_null_constraints.md b/doc/development/database/not_null_constraints.md index 178a207dab5..de070f7e434 100644 --- a/doc/development/database/not_null_constraints.md +++ b/doc/development/database/not_null_constraints.md @@ -25,7 +25,7 @@ For example, consider a migration that creates a table with two `NOT NULL` colum `db/migrate/20200401000001_create_db_guides.rb`: ```ruby -class CreateDbGuides < ActiveRecord::Migration[6.0] +class CreateDbGuides < Gitlab::Database::Migration[1.0] def change create_table :db_guides do |t| t.bigint :stars, default: 0, null: false @@ -44,7 +44,7 @@ For example, consider a migration that adds a new `NOT NULL` column `active` to `db/migrate/20200501000001_add_active_to_db_guides.rb`: ```ruby -class AddExtendedTitleToSprints < ActiveRecord::Migration[6.0] +class AddExtendedTitleToSprints < Gitlab::Database::Migration[1.0] def change add_column :db_guides, :active, :boolean, default: true, null: false end @@ -111,9 +111,7 @@ with `validate: false` in a post-deployment migration, `db/post_migrate/20200501000001_add_not_null_constraint_to_epics_description.rb`: ```ruby -class AddNotNullConstraintToEpicsDescription < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class AddNotNullConstraintToEpicsDescription < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -144,9 +142,7 @@ so we are going to add a post-deployment migration for the 13.0 milestone (curre `db/post_migrate/20200501000002_cleanup_epics_with_null_description.rb`: ```ruby -class CleanupEpicsWithNullDescription < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class CleanupEpicsWithNullDescription < Gitlab::Database::Migration[1.0] # With BATCH_SIZE=1000 and epics.count=29500 on GitLab.com # - 30 iterations will be run # - each requires on average ~150ms @@ -184,9 +180,7 @@ migration helper in a final post-deployment migration, `db/post_migrate/20200601000001_validate_not_null_constraint_on_epics_description.rb`: ```ruby -class ValidateNotNullConstraintOnEpicsDescription < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class ValidateNotNullConstraintOnEpicsDescription < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md index b7209b4ca30..3a772b10a6d 100644 --- a/doc/development/database/pagination_guidelines.md +++ b/doc/development/database/pagination_guidelines.md @@ -302,7 +302,7 @@ LIMIT 20 ##### Tooling -A generic keyset pagination library is available within the GitLab project which can most of the cases easly replace the existing, kaminari based pagination with significant performance improvements when dealing with large datasets. +A generic keyset pagination library is available within the GitLab project which can most of the cases easily replace the existing, kaminari based pagination with significant performance improvements when dealing with large datasets. Example: diff --git a/doc/development/database/rename_database_tables.md b/doc/development/database/rename_database_tables.md index 8ac50d2c0a0..881adf00ad0 100644 --- a/doc/development/database/rename_database_tables.md +++ b/doc/development/database/rename_database_tables.md @@ -60,7 +60,7 @@ Consider the next release as "Release N.M". Execute a standard migration (not a post-migration): ```ruby - include Gitlab::Database::MigrationHelpers + enable_lock_retries! def up rename_table_safely(:issues, :tickets) @@ -96,8 +96,6 @@ At this point, we don't have applications using the old database table name in t 1. Remove the database view through a post-migration: ```ruby - include Gitlab::Database::MigrationHelpers - def up finalize_table_rename(:issues, :tickets) end 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 688d811b897..a0dda42fdc7 100644 --- a/doc/development/database/strings_and_the_text_data_type.md +++ b/doc/development/database/strings_and_the_text_data_type.md @@ -11,11 +11,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w When adding new columns that will be used to store strings or other textual information: 1. We always use the `text` data type instead of the `string` data type. -1. `text` columns should always have a limit set, either by using the `create_table_with_constraints` helper -when creating a table, or by using the `add_text_limit` when altering an existing table. +1. `text` columns should always have a limit set, either by using the `create_table` with +the `#text ... limit: 100` helper (see below) when creating a table, or by using the `add_text_limit` +when altering an existing table. -The `text` data type can not be defined with a limit, so `create_table_with_constraints` and `add_text_limit` enforce -that by adding a [check constraint](https://www.postgresql.org/docs/11/ddl-constraints.html) on the column. +The standard Rails `text` column type can not be defined with a limit, but we extend `create_table` to +add a `limit: 255` option. Outside of `create_table`, `add_text_limit` can be used to add a [check constraint](https://www.postgresql.org/docs/11/ddl-constraints.html) +to an already existing column. ## Background information @@ -41,36 +43,24 @@ Don't use text columns for `attr_encrypted` attributes. Use a ## Create a new table with text columns When adding a new table, the limits for all text columns should be added in the same migration as -the table creation. +the table creation. We add a `limit:` attribute to Rails' `#text` method, which allows adding a limit +for this column. For example, consider a migration that creates a table with two text columns, `db/migrate/20200401000001_create_db_guides.rb`: ```ruby -class CreateDbGuides < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - - def up - create_table_with_constraints :db_guides do |t| +class CreateDbGuides < Gitlab::Database::Migration[1.0] + def change + create_table :db_guides do |t| t.bigint :stars, default: 0, null: false - t.text :title - t.text :notes - - t.text_limit :title, 128 - t.text_limit :notes, 1024 + t.text :title, limit: 128 + t.text :notes, limit: 1024 end end - - def down - # No need to drop the constraints, drop_table takes care of everything - drop_table :db_guides - end end ``` -Note that the `create_table_with_constraints` helper uses the `with_lock_retries` helper -internally, so we don't need to manually wrap the method call in the migration. - ## Add a text column to an existing table Adding a column to an existing table requires an exclusive lock for that table. Even though that lock @@ -84,7 +74,7 @@ For example, consider a migration that adds a new text column `extended_title` t `db/migrate/20200501000001_add_extended_title_to_sprints.rb`: ```ruby -class AddExtendedTitleToSprints < ActiveRecord::Migration[6.0] +class AddExtendedTitleToSprints < Gitlab::Database::Migration[1.0] # rubocop:disable Migration/AddLimitToTextColumns # limit is added in 20200501000002_add_text_limit_to_sprints_extended_title @@ -99,8 +89,7 @@ A second migration should follow the first one with a limit added to `extended_t `db/migrate/20200501000002_add_text_limit_to_sprints_extended_title.rb`: ```ruby -class AddTextLimitToSprintsExtendedTitle < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers +class AddTextLimitToSprintsExtendedTitle < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -175,9 +164,7 @@ in a post-deployment migration, `db/post_migrate/20200501000001_add_text_limit_migration.rb`: ```ruby -class AddTextLimitMigration < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class AddTextLimitMigration < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up @@ -208,9 +195,7 @@ to add a background migration for the 13.0 milestone (current), `db/post_migrate/20200501000002_schedule_cap_title_length_on_issues.rb`: ```ruby -class ScheduleCapTitleLengthOnIssues < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class ScheduleCapTitleLengthOnIssues < Gitlab::Database::Migration[1.0] # Info on how many records will be affected on GitLab.com # time each batch needs to run on average, etc ... BATCH_SIZE = 5000 @@ -255,9 +240,7 @@ helper in a final post-deployment migration, `db/post_migrate/20200601000001_validate_text_limit_migration.rb`: ```ruby -class ValidateTextLimitMigration < ActiveRecord::Migration[6.0] - include Gitlab::Database::MigrationHelpers - +class ValidateTextLimitMigration < Gitlab::Database::Migration[1.0] disable_ddl_transaction! def up diff --git a/doc/development/database/table_partitioning.md b/doc/development/database/table_partitioning.md index 207d5a733ce..5319c73aad0 100644 --- a/doc/development/database/table_partitioning.md +++ b/doc/development/database/table_partitioning.md @@ -173,7 +173,7 @@ An example migration of partitioning the `audit_events` table by its `created_at` column would look like: ```ruby -class PartitionAuditEvents < ActiveRecord::Migration[6.0] +class PartitionAuditEvents < Gitlab::Database::Migration[1.0] include Gitlab::Database::PartitioningMigrationHelpers def up @@ -200,7 +200,7 @@ into the partitioned copy. Continuing the above example, the migration would look like: ```ruby -class BackfillPartitionAuditEvents < ActiveRecord::Migration[6.0] +class BackfillPartitionAuditEvents < Gitlab::Database::Migration[1.0] include Gitlab::Database::PartitioningMigrationHelpers def up @@ -233,7 +233,7 @@ failed jobs. Once again, continuing the example, this migration would look like: ```ruby -class CleanupPartitionedAuditEventsBackfill < ActiveRecord::Migration[6.0] +class CleanupPartitionedAuditEventsBackfill < Gitlab::Database::Migration[1.0] include Gitlab::Database::PartitioningMigrationHelpers def up diff --git a/doc/development/database/transaction_guidelines.md b/doc/development/database/transaction_guidelines.md index 1c25496b153..4c586135015 100644 --- a/doc/development/database/transaction_guidelines.md +++ b/doc/development/database/transaction_guidelines.md @@ -12,7 +12,7 @@ For further reference please check PostgreSQL documentation about [transactions] ## Database decomposition and sharding -The [sharding group](https://about.gitlab.com/handbook/engineering/development/enablement/sharding) plans to split the main GitLab database and move some of the database tables to other database servers. +The [sharding group](https://about.gitlab.com/handbook/engineering/development/enablement/sharding/) plans to split the main GitLab database and move some of the database tables to other database servers. The group will start decomposing the `ci_*` related database tables first. To maintain the current application development experience, tooling and static analyzers will be added to the codebase to ensure correct data access and data modification methods. By using the correct form for defining database transactions, we can save significant refactoring work in the future. diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index 67ec1b3c4f1..b1c8508c884 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -25,6 +25,12 @@ 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 want to seed the empty DB with sample data (approximately 4 minutes): + +```shell +bundle exec rake dev:setup +``` + 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: @@ -64,6 +70,36 @@ bundle exec rails db -e development - `SELECT * FROM schema_migrations WHERE version = '20170926203418';`: Check if a migration was run - `DELETE FROM schema_migrations WHERE version = '20170926203418';`: Manually remove a migration +## Access the database with a GUI + +Most GUIs (DataGrid, RubyMine, DBeaver) require a TCP connection to the database, but by default +the database runs on a UNIX socket. To be able to access the database from these tools, some steps +are needed: + +1. On the GDK root directory, run: + + ```shell + gdk config set postgresql.host localhost + ``` + +1. Open your `gdk.yml`, and confirm that it has the following lines: + + ```yaml + postgresql: + host: localhost + ``` + +1. Reconfigure GDK: + + ```shell + gdk reconfigure + ``` + +1. On your database GUI, select `localhost` as host, `5432` as port and `gitlabhq_development` as database. + Alternatively, you can use the connection string `postgresql://localhost:5432/gitlabhq_development`. + +The new connection should be working now. + ## Access the GDK database with Visual Studio Code Use these instructions for exploring the GitLab database while developing with the GDK: diff --git a/doc/development/database_review.md b/doc/development/database_review.md index 2746d9f6582..42bfa656a61 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -108,7 +108,7 @@ the following preparations into account. - Ensure the down method reverts the changes in `db/structure.sql`. - Update the migration output whenever you modify the migrations during the review process. - Add tests for the migration in `spec/migrations` if necessary. See [Testing Rails migrations at GitLab](testing_guide/testing_migrations_guide.md) for more details. -- When [high-traffic](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3) tables are involved in the migration, use the [`with_lock_retries`](migration_style_guide.md#retry-mechanism-when-acquiring-database-locks) helper method. Review the relevant [examples in our documentation](migration_style_guide.md#examples) for use cases and solutions. +- When [high-traffic](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3) tables are involved in the migration, use the [`enable_lock_retries`](migration_style_guide.md#retry-mechanism-when-acquiring-database-locks) method to enable lock-retries. Review the relevant [examples in our documentation](migration_style_guide.md#usage-with-transactional-migrations) for use cases and solutions. - Ensure RuboCop checks are not disabled unless there's a valid reason to. - When adding an index to a [large table](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3), test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slack channel and add the execution time to the MR description: @@ -128,7 +128,9 @@ test its execution using `CREATE INDEX CONCURRENTLY` in the `#database-lab` Slac - Write the raw SQL in the MR description. Preferably formatted nicely with [pgFormatter](https://sqlformat.darold.net) or [paste.depesz.com](https://paste.depesz.com) and using regular quotes + (for example, `"projects"."id"`) and avoiding smart quotes (for example, `“projects”.“id”`). + - In case of queries generated dynamically by using parameters, there should be one raw SQL query for each variation. For example, a finder for issues that may take as a parameter an optional filter on projects, diff --git a/doc/development/deprecation_guidelines/index.md b/doc/development/deprecation_guidelines/index.md index 3543345aa34..f8ee29e6904 100644 --- a/doc/development/deprecation_guidelines/index.md +++ b/doc/development/deprecation_guidelines/index.md @@ -32,6 +32,6 @@ It also should be [deprecated in advance](https://about.gitlab.com/handbook/mark For API removals, see the [GraphQL](../../api/graphql/index.md#deprecation-and-removal-process) and [GitLab API](../../api/index.md#compatibility-guidelines) guidelines. -For configuration removals, see the [Omnibus deprecation policy](https://docs.gitlab.com/omnibus/package-information/deprecation_policy.html). +For configuration removals, see the [Omnibus deprecation policy](../../administration/package_information/deprecation_policy.md). For versioning and upgrade details, see our [Release and Maintenance policy](../../policy/maintenance.md). diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index b0fa6c3428c..5a4d365ed20 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -67,10 +67,12 @@ When the state of a flag changes (for example, disabled by default to enabled by Possible version history entries are: ```markdown -> - [Enabled on GitLab.com](issue-link) in GitLab X.X and is ready for production use. -> - [Enabled on GitLab.com](issue-link) in GitLab X.X and is ready for production use. Available to GitLab.com administrators only. -> - [Enabled with flag](issue-link) for self-managed GitLab in GitLab X.X and is ready for production use. -> - [Feature flag removed](issue-line) in GitLab X.X. +> - [Introduced](issue-link) in GitLab X.X. [Deployed behind the flag](../../administration/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com](issue-link) in GitLab X.X. +> - [Enabled on GitLab.com](issue-link) in GitLab X.X. Available to GitLab.com administrators only. +> - [Enabled on self-managed](issue-link) in GitLab X.X. +> - [Feature flag removed](issue-link) in GitLab X.X. +> - [Generally available](issue-link) in GitLab X.X. ``` ## Feature flag documentation examples @@ -78,7 +80,7 @@ Possible version history entries are: The following examples show the progression of a feature flag. ```markdown -> Introduced in GitLab 13.7. +> Introduced in GitLab 13.7. [Deployed behind the `forti_token_cloud` flag](../../administration/feature_flags.md), disabled by default. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, @@ -86,11 +88,11 @@ ask an administrator to [enable the `forti_token_cloud` flag](../administration/ The feature is not ready for production use. ``` -If it were to be updated in the future to enable its use in production, you can update the version history: +When the feature is enabled in production, you can update the version history: ```markdown -> - Introduced in GitLab 13.7. -> - [Enabled with `forti_token_cloud` flag](https://gitlab.com/issue/etc) for self-managed GitLab in GitLab X.X and ready for production use. +> - Introduced in GitLab 13.7. [Deployed behind the `forti_token_cloud` flag](../../administration/feature_flags.md), disabled by default. +> - [Enabled on self-managed](https://gitlab.com/issue/etc) GitLab 13.8. FLAG: On self-managed GitLab, by default this feature is available. To hide the feature per user, @@ -100,8 +102,9 @@ ask an administrator to [disable the `forti_token_cloud` flag](../administration And, when the feature is done and fully available to all users: ```markdown -> - Introduced in GitLab 13.7. -> - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab X.X and is ready for production use. -> - [Enabled with `forti_token_cloud` flag](https://gitlab.com/issue/etc) for self-managed GitLab in GitLab X.X and is ready for production use. -> - [Feature flag `forti_token_cloud`](https://gitlab.com/issue/etc) removed in GitLab X.X. +> - Introduced in GitLab 13.7. [Deployed behind the `forti_token_cloud` flag](../../administration/feature_flags.md), disabled by default. +> - [Enabled on self-managed](https://gitlab.com/issue/etc) GitLab 13.8. +> - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9. +> - [Feature flag `forti_token_cloud`](https://gitlab.com/issue/etc) removed in GitLab 14.0. +> - [Generally available](issue-link) in GitLab 14.0. ``` diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 59a1b8c7b99..a597ea512c6 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -131,10 +131,10 @@ 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](#move-or-rename-a-page). + [Learn more](redirects.md). - `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). + [Learn more](redirects.md#redirections-for-pages-with-disqus-comments). ### Comments metadata @@ -156,133 +156,7 @@ Nanoc layout), which is displayed at the top of the page if defined. ## Move or rename a page -Moving or renaming a document is the same as changing its location. Be sure to -assign a technical writer to any merge request that renames or moves a page. -Technical Writers can help with any questions and can review your change. - -When moving or renaming a page, you must redirect browsers to the new page. -This ensures users find the new page, and have the opportunity to update their -bookmarks. - -There are two types of redirects: - -- Redirect codes added into the documentation files themselves, for users who - view the docs in `/help` on self-managed instances. For example, - [`/help` on GitLab.com](https://gitlab.com/help). -- [GitLab Pages redirects](../../user/project/pages/redirects.md), - for users who view the docs on [`docs.gitlab.com`](https://docs.gitlab.com). - -The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md) -to regularly update the [`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml) -file. - -To add a redirect: - -1. In the repository (`gitlab`, `gitlab-runner`, `omnibus-gitlab`, or `charts`), - create a new documentation file. Don't delete the old one. The easiest - way is to copy it. For example: - - ```shell - cp doc/user/search/old_file.md doc/api/new_file.md - ``` - -1. Add the redirect code to the old documentation file by running the - following Rake task. The first argument is the path of the old file, - and the second argument is the path of the new file: - - - To redirect to a page in the same project, use relative paths and - the `.md` extension. Both old and new paths start from the same location. - In the following example, both paths are relative to `doc/`: - - ```shell - bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, doc/api/new_file.md]" - ``` - - - To redirect to a page in a different project or site, use the full URL (with `https://`) : - - ```shell - bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]" - ``` - - Alternatively, you can omit the arguments and be asked to enter their values: - - ```shell - bundle exec rake gitlab:docs:redirect - ``` - - If you don't want to use the Rake task, you can use the following template. - However, the file paths must be relative to the `doc` or `docs` directory. - - Replace the value of `redirect_to` with the new file path and `YYYY-MM-DD` - with the date the file should be removed. - - Redirect files that link to docs in internal documentation projects - are removed after three months. Redirect files that link to external sites are - removed after one year: - - ```markdown - --- - redirect_to: '../newpath/to/file/index.md' - remove_date: 'YYYY-MM-DD' - --- - - This document was moved to [another location](../path/to/file/index.md). - - - - ``` - -1. If the documentation page being moved has any Disqus comments, follow the steps - described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). -1. Open a merge request with your changes. If a documentation page - you're removing includes images that aren't used - with any other documentation pages, be sure to use your merge request to delete - those images from the repository. -1. Assign the merge request to a technical writer for review and merge. -1. Search for links to the old documentation file. You must find and update all - links that point to the old documentation file: - - - In , search for full URLs: - `grep -r "docs.gitlab.com/ee/path/to/file.html" .` - - In , - search the navigation bar configuration files for the path with `.html`: - `grep -r "path/to/file.html" .` - - In any of the four internal projects, search for links in the docs - and codebase. Search for all variations, including full URL and just the path. - For example, go to the root directory of the `gitlab` project and run: - - ```shell - grep -r "docs.gitlab.com/ee/path/to/file.html" . - grep -r "path/to/file.html" . - grep -r "path/to/file.md" . - grep -r "path/to/file" . - ``` - - You may need to try variations of relative links, such as `../path/to/file` or - `../file` to find every case. - -### Redirections for pages with Disqus comments - -If the documentation page being relocated already has Disqus comments, -we need to preserve the Disqus thread. - -Disqus uses an identifier per page, and for , the page identifier -is configured to be the page URL. Therefore, when we change the document location, -we need to preserve the old URL as the same Disqus identifier. - -To do that, add to the front matter the variable `disqus_identifier`, -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 information. You must -include the filename in the `disqus_identifier` URL, even if it's `index.html` or `README.html`. - -```yaml ---- -disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html' ---- -``` +See [redirects](redirects.md). ## Merge requests for GitLab documentation @@ -405,76 +279,7 @@ on how the left-side navigation menu is built and updated. ## Previewing the changes live -NOTE: -To preview your changes to documentation locally, follow this -[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). - -The live preview is currently enabled for the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner) - -If your merge request has docs changes, you can use the manual `review-docs-deploy` job -to deploy the docs review app for your merge request. - -![Manual trigger a docs build](img/manual_build_docs.png) - -You must push a branch to those repositories, as it doesn't work for forks. - -The `review-docs-deploy*` job: - -1. Triggers a cross project pipeline and build the docs site with your changes. - -In case the review app URL returns 404, this means that either the site is not -yet deployed, or something went wrong with the remote pipeline. Give it a few -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. - -NOTE: -Someone with no merge rights to the GitLab projects (think of forks from -contributors) cannot run the manual job. In that case, you can -ask someone from the GitLab team who has the permissions to do that for you. - -### Troubleshooting review apps - -In case the review app URL returns 404, follow these steps to debug: - -1. **Did you follow the URL from the merge request widget?** If yes, then check if - the link is the same as the one in the job output. -1. **Did you follow the URL from the job output?** If yes, then it means that - either the site is not yet deployed or something went wrong with the remote - pipeline. Give it a few minutes and it should appear online, otherwise you - can check the status of the remote pipeline from the link in the job output. - If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. - -### Technical aspects - -If you want to know the in-depth details, here's what's really happening: - -1. You manually run the `review-docs-deploy` job in a merge request. -1. The job runs the [`scripts/trigger-build`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/trigger-build) - script with the `docs deploy` flag, which triggers the "Triggered from `gitlab-org/gitlab` 'review-docs-deploy' job" - pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `main`). -1. The preview URL is shown both at the job output and in the merge request - widget. You also get the link to the remote pipeline. -1. In the `gitlab-org/gitlab-docs` project, the pipeline is created and it - [skips the test jobs](https://gitlab.com/gitlab-org/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55) - to lower the build time. -1. Once the docs site is built, the HTML files are uploaded as artifacts. -1. A specific runner tied only to the docs project, runs the Review App job - that downloads the artifacts and uses `rsync` to transfer the files over - to a location where NGINX serves them. - -The following GitLab features are used among others: - -- [Manual jobs](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) -- [Multi project pipelines](../../ci/pipelines/multi_project_pipelines.md) -- [Review Apps](../../ci/review_apps/index.md) -- [Artifacts](../../ci/yaml/index.md#artifacts) -- [Specific runner](../../ci/runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) -- [Pipelines for merge requests](../../ci/pipelines/merge_request_pipelines.md) +See how you can use review apps to [preview your changes live](review_apps.md). ## Testing diff --git a/doc/development/documentation/redirects.md b/doc/development/documentation/redirects.md new file mode 100644 index 00000000000..eb6878f5870 --- /dev/null +++ b/doc/development/documentation/redirects.md @@ -0,0 +1,155 @@ +--- +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/#assignments +description: Learn how to contribute to GitLab Documentation. +--- + + + +# Redirects in GitLab documentation + +Moving or renaming a document is the same as changing its location. Be sure +to assign a technical writer to any merge request that renames or moves a page. +Technical Writers can help with any questions and can review your change. + +When moving or renaming a page, you must redirect browsers to the new page. +This ensures users find the new page, and have the opportunity to update their +bookmarks. + +There are two types of redirects: + +- Redirect added into the documentation files themselves, for users who + view the docs in `/help` on self-managed instances. For example, + [`/help` on GitLab.com](https://gitlab.com/help). +- [GitLab Pages redirects](../../user/project/pages/redirects.md), + for users who view the docs on [`docs.gitlab.com`](https://docs.gitlab.com). + + The Technical Writing team manages the [process](https://gitlab.com/gitlab-org/technical-writing/-/blob/main/.gitlab/issue_templates/tw-monthly-tasks.md) + to regularly update and [clean up the redirects](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/raketasks.md#clean-up-redirects). + If you're a contributor, you may add a new redirect, but you don't need to delete + the old ones. This process is automatic and handled by the Technical + Writing team. + +NOTE: +If the old page you're renaming doesn't exist in a stable branch, skip the +following steps and ask a Technical Writer to add the redirect in +[`redirects.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/content/_data/redirects.yaml). +For example, if you add a new page on the 3rd of the month and then rename it before it gets +added in the stable branch on the 18th, the old page will never be part of the internal `/help`. +In that case, you can jump straight to the +[Pages redirect](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/maintenance.md#pages-redirects). + +To add a redirect: + +1. In the repository (`gitlab`, `gitlab-runner`, `omnibus-gitlab`, or `charts`), + create a new documentation file. Don't delete the old one. The easiest + way is to copy it. For example: + + ```shell + cp doc/user/search/old_file.md doc/api/new_file.md + ``` + +1. Add the redirect code to the old documentation file by running the + following Rake task. The first argument is the path of the old file, + and the second argument is the path of the new file: + + - To redirect to a page in the same project, use relative paths and + the `.md` extension. Both old and new paths start from the same location. + In the following example, both paths are relative to `doc/`: + + ```shell + bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, doc/api/new_file.md]" + ``` + + - To redirect to a page in a different project or site, use the full URL (with `https://`) : + + ```shell + bundle exec rake "gitlab:docs:redirect[doc/user/search/old_file.md, https://example.com]" + ``` + + Alternatively, you can omit the arguments and be asked to enter their values: + + ```shell + bundle exec rake gitlab:docs:redirect + ``` + + If you don't want to use the Rake task, you can use the following template. + However, the file paths must be relative to the `doc` or `docs` directory. + + Replace the value of `redirect_to` with the new file path and `YYYY-MM-DD` + with the date the file should be removed. + + Redirect files that link to docs in internal documentation projects + are removed after three months. Redirect files that link to external sites are + removed after one year: + + ```markdown + --- + redirect_to: '../newpath/to/file/index.md' + remove_date: 'YYYY-MM-DD' + --- + + This document was moved to [another location](../path/to/file/index.md). + + + + ``` + +1. If the documentation page being moved has any Disqus comments, follow the steps + described in [Redirections for pages with Disqus comments](#redirections-for-pages-with-disqus-comments). +1. Open a merge request with your changes. If a documentation page + you're removing includes images that aren't used + with any other documentation pages, be sure to use your merge request to delete + those images from the repository. +1. Assign the merge request to a technical writer for review and merge. +1. Search for links to the old documentation file. You must find and update all + links that point to the old documentation file: + + - In , search for full URLs: + `grep -r "docs.gitlab.com/ee/path/to/file.html" .` + - In , + search the navigation bar configuration files for the path with `.html`: + `grep -r "path/to/file.html" .` + - In any of the four internal projects, search for links in the docs + and codebase. Search for all variations, including full URL and just the path. + For example, go to the root directory of the `gitlab` project and run: + + ```shell + grep -r "docs.gitlab.com/ee/path/to/file.html" . + grep -r "path/to/file.html" . + grep -r "path/to/file.md" . + grep -r "path/to/file" . + ``` + + You may need to try variations of relative links, such as `../path/to/file` or + `../file` to find every case. + +## Redirections for pages with Disqus comments + +If the documentation page being relocated already has Disqus comments, +we need to preserve the Disqus thread. + +Disqus uses an identifier per page, and for , the page identifier +is configured to be the page URL. Therefore, when we change the document location, +we need to preserve the old URL as the same Disqus identifier. + +To do that, add to the front matter the variable `disqus_identifier`, +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 information. You must +include the filename in the `disqus_identifier` URL, even if it's `index.html` or `README.html`. + +```yaml +--- +disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html' +--- +``` diff --git a/doc/development/documentation/review_apps.md b/doc/development/documentation/review_apps.md new file mode 100644 index 00000000000..2b8c412f165 --- /dev/null +++ b/doc/development/documentation/review_apps.md @@ -0,0 +1,101 @@ +--- +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/#assignments +description: Learn how documentation review apps work. +--- + +# Documentation review apps + +If you're a GitLab team member and your merge request contains documentation changes, you can use a review app to preview +how they would look if they were deployed to the [GitLab Docs site](https://docs.gitlab.com). + +Review apps are enabled for the following projects: + +- [GitLab](https://gitlab.com/gitlab-org/gitlab) +- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab) +- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) +- [GitLab Charts](https://gitlab.com/gitlab-org/charts/gitlab) + +Alternatively, check the [`gitlab-docs` development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/README.md#development-when-contributing-to-gitlab-documentation) +or [the GDK documentation](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md) +to render and preview the documentation locally. + +## How to trigger a review app + +If a merge request has documentation changes, use the `review-docs-deploy` manual job +to deploy the documentation review app for your merge request. + +![Manual trigger a documentation review app](img/manual_build_docs.png) + +The `review-docs-deploy*` job triggers a cross project pipeline and builds the +docs site with your changes. When the pipeline finishes, the review app URL +appears in the merge request widget. Use it to navigate to your changes. + +You must have the Developer role in the project. Users without the Developer role, such +as external contributors, cannot run the manual job. In that case, ask someone from +the GitLab team to run the job. + +## Technical aspects + +If you want to know the in-depth details, here's what's really happening: + +1. You manually run the `review-docs-deploy` job in a merge request. +1. The job runs the [`scripts/trigger-build`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/trigger-build) + script with the `docs deploy` flag, which triggers the "Triggered from `gitlab-org/gitlab` 'review-docs-deploy' job" + pipeline trigger in the `gitlab-org/gitlab-docs` project for the `$DOCS_BRANCH` (defaults to `main`). +1. The preview URL is shown both at the job output and in the merge request + widget. You also get the link to the remote pipeline. +1. In the `gitlab-org/gitlab-docs` project, the pipeline is created and it + [skips the test jobs](https://gitlab.com/gitlab-org/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55) + to lower the build time. +1. Once the docs site is built, the HTML files are uploaded as artifacts. +1. A specific runner tied only to the docs project, runs the Review App job + that downloads the artifacts and uses `rsync` to transfer the files over + to a location where NGINX serves them. + +The following GitLab features are used among others: + +- [Manual jobs](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) +- [Multi project pipelines](../../ci/pipelines/multi_project_pipelines.md) +- [Review Apps](../../ci/review_apps/index.md) +- [Artifacts](../../ci/yaml/index.md#artifacts) +- [Specific runner](../../ci/runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) +- [Pipelines for merge requests](../../ci/pipelines/merge_request_pipelines.md) + +## Troubleshooting review apps + +### Review app returns a 404 error + +If the review app URL returns a 404 error, either the site is not +yet deployed, or something went wrong with the remote pipeline. You can: + +- Wait a few minutes and it should appear online. +- Check the manual job's log and verify the URL. If the URL is different, try the + one from the job log. +- Check the status of the remote pipeline from the link in the merge request's job output. + If the pipeline failed or got stuck, GitLab team members can ask for help in the `#docs` + chat channel. Contributors can ping a technical writer in the merge request. + +### Not enough disk space + +Sometimes the review app server is full and there is no more disk space. Each review +app takes about 570MB of disk space. + +A cron job to remove review apps older than 20 days runs hourly, +but the disk space still occasionally fills up. To manually free up more space, +a GitLab technical writing team member can: + +1. Navigate to the [`gitlab-docs` schedules page](https://gitlab.com/gitlab-org/gitlab-docs/-/pipeline_schedules). +1. Select the play button for the `Remove old review apps from review app server` + schedule. By default, this cleans up review apps older than 14 days. +1. Navigate to the [pipelines page](https://gitlab.com/gitlab-org/gitlab-docs/-/pipelines) + and start the manual job called `clean-pages`. + +If the job says no review apps were found in that period, edit the `CLEAN_REVIEW_APPS_DAYS` +variable in the schedule, and repeat the process above. Gradually decrease the variable +until the free disk space reaches an acceptable amount (for example, 3GB). +Remember to set it to 14 again when you're done. + +There's an issue to [migrate from the DigitalOcean server to GCP buckets](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/735)), +which should solve the disk space problem. diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 046de5c6d86..cd69154217c 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -33,7 +33,6 @@ from where content is sourced, the `gitlab-docs` project, and the published outp D --> E E -- Build pipeline --> F F[docs.gitlab.com] - G[/ce/] H[/ee/] I[/runner/] J[/omnibus/] @@ -42,7 +41,6 @@ from where content is sourced, the `gitlab-docs` project, and the published outp F --> I F --> J F --> K - H -- symlink --> G ``` GitLab docs content isn't kept in the `gitlab-docs` repository. @@ -54,15 +52,6 @@ product, and all together are pulled to generate the docs website: - [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) -NOTE: -In September 2019, we [moved towards a single codebase](https://gitlab.com/gitlab-org/gitlab/-/issues/2952), -as such the docs for CE and EE are now identical. For historical reasons and -in order not to break any existing links throughout the internet, we still -maintain the CE docs (`https://docs.gitlab.com/ce/`), although it is hidden -from the website, and is now a symlink to the EE docs. When -[Support wildcard redirects](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/500) is resolved, -we can remove this completely. - ## Assets To provide an optimized site structure, design, and a search-engine friendly diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 4e548179b9e..2cbecc91b20 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -420,6 +420,11 @@ Some contractions, however, should be avoided: | Requests to localhost are not allowed. | Requests to localhost aren't allowed. | | Specified URL cannot be used. | Specified URL can't be used. | +### Acronyms + +If you use an acronym, spell it out on first use on a page. You do not need to spell it out more than once on a page. +When possible, try to avoid acronyms in headings. + ## Text - [Write in Markdown](#markdown). @@ -438,8 +443,21 @@ Some contractions, however, should be avoided: - List item 2 ``` +### Comments + +To embed comments within Markdown, use standard HTML comments that are not rendered +when published. Example: + +```html + +``` + ### Emphasis +Use **bold** rather than italic to provide emphasis. GitLab uses a sans-serif font and italic text does not stand out as much as it would in a serif font. For details, see [Butterick's Practical Typography guide on bold or italic](https://practicaltypography.com/bold-or-italic.html). + +You can use italics when you are introducing a term for the first time. Otherwise, use bold. + - Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). - Use underscore (`_`) for text in italics (`_italic_`). - Use greater than (`>`) for blockquotes. @@ -460,6 +478,7 @@ Follow these guidelines for punctuation: | Use serial commas (Oxford commas) before the final **and** or **or** in a list of three or more items. (Tested in [`OxfordComma.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml).) | You can create new issues, merge requests, and milestones. | | Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | You should try this - or not. | | When a colon is part of a sentence, always use lowercase after the colon. | Linked issues: a way to create a relationship between issues. | +| Do not use typographer's quotes. Use straight quotes instead. (Tested in [`NonStandardQuotes.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/NonStandardQuotes.yml).) | "It's the questions we can't answer that teach us the most"---Patrick Rothfuss | @@ -751,6 +770,7 @@ Valid for Markdown content only, not for front matter entries: For other punctuation rules, refer to the [Pajamas Design System Punctuation section](https://design.gitlab.com/content/punctuation/). +This is overridden by the [documentation-specific punctuation rules](#punctuation). ## Headings @@ -1003,9 +1023,23 @@ document to ensure it links to the most recent version of the file. ## Navigation -When documenting navigation through the user interface, use these terms and styles. +When documenting how to navigate through the GitLab UI: + +- Always use location, then action. + - `From the **Visibility** list,` (location) `select **Public**.` (action) +- Be brief and specific. For example: + - Avoid: `Select **Save** for the changes to take effect.` + - Use instead: `Select **Save**.` +- When selecting from high-level UI elements, use the word **on**. + - Avoid: `From the left sidebar...` or `In the left sidebar...` + - Use instead: `On the left sidebar...` +- If a step must include a reason, start the step with it. + - Avoid: `Select the link in the merge request to view the changes.` + - Use instead: `To view the changes, select the link in the merge request.` +- If a step is optional, start the step with the word `Optional` followed by a period. + - `1. Optional. Enter a name for the dog.` -### What to call the menus +### Names for menus Use these terms when referring to the main GitLab user interface elements: @@ -1017,9 +1051,14 @@ elements: - **Right sidebar**: This is the navigation sidebar on the right of the user interface, specific to the open issue, merge request, or epic. -### How to document the menus +### Names for UI elements -To be consistent, use this format when you write about UI navigation. +UI elements, like button and checkbox names, should be **bold**. +Guidance for each individual UI element is in [the word list](word_list.md). + +### How to write navigation task steps + +To be consistent, use this format when you write navigation steps in a task topic. 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. @@ -1034,20 +1073,27 @@ Another example: An Admin Area example: ```markdown -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. ``` -This text renders this output: +To select your avatar: -1. On the top bar, select **Menu >** **{admin}** **Admin**. +```markdown +1. On the top bar, in the top right corner, select your avatar. +``` ## Images Images, including screenshots, can help a reader better understand a concept. -However, they can be hard to maintain, and should be used sparingly. +However, they should be used sparingly because: -Before including an image in the documentation, ensure it provides value to the -reader. +- They tend to become out-of-date. +- They are difficult and expensive to localize. +- They cannot be read by screen readers. + +If you do include an image in the documentation, ensure it provides value. +Don't use `lorem ipsum` text. Try to replicate how the feature would be +used in a real-world scenario, and [use realistic text](#fake-user-information). ### Capture the image @@ -1106,7 +1152,7 @@ known tool is [`pngquant`](https://pngquant.org/), which is cross-platform and open source. Install it by visiting the official website and following the instructions for your OS. -GitLab has a [Rake task](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/tasks/pngquant.rake) +GitLab has a [Ruby script](https://gitlab.com/gitlab-org/gitlab/-/blob/master/bin/pngquant) that you can use to automate the process. In the root directory of your local copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: @@ -1114,19 +1160,26 @@ copy of `https://gitlab.com/gitlab-org/gitlab`, run in a terminal: been compressed: ```shell - bundle exec rake pngquant:lint + bin/pngquant lint ``` - Compress all documentation PNG images using `pngquant`: ```shell - bundle exec rake pngquant:compress + bin/pngquant compress + ``` + +- Compress specific files: + + ```shell + bin/pngquant compress doc/user/img/award_emoji_select.png doc/user/img/markdown_logo.png ``` -The only caveat is that the task runs on all images under `doc/`, not only the -ones you might have included in a merge request. In that case, you can run the -compress task and only commit the images that are relevant to your merge -request. +- Compress all PNG files in a specific directory: + + ```shell + bin/pngquant compress doc/user/img + ``` ## Videos @@ -1288,64 +1341,22 @@ For a complete reference on code blocks, see the [Kramdown guide](https://about. > [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7. You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) -directly in the documentation. - -This way, you can achieve a consistent look when writing about interacting with -GitLab user interface elements. - -Usage examples: - -- Icon with default size (16px): `**{icon-name}**` +directly in the documentation. For example, `**{tanuki}**` renders as: **{tanuki}**. - Example: `**{tanuki}**` renders as: **{tanuki}**. -- Icon with custom size: `**{icon-name, size}**` +In most cases, you should avoid using the icons in text. +However, you can use an icon when hover text is the only +available way to describe a UI element. For example, **Delete** or **Edit** buttons +often have hover text only. - Available sizes (in pixels): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72 +When you do use an icon, start with the hover text and follow it with the SVG reference in parentheses. - Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**. -- Icon with custom size and class: `**{icon-name, size, class-name}**`. +- Avoid: `Select **{pencil}** **Edit**.` This generates as: Select **{pencil}** **Edit**. +- Use instead: `Select **Edit** (**{pencil}**).` This generates as: Select **Edit** (**{pencil}**). - You can access any class available to this element in GitLab documentation CSS. +Do not use words to describe the icon: - Example with `float-right`, a - [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/): - `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}** - -### When to use icons - -Icons should be used sparingly, and only in ways that aid and do not hinder the -readability of the text. - -For example, this Markdown adds little to the accompanying text: - -```markdown -1. Go to **{home}** **Project information > Details**. -``` - -1. Go to **{home}** **Project information > Details**. - -However, these tables might help the reader connect the text to the user -interface: - -```markdown -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | -``` - -| Section | Description | -|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------| -| **{overview}** Overview | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers. | -| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. | -| **{messages}** Messages | Send and manage broadcast messages for your users. | - -Use an icon when you find yourself having to describe an interface element. For -example: - -- Do: Select the Admin Area icon ( **{admin}** ). -- Don't: Select the Admin Area icon (the wrench icon). +- Avoid: `Select **Erase job log** (the trash icon).` +- Use instead: `Select **Erase job log** (**{remove}**).` This generates as: Select **Erase job log** (**{remove}**). ## Alert boxes @@ -1456,27 +1467,9 @@ Follow these styles when you're describing user interface elements in an application: - For elements with a visible label, use that label in bold with matching case. - For example, `the **Cancel** button`. + For example, `Select **Cancel**`. - For elements with a tooltip or hover label, use that label in bold with - matching case. For example, `the **Add status emoji** button`. - -### Verbs for UI elements - -Use these verbs for specific uses with user interface -elements: - -| Recommended | Used for | Replaces | -|:--------------------|:--------------------------------------|:----------------------| -| select | buttons, links, menu items, dropdowns | click, press, hit | -| select or clear | checkboxes | enable, click, press | -| expand | expandable sections | open | -| turn on or turn off | toggles | flip, enable, disable | - -### Other Verbs - -| Recommended | Used for | Replaces | -|:------------|:--------------------------------|:----------------------| -| go to | making a browser go to location | navigate to, open | + matching case. For example, `Select **Add status emoji**`. ## GitLab versions @@ -1504,10 +1497,6 @@ tagged and released set of documentation for your installed version: When a feature is added or updated, you can include its version information either as a **Version history** item or as an inline text reference. -Version text shouldn't include information about the tier in which the feature -is available. This information is provided by the [product badge](#product-tier-badges) -displayed for the page or feature. - #### Version text in the **Version History** If all content in a section is related, add version text after the header for @@ -1523,6 +1512,10 @@ the section. The version information must: - Whenever possible, include a link to the completed issue, merge request, or epic that introduced the feature. An issue is preferred over a merge request, and a merge request is preferred over an epic. +- Do not include information about the tier, unless documenting a tier change + (for example, `Feature X [moved](issue-link) to Premium in GitLab 19.2`). +- Do not link to the pricing page. + The tier is provided by the [product badge](#product-tier-badges) on the heading. ```markdown ## Feature name @@ -1647,37 +1640,24 @@ When names change, it is more complicated to search or grep text that has line b ### Product tier badges -Tier badges are displayed as orange text next to a heading. For example: +Tier badges are displayed as orange text next to a heading. These badges link to the GitLab +pricing page. For example: ![Tier badge](img/tier_badge.png) You must assign a tier badge: -- To [all H1 topic headings](#product-tier-badges-on-headings). +- To all H1 topic headings. - To topic headings that don't apply to the same tier as the H1. -- To [sections of a topic](#product-tier-badges-on-other-content), - if they apply to a tier other than what applies to the H1. - -#### Product tier badges on headings -To add a tier badge to a heading, add the relevant [tier badge](#available-product-tier-badges) +To add a tier badge to a heading, add the relevant tier badge after the heading text. For example: ```markdown # Heading title **(FREE)** ``` -#### Product tier badges on other content - -In paragraphs, list names, and table cells, an information icon displays when you -add a tier badge. More verbose information displays when a user points to the icon: - -- `**(FREE)**` displays as **(FREE)** -- `**(FREE SELF)**` displays as **(FREE SELF)** -- `**(FREE SAAS)**` displays as **(FREE SAAS)** - -The `**(FREE)**` generates a `span` element to trigger the -badges and tooltips (``). +Do not add tier badges inline with other text. The single source of truth for a feature should be the heading where the functionality is described. #### Available product tier badges diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 9e921bb30f0..eafe0e7a1c2 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -17,15 +17,17 @@ For guidance not on this page, we defer to these style guides: -## @mention +## `@mention` -Try to avoid. Say "mention" instead, and consider linking to the +Try to avoid **`@mention`**. Say **mention** instead, and consider linking to the [mentions topic](../../../user/project/issues/issue_data_and_actions.md#mentions). -Don't use `code formatting`. +Don't use backticks. ## above -Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **previously** instead. +Try to avoid using **above** when referring to an example or table in a documentation page. If required, use **previous** instead. For example: + +- In the previous example, the dog had fleas. ## admin, admin area @@ -33,55 +35,111 @@ Use **administration**, **administrator**, **administer**, or **Admin Area** ins ## allow, enable -Try to avoid, unless you are talking about security-related features. For example: +Try to avoid **allow** and **enable**, unless you are talking about security-related features. For example: -- Avoid: This feature allows you to create a pipeline. -- Use instead: Use this feature to create a pipeline. +- Do: Use this feature to create a pipeline. +- Do not: This feature allows you to create a pipeline. This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. [View details in the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). ## Alpha -Uppercase. For example: **The XYZ feature is in Alpha.** or **This Alpha release is ready to test.** +Use uppercase for **Alpha**. For example: **The XYZ feature is in Alpha.** or **This Alpha release is ready to test.** You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) in the handbook when writing about Alpha features. ## and/or -Instead of **and/or**, use or or rewrite the sentence to spell out both options. +Instead of **and/or**, use **or** or rewrite the sentence to spell out both options. + +## area + +Use [**section**](#section) instead of **area**. The only exception is [the Admin Area](#admin-admin-area). ## below -Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead. +Try to avoid **below** when referring to an example or table in a documentation page. If required, use **following** instead. For example: + +- In the following example, the dog has fleas. ## Beta -Uppercase. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** +Use uppercase for **Beta**. For example: **The XYZ feature is in Beta.** or **This Beta release is ready to test.** You might also want to link to [this section](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) in the handbook when writing about Beta features. ## blacklist -Do not use. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +Do not use **blacklist**. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## board Use lowercase for **boards**, **issue boards**, and **epic boards**. +## box + +Use **text box** to refer to the UI field. Do not use **field** or **box**. For example: + +- In the **Variable name** text box, enter `my text`. + +## button + +Don't use a descriptor with **button**. + +- Do: Select **Run pipelines**. +- Do not: Select the **Run pipelines** button. + +## cannot, can not + +Use **cannot** instead of **can not**. You can also use **can't**. + +See also [contractions](index.md#contractions). + ## checkbox -One word, **checkbox**. Do not use **check box**. +Use one word for **checkbox**. Do not use **check box**. + +You **select** (not **check** or **enable**) and **clear** (not **deselect** or **disable**) checkboxes. +For example: + +- Select the **Protect environment** checkbox. +- Clear the **Protect environment** checkbox. + +If you must refer to the checkbox, you can say it is selected or cleared. For example: + +- Ensure the **Protect environment** checkbox is cleared. +- Ensure the **Protect environment** checkbox is selected. ## CI/CD -Always uppercase. No need to spell out on first use. +CI/CD is always uppercase. No need to spell it out on first use. + +## click + +Do not use **click**. Instead, use **select** with buttons, links, menu items, and lists. +**Select** applies to more devices, while **click** is more specific to a mouse. + +## collapse + +Use **collapse** instead of **close** when you are talking about expanding or collapsing a section in the UI. + +## confirmation dialog + +Use **confirmation dialog** to describe the dialog box that asks you to confirm your action. For example: + +- On the confirmation dialog, select **OK**. ## currently -Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) +Do not use **currently** when talking about the product or its features. The documentation describes the product as it is today. +([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml)) + +## deploy board + +Use lowercase for **deploy board**. ## Developer @@ -92,26 +150,35 @@ When writing about the Developer role: - Do not use the phrase, **if you are a developer** to mean someone who is assigned the Developer role. Instead, write it out. For example, **if you are assigned the Developer role**. - To describe a situation where the Developer role is the minimum required: - - Avoid: **the Developer role or higher** - - Use instead: **at least the Developer role** + - Avoid: the Developer role or higher + - Use instead: at least the Developer role Do not use **Developer permissions**. A user who is assigned the Developer role has a set of associated permissions. ## disable -See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance. +See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance on **disable**. Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) +## dropdown list + +Use **dropdown list** to refer to the UI element. Do not use **dropdown** without **list** after it. +Do not use **drop-down** (hyphenated), **dropdown menu**, or other variants. + +For example: + +- From the **Visibility** dropdown list, select **Public**. + ## earlier -Use when talking about version numbers. +Use **earlier** when talking about version numbers. -- Avoid: In GitLab 14.1 and lower. -- Use instead: In GitLab 14.1 and earlier. +- Do: In GitLab 14.1 and earlier. +- Do not: In GitLab 14.1 and lower. ## easily -Do not use. If the user doesn't find the process to be easy, we lose their trust. +Do not use **easily**. If the user doesn't find the process to be easy, we lose their trust. ## e.g. @@ -119,60 +186,75 @@ Do not use Latin abbreviations. Use **for example**, **such as**, **for instance ## email -Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**. +Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) ## enable -See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance. +See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance on **enable**. Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) +## enter + +Use **enter** instead of **type** when talking about putting values into text boxes. + ## epic -Lowercase. +Use lowercase for **epic**. ## epic board -Lowercase. +Use lowercase for **epic board**. ## etc. -Try to avoid. Be as specific as you can. Do not use **and so on** as a replacement. +Try to avoid **etc.**. Be as specific as you can. Do not use **and so on** as a replacement. -- Avoid: You can update objects, like merge requests, issues, etc. -- Use instead: You can update objects, like merge requests and issues. +- Do: You can update objects, like merge requests and issues. +- Do not: You can update objects, like merge requests, issues, etc. + +## expand + +Use **expand** instead of **open** when you are talking about expanding or collapsing a section in the UI. + +## field + +Use **box** instead of **field** or **text box**. + +- Avoid: In the **Variable name** field, enter `my text`. +- Use instead: In the **Variable name** box, enter `my text`. ## foo -Do not use in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. +Do not use **foo** in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead. ## future tense -When possible, use present tense instead. For example, use `after you execute this command, GitLab displays the result` instead of `after you execute this command, GitLab will display the result`. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) +When possible, use present tense instead of future tense. For example, use **after you execute this command, GitLab displays the result** instead of **after you execute this command, GitLab will display the result**. ([Vale](../testing.md#vale) rule: [`FutureTense.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FutureTense.yml)) ## Geo -Title case. +Use title case for **Geo**. ## GitLab -Do not make possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/). +Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trademark Guidelines](https://about.gitlab.com/handbook/marketing/corporate-marketing/brand-activation/trademark-guidelines/). ## GitLab.com -Refers to the GitLab instance managed by GitLab itself. +**GitLab.com** refers to the GitLab instance managed by GitLab itself. ## GitLab SaaS -Refers to the product license that provides access to GitLab.com. Does not refer to the +**GitLab SaaS** refers to the product license that provides access to GitLab.com. It does not refer to the GitLab instance managed by GitLab itself. ## GitLab Runner -Title case. This is the product you install. See also [runners](#runner-runners) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). +Use title case for **GitLab Runner**. This is the product you install. See also [runners](#runner-runners) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). ## GitLab self-managed -Refers to the product license for GitLab instances managed by customers themselves. +Use **GitLab self-managed** to refer to the product license for GitLab instances managed by customers themselves. ## Guest @@ -183,25 +265,32 @@ When writing about the Guest role: - Do not use the phrase, **if you are a guest** to mean someone who is assigned the Guest role. Instead, write it out. For example, **if you are assigned the Guest role**. - To describe a situation where the Guest role is the minimum required: - - Avoid: **the Guest role or higher** - - Use instead: **at least the Guest role** + - Avoid: the Guest role or higher + - Use instead: at least the Guest role Do not use **Guest permissions**. A user who is assigned the Guest role has a set of associated permissions. ## handy -Do not use. If the user doesn't find the feature or process to be handy, we lose their trust. +Do not use **handy**. If the user doesn't find the feature or process to be handy, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) ## high availability, HA -Do not use. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. +Do not use **high availability** or **HA**. Instead, direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) for information about configuring GitLab for handling greater amounts of users. ## higher -Do not use when talking about version numbers. +Do not use **higher** when talking about version numbers. -- Avoid: In GitLab 14.1 and higher. -- Use instead: In GitLab 14.1 and later. +- Do: In GitLab 14.1 and later. +- Do not: In GitLab 14.1 and higher. + +## hit + +Don't use **hit** to mean **press**. + +- Avoid: Hit the **ENTER** button. +- Use instead: Press **ENTER**. ## I @@ -213,19 +302,19 @@ Do not use Latin abbreviations. Use **that is** instead. ([Vale](../testing.md#v ## in order to -Do not use. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) +Do not use **in order to**. Use **to** instead. ([Vale](../testing.md#vale) rule: [`Wordy.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Wordy.yml)) ## issue -Lowercase. +Use lowercase for **issue**. ## issue board -Lowercase. +Use lowercase for **issue board**. ## issue weights -Lowercase. +Use lowercase for **issue weights**. ## job @@ -235,21 +324,26 @@ If you want to use **CI** with the word **job**, use **CI/CD job** rather than * ## later -Use when talking about version numbers. +Use **later** when talking about version numbers. - Avoid: In GitLab 14.1 and higher. - Use instead: In GitLab 14.1 and later. +## list + +Do not use **list** when referring to a [**dropdown list**](#dropdown-list). +Use the full phrase **dropdown list** instead. + ## log in, log on -Do not use. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it. +Do not use **log in** or **log on**. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it. ## lower -Do not use when talking about version numbers. +Do not use **lower** when talking about version numbers. -- Avoid: In GitLab 14.1 and lower. -- Use instead: In GitLab 14.1 and earlier. +- Do: In GitLab 14.1 and earlier. +- Do not: In GitLab 14.1 and lower. ## Maintainer @@ -260,22 +354,22 @@ When writing about the Maintainer role: - Do not use the phrase, **if you are a maintainer** to mean someone who is assigned the Maintainer role. Instead, write it out. For example, **if you are assigned the Maintainer role**. - To describe a situation where the Maintainer role is the minimum required: - - Avoid: **the Maintainer role or higher** - - Use instead: **at least the Maintainer role** + - Avoid: the Maintainer role or higher + - Use instead: at least the Maintainer role Do not use **Maintainer permissions**. A user who is assigned the Maintainer role has a set of associated permissions. ## mankind -Do not use. Use **people** or **humanity** instead. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) +Do not use **mankind**. Use **people** or **humanity** instead. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) ## manpower -Do not use. Use words like **workforce** or **GitLab team members**. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) +Do not use **manpower**. Use words like **workforce** or **GitLab team members**. ([Vale](../testing.md#vale) rule: [`InclusionGender.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionGender.yml)) ## master -Do not use. Options are **primary** or **main**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +Do not use **master**. Options are **primary** or **main**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## may, might @@ -287,18 +381,25 @@ Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale ## merge requests -Lowercase. If you use **MR** as the acronym, spell it out on first use. +Use lowercase for **merge requests**. If you use **MR** as the acronym, spell it out on first use. ## milestones -Lowercase. +Use lowercase for **milestones**. + +## navigate + +Do not use **navigate**. Use **go** instead. For example: + +- Go to this webpage. +- Open a terminal and go to the `runner` directory. ## need to, should -Try to avoid. If something is required, use **must**. +Try to avoid **needs to**, because it's wordy. Avoid **should** when you can be more specific. If something is required, use **must**. -- Avoid: You need to set the variable. -- Use instead: You must set the variable. Or: Set the variable. +- Do: You must set the variable. Or: Set the variable. +- Do not: You need to set the variable. **Should** is acceptable for recommended actions or items, or in cases where an event may not happen. For example: @@ -310,10 +411,10 @@ happen. For example: ## note that -Do not use. +Do not use **note that** because it's wordy. -- Avoid: Note that you can change the settings. -- Use instead: You can change the settings. +- Do: You can change the settings. +- Do not: Note that you can change the settings. ## Owner @@ -328,15 +429,21 @@ Do not use **Owner permissions**. A user who is assigned the Owner role has a se ## permissions -Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. +Do not use **roles** and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. ## please -Do not use. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +Do not use **please**. For details, see the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). + +## press + +Use **press** when talking about keyboard keys. For example: + +- To stop the command, press Control+C. ## profanity -Do not use. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). +Do not use profanity. Doing so may negatively affect other users and contributors, which is contrary to the GitLab value of [Diversity, Inclusion, and Belonging](https://about.gitlab.com/handbook/values/#diversity-inclusion). ## Reporter @@ -347,30 +454,48 @@ When writing about the Reporter role: - Do not use the phrase, **if you are a reporter** to mean someone who is assigned the Reporter role. Instead, write it out. For example, **if you are assigned the Reporter role**. - To describe a situation where the Reporter role is the minimum required: - - Avoid: **the Reporter role or higher** - - Use instead: **at least the Reporter role** + - Avoid: the Reporter role or higher + - Use instead: at least the Reporter role Do not use **Reporter permissions**. A user who is assigned the Reporter role has a set of associated permissions. ## Repository Mirroring -Title case. +Use title case for **Repository Mirroring**. ## roles -Do not use roles and permissions interchangeably. Each user is assigned a role. Each role includes a set of permissions. +Do not use **roles** and **permissions** interchangeably. Each user is assigned a role. Each role includes a set of permissions. ## runner, runners -Lowercase. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). +Use lowercase for **runners**. These are the agents that run CI/CD jobs. See also [GitLab Runner](#gitlab-runner) and [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/233529). ## sanity check -Do not use. Use **check for completeness** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) +Do not use **sanity check**. Use **check for completeness** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) ## scalability -Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. +Do not use **scalability** when talking about increasing GitLab performance for additional users. The words scale or scaling +are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers +to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page. + +## section + +Use **section** to describe an area on a page. For example, if a page has lines that separate the UI +into separate areas, refer to these areas as sections. + +We often think of expandable/collapsible areas as **sections**. When you refer to expanding +or collapsing a section, don't include the word **section**. + +- Do: Expand **Auto DevOps**. +- Do not: Expand the **Auto DevOps** section. + +## select + +Use **select** with buttons, links, menu items, and lists. **Select** applies to more devices, +while **click** is more specific to a mouse. ## setup, set up @@ -381,13 +506,13 @@ Use **setup** as a noun, and **set up** as a verb. For example: ## sign in -Use instead of **sign on** or **log on** or **log in**. If the user interface has different words, use those. +Use **sign in** instead of **sign on** or **log on** or **log in**. If the user interface has different words, use those. You can use **single sign-on**. ## simply, simple -Do not use. If the user doesn't find the process to be simple, we lose their trust. +Do not use **simply** or **simple**. If the user doesn't find the process to be simple, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) ## slashes @@ -395,34 +520,38 @@ Instead of **and/or**, use **or** or re-write the sentence. This rule also appli ## slave -Do not use. Another option is **secondary**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +Do not use **slave**. Another option is **secondary**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) ## subgroup -Use instead of **sub-group**. +Use **subgroup** (no hyphen) instead of **sub-group**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) ## that -Do not use when describing a noun. For example: +Do not use **that** when describing a noun. For example: -- Avoid: The file **that** you save... -- Use instead: The file you save... +- Do: The file you save... +- Do not: The file **that** you save... See also [this, these, that, those](#this-these-that-those). ## terminal -Lowercase. For example: +Use lowercase for **terminal**. For example: - Open a terminal. - From a terminal, run the `docker login` command. +## text box + +Use **text box** instead of **field** or **box** when referring to the UI element. + ## there is, there are -Try to avoid. These phrases hide the subject. +Try to avoid **there is** and **there are**. These phrases hide the subject. -- Avoid: There are holes in the bucket. -- Use instead: The bucket has holes. +- Do: The bucket has holes. +- Do not: There are holes in the bucket. ## they @@ -434,37 +563,48 @@ a gender-neutral pronoun. Always follow these words with a noun. For example: -- Avoid: **This** improves performance. -- Use instead: **This setting** improves performance. +- Do: **This setting** improves performance. +- Do not: **This** improves performance. -- Avoid: **These** are the best. -- Use instead: **These pants** are the best. +- Do: **These pants** are the best. +- Do not: **These** are the best. -- Avoid: **That** is the one you are looking for. -- Use instead: **That Jedi** is the one you are looking for. +- Do: **That droid** is the one you are looking for. +- Do not: **That** is the one you are looking for. -- Avoid: **Those** need to be configured. -- Use instead: **Those settings** need to be configured. (Or even better, **Configure those settings.**) +- Do: **Those settings** need to be configured. (Or even better, **Configure those settings.**) +- Do not: **Those** need to be configured. ## to-do item -Use lowercase. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) +Use lowercase and hyphenate **to-do** item. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) ## To-Do List -Use title case. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) +Use title case for **To-Do List**. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml)) + +## toggle + +You **turn on** or **turn off** a toggle. For example: + +- Turn on the **blah** toggle. + +## type + +Do not use **type** if you can avoid it. Use **enter** instead. ## useful -Do not use. If the user doesn't find the process to be useful, we lose their trust. +Do not use **useful**. If the user doesn't find the process to be useful, we lose their trust. ([Vale](../testing.md#vale) rule: [`Simplicity.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Simplicity.yml)) ## utilize -Do not use. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. +Do not use **utilize**. Use **use** instead. It's more succinct and easier for non-native English speakers to understand. +([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) ## Value Stream Analytics -Title case. +Use title case for **Value Stream Analytics**. ## via @@ -474,14 +614,14 @@ Do not use Latin abbreviations. Use **with**, **through**, or **by using** inste Try to avoid **we** and focus instead on how the user can accomplish something in GitLab. -- Avoid: We created a feature for you to add widgets. -- Instead, use: Use widgets when you have work you want to organize. +- Do: Use widgets when you have work you want to organize. +- Do not: We created a feature for you to add widgets. -One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**. +One exception: You can use **we recommend** instead of **it is recommended** or **GitLab recommends**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) ## whitelist -Do not use. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) +Do not use **whitelist**. Another option is **allowlist**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml)) diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index 2ade6c1e71d..dfa2f3ed55a 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -228,7 +228,7 @@ guidelines: In [`ReadingLevel.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ReadingLevel.yml), we have implemented -[the Flesch-Kincaid grade level test](https://readable.com/blog/the-flesch-reading-ease-and-flesch-kincaid-grade-level/) +[the Flesch-Kincaid grade level test](https://readable.com/readability/flesch-reading-ease-flesch-kincaid-grade-level/) to determine the readability of our documentation. As a general guideline, the lower the score, the more readable the documentation. @@ -319,6 +319,38 @@ To configure Vale in your editor, install one of the following as appropriate: cases, `vale` should work. To find the location, run `which vale` in a terminal. - Vim [ALE plugin](https://github.com/dense-analysis/ale). +- Emacs [Flycheck extension](https://github.com/flycheck/flycheck). + This requires some configuration: + + - `Flycheck` supports `markdownlint-cli` out of the box, but you must point it + to the `.markdownlint.yml` at the base of the project directory. A `.dir-locals.el` + file can accomplish this: + + ```lisp + ;; Place this code in a file called `.dir-locals.el` at the root of the gitlab project. + ((markdown-mode . ((flycheck-markdown-markdownlint-cli-config . ".markdownlint.yml")))) + + ``` + + - A minimal configuration for Flycheck to work with Vale could look like this: + + ```lisp + (flycheck-define-checker vale + "A checker for prose" + :command ("vale" "--output" "line" "--no-wrap" + source) + :standard-input nil + :error-patterns + ((error line-start (file-name) ":" line ":" column ":" (id (one-or-more (not (any ":")))) ":" (message) line-end)) + :modes (markdown-mode org-mode text-mode) + :next-checkers ((t . markdown-markdownlint-cli)) + ) + + (add-to-list 'flycheck-checkers 'vale) + ``` + + In this setup the `markdownlint` checker is set as a "next" checker from the defined `vale` checker. + Enabling this custom Vale checker provides error linting from both Vale and markdownlint. We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 4b87f1c28f1..bba4e1cda23 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w This area is to maintain a compendium of useful information when working with Elasticsearch. Information on how to enable Elasticsearch and perform the initial indexing is in -the [Elasticsearch integration documentation](../integration/elasticsearch.md#enabling-advanced-search). +the [Elasticsearch integration documentation](../integration/elasticsearch.md#enable-advanced-search). ## Deep Dive @@ -233,6 +233,11 @@ Any data or index cleanup needed to support migration retries should be handled will re-enqueue itself with a delay which is set using the `throttle_delay` option described below. The batching must be handled within the `migrate` method, this setting controls the re-enqueuing only. +- `batch_size` - Sets the number of documents modified during a `batched!` migration run. This size should be set to a value which allows the updates + enough time to finish. This can be tuned in combination with the `throttle_delay` option described below. The batching + must be handled within a custom `migrate` method or by using the [`Elastic::MigrationBackfillHelper`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/workers/concerns/elastic/migration_backfill_helper.rb) + `migrate` method which uses this setting. Default value is 1000 documents. + - `throttle_delay` - Sets the wait time in between batch runs. This time should be set high enough to allow each migration batch enough time to finish. Additionally, the time should be less than 30 minutes since that is how often the [`Elastic::MigrationWorker`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/workers/elastic/migration_worker.rb) diff --git a/doc/development/experiment_guide/experimentation.md b/doc/development/experiment_guide/experimentation.md index ee0f63342f1..b242646c549 100644 --- a/doc/development/experiment_guide/experimentation.md +++ b/doc/development/experiment_guide/experimentation.md @@ -106,7 +106,7 @@ class SomeWorker # Since we cannot access cookies in a worker, we need to bucket models # based on a unique, unchanging attribute instead. - # It is therefore necessery to always provide the same subject. + # It is therefore necessary to always provide the same subject. if Gitlab::Experimentation.in_experiment_group?(:experiment_key, subject: user) # execute experimental code else diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index e4a97091a81..4de272fec20 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -8,11 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w Experiments can be conducted by any GitLab team, most often the teams from the [Growth Sub-department](https://about.gitlab.com/handbook/engineering/development/growth/). Experiments are not tied to releases because they primarily target GitLab.com. -Experiments are run as an A/B/n test, and are behind a feature flag to turn the test on or off. Based on the data the experiment generates, the team decides if the experiment had a positive impact and should be made the new default, or rolled back. +Experiments are run as an A/B/n test, and are behind an [experiment feature flag](../feature_flags/#experiment-type) to turn the test on or off. Based on the data the experiment generates, the team decides if the experiment had a positive impact and should be made the new default, or rolled back. -## Experiment tracking issue +## Experiment rollout issue -Each experiment should have an [Experiment tracking](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&state=opened&label_name[]=growth%20experiment&search=%22Experiment+tracking%22) issue to track the experiment from roll-out through to cleanup/removal. The tracking issue is similar to a feature flag rollout issue, and is also used to track the status of an experiment. Immediately after an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). +Each experiment should have an [experiment rollout](https://gitlab.com/groups/gitlab-org/-/boards/1352542) issue to track the experiment from rollout through to cleanup and removal. +The rollout issue is similar to a feature flag rollout issue, and is also used to track the status of an experiment. +When an experiment is deployed, the due date of the issue should be set (this depends on the experiment but can be up to a few weeks in the future). After the deadline, the issue needs to be resolved and either: - It was successful and the experiment becomes the new default. @@ -29,6 +31,10 @@ run) shouldn't impact GitLab availability. To avoid or identify issues, experiments are initially deployed to a small number of users. Regardless, experiments still need tests. +Experiments must have corresponding [frontend or feature tests](../testing_guide/index.md) to ensure they +exist in the application. These tests should help prevent the experiment code from +being removed before the [experiment cleanup process](https://about.gitlab.com/handbook/engineering/development/growth/experimentation/#experiment-cleanup-issue) starts. + If, as a reviewer or maintainer, you find code that would usually fail review but is acceptable for now, mention your concerns with a note that there's no need to change the code. The author can then add a comment to this piece of code @@ -38,22 +44,14 @@ addressed. ## Implementing an experiment -There are currently two options when implementing an experiment. - -One is built into GitLab directly and has been around for a while (this is called -`Exerimentation Module`), and the other is provided by -[`gitlab-experiment`](https://gitlab.com/gitlab-org/gitlab-experiment) and is referred -to as `Gitlab::Experiment` -- GLEX for short. +[`GLEX`](https://gitlab.com/gitlab-org/gitlab-experiment) - or `Gitlab::Experiment`, the `gitlab-experiment` gem - is the preferred option for implementing an experiment in GitLab. -Both approaches use [experiment](../feature_flags/index.md#experiment-type) -feature flags. We recommend using GLEX rather than `Experimentation Module` for new experiments. +For more information, see [Implementing an A/B/n experiment using GLEX](gitlab_experiment.md). -- [Implementing an A/B/n experiment using GLEX](gitlab_experiment.md) -- [Implementing an A/B experiment using `Experimentation Module`](experimentation.md) +There are still some longer running experiments using the [`Exerimentation Module`](experimentation.md). -Historical Context: `Experimentation Module` was built iteratively with the needs that -appeared while implementing Growth sub-department experiments, while GLEX was built -with the findings of the team and an easier to use API. +Both approaches use [experiment](../feature_flags/index.md#experiment-type) feature flags. +`GLEX` is the preferred option for new experiments. ### Add new icons and illustrations for experiments diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index 0cd7cf58b58..7c870de9a6c 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.md @@ -334,7 +334,7 @@ Keep in mind that: - When you add `:hover` styles, in most cases you should add `:focus` styles too so that the styling is applied for both mouse **and** keyboard users. - If you remove an interactive element's `outline`, make sure you maintain visual focus state in another way such as with `box-shadow`. -See the [Pajamas Keyboard-only page](https://design.gitlab.com/accessibility-audits/2-keyboard-only/) for more detail. +See the [Pajamas Keyboard-only page](https://design.gitlab.com/accessibility-audits/keyboard-only) for more detail. ## Tabindex @@ -510,7 +510,7 @@ Proper research and testing should be done to ensure compliance with [WCAG](http ### Viewing the browser accessibility tree - [Firefox DevTools guide](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector#accessing_the_accessibility_inspector) -- [Chrome DevTools guide](https://developer.chrome.com/docs/devtools/accessibility/reference#pane) +- [Chrome DevTools guide](https://developer.chrome.com/docs/devtools/accessibility/reference/#pane) ### Browser extensions diff --git a/doc/development/fe_guide/axios.md b/doc/development/fe_guide/axios.md index 2d699b305ce..b42a17d7870 100644 --- a/doc/development/fe_guide/axios.md +++ b/doc/development/fe_guide/axios.md @@ -75,7 +75,7 @@ We have also decided against using [Axios interceptors](https://github.com/axios ### Mock poll requests in tests with Axios -Because polling function requires a header object, we need to always include an object as the third argument: +Because a polling function requires a header object, we need to always include an object as the third argument: ```javascript mock.onGet('/users').reply(200, { foo: 'bar' }, {}); diff --git a/doc/development/fe_guide/content_editor.md b/doc/development/fe_guide/content_editor.md index 6cf4076bf83..956e7d0d56e 100644 --- a/doc/development/fe_guide/content_editor.md +++ b/doc/development/fe_guide/content_editor.md @@ -4,10 +4,10 @@ group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Content Editor **(FREE)** +# Content Editor development guidelines **(FREE)** The Content Editor is a UI component that provides a WYSIWYG editing -experience for [GitLab Flavored Markdown](../../user/markdown.md) (GFM) in the GitLab application. +experience for [GitLab Flavored Markdown](../../user/markdown.md) in the GitLab application. It also serves as the foundation for implementing Markdown-focused editors that target other engines, like static site generators. @@ -16,103 +16,339 @@ to build the Content Editor. These frameworks provide a level of abstraction on the native [`contenteditable`](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content) web technology. -## Architecture remarks +## Usage guide -At a high level, the Content Editor: +Follow these instructions to include the Content Editor in a feature. -- Imports arbitrary Markdown. -- Renders it in a HTML editing area. -- Exports it back to Markdown with changes introduced by the user. +1. [Include the Content Editor component](#include-the-content-editor-component). +1. [Set and get Markdown](#set-and-get-markdown). +1. [Listen for changes](#listen-for-changes). -The Content Editor relies on the -[Markdown API endpoint](../../api/markdown.md) to transform Markdown -into HTML. It sends the Markdown input to the REST API and displays the API's -HTML output in the editing area. The editor exports the content back to Markdown -using a client-side library that serializes editable documents into Markdown. +### Include the Content Editor component -![Content Editor high level diagram](img/content_editor_highlevel_diagram.png) +Import the `ContentEditor` Vue component. We recommend using asynchronous named imports to +take advantage of caching, as the ContentEditor is a big dependency. -Check the [Content Editor technical design document](https://docs.google.com/document/d/1fKOiWpdHned4KOLVOOFYVvX1euEjMP5rTntUhpapdBg) -for more information about the design decisions that drive the development of the editor. - -**NOTE**: We also designed the Content Editor to be extensible. We intend to provide -more information about extension development for supporting new types of content in upcoming -milestones. - -## GitLab Flavored Markdown support +```html + +``` -The [GitLab Flavored Markdown](../../user/markdown.md) extends -the [CommonMark specification](https://spec.commonmark.org/0.29/) with support for a -variety of content types like diagrams, math expressions, and tables. Supporting -all GitLab Flavored Markdown content types in the Content Editor is a work in progress. For -the status of the ongoing development for CommonMark and GitLab Flavored Markdown support, read: +The Content Editor requires two properties: -- [Basic Markdown formatting extensions](https://gitlab.com/groups/gitlab-org/-/epics/5404) epic. -- [GitLab Flavored Markdown extensions](https://gitlab.com/groups/gitlab-org/-/epics/5438) epic. +- `renderMarkdown` is an asynchronous function that returns the response (String) of invoking the +[Markdown API](../../api/markdown.md). +- `uploadsPath` is a URL that points to a [GitLab upload service](../uploads.md#upload-encodings) + with `multipart/form-data` support. -## Usage +See the [`WikiForm.vue`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/pages/shared/wikis/components/wiki_form.vue#L207) +component for a production example of these two properties. -To include the Content Editor in your feature, import the `createContentEditor` factory -function and the `ContentEditor` Vue component. `createContentEditor` sets up an instance -of [tiptap's Editor class](https://www.tiptap.dev/api/editor/) with all the necessary -extensions to support editing GitLab Flavored Markdown content. It also creates -a Markdown serializer that allows exporting tiptap's document format to Markdown. +### Set and get Markdown -`createContentEditor` requires a `renderMarkdown` parameter invoked -by the editor every time it needs to convert Markdown to HTML. The Content Editor -does not provide a default value for this function yet. +The `ContentEditor` Vue component doesn't implement Vue data binding flow (`v-model`) +because setting and getting Markdown are expensive operations. Data binding would +trigger these operations every time the user interacts with the component. -**NOTE**: The Content Editor is in an early development stage. Usage and development -guidelines are subject to breaking changes in the upcoming months. +Instead, you should obtain an instance of the `ContentEditor` class by listening to the +`initialized` event: ```html + +``` + +### Listen for changes + +You can still react to changes in the Content Editor. Reacting to changes helps +you know if the document is empty or dirty. Use the `@change` event handler for +this purpose. + +```html + + +``` + +## Implementation guide + +The Content Editor is composed of three main layers: + +- **The editing tools UI**, like the toolbar and the table structure editor. They + display the editor's state and mutate it by dispatching commands. +- **The Tiptap Editor object** manages the editor's state, + and exposes business logic as commands executed by the editing tools UI. +- **The Markdown serializer** transforms a Markdown source string into a ProseMirror + document and vice versa. + +### Editing tools UI + +The editing tools UI are Vue components that display the editor's state and +dispatch [commands](https://www.tiptap.dev/api/commands/#commands) to mutate it. +They are located in the `~/content_editor/components` directory. For example, +the **Bold** toolbar button displays the editor's state by becoming active when +the user selects bold text. This button also dispatches the `toggleBold` command +to format text as bold: + +```mermaid +sequenceDiagram + participant A as Editing tools UI + participant B as Tiptap object + A->>B: queries state/dispatches commands + B--)A: notifies state changes +``` + +#### Node views + +We implement [node views](https://www.tiptap.dev/guide/node-views/vue/#node-views-with-vue) +to provide inline editing tools for some content types, like tables and images. Node views +allow separating the presentation of a content type from its +[model](https://prosemirror.net/docs/guide/#doc.data_structures). Using a Vue component in +the presentation layer enables sophisticated editing experiences in the Content Editor. +Node views are located in `~/content_editor/components/wrappers`. + +#### Dispatch commands + +You can inject the Tiptap Editor object to Vue components to dispatch +commands. + +NOTE: +Do not implement logic that changes the editor's +state in Vue components. Encapsulate this logic in commands, and dispatch +the command from the component's methods. + +```html + +