diff options
89 files changed, 593 insertions, 1008 deletions
diff --git a/app/assets/javascripts/pages/admin/runners/index.js b/app/assets/javascripts/pages/admin/runners/index.js index 104b7eeaf96..e60c6133c7c 100644 --- a/app/assets/javascripts/pages/admin/runners/index.js +++ b/app/assets/javascripts/pages/admin/runners/index.js @@ -1,12 +1,11 @@ import initFilteredSearch from '~/pages/search/init_filtered_search'; import AdminRunnersFilteredSearchTokenKeys from '~/filtered_search/admin_runners_filtered_search_token_keys'; import { FILTERED_SEARCH } from '~/pages/constants'; -import { initInstallRunner } from '~/pages/shared/mount_runner_instructions'; -initFilteredSearch({ - page: FILTERED_SEARCH.ADMIN_RUNNERS, - filteredSearchTokenKeys: AdminRunnersFilteredSearchTokenKeys, - useDefaultState: true, +document.addEventListener('DOMContentLoaded', () => { + initFilteredSearch({ + page: FILTERED_SEARCH.ADMIN_RUNNERS, + filteredSearchTokenKeys: AdminRunnersFilteredSearchTokenKeys, + useDefaultState: true, + }); }); - -initInstallRunner(); diff --git a/app/assets/javascripts/pages/groups/settings/ci_cd/show/index.js b/app/assets/javascripts/pages/groups/settings/ci_cd/show/index.js index 3456048d718..e8d8c985ade 100644 --- a/app/assets/javascripts/pages/groups/settings/ci_cd/show/index.js +++ b/app/assets/javascripts/pages/groups/settings/ci_cd/show/index.js @@ -4,18 +4,18 @@ import initFilteredSearch from '~/pages/search/init_filtered_search'; import GroupRunnersFilteredSearchTokenKeys from '~/filtered_search/group_runners_filtered_search_token_keys'; import { FILTERED_SEARCH } from '~/pages/constants'; import initSharedRunnersForm from '~/group_settings/mount_shared_runners'; -import { initInstallRunner } from '~/pages/shared/mount_runner_instructions'; -// Initialize expandable settings panels -initSettingsPanels(); +document.addEventListener('DOMContentLoaded', () => { + // Initialize expandable settings panels + initSettingsPanels(); -initFilteredSearch({ - page: FILTERED_SEARCH.ADMIN_RUNNERS, - filteredSearchTokenKeys: GroupRunnersFilteredSearchTokenKeys, - anchor: FILTERED_SEARCH.GROUP_RUNNERS_ANCHOR, - useDefaultState: false, -}); + initFilteredSearch({ + page: FILTERED_SEARCH.ADMIN_RUNNERS, + filteredSearchTokenKeys: GroupRunnersFilteredSearchTokenKeys, + anchor: FILTERED_SEARCH.GROUP_RUNNERS_ANCHOR, + useDefaultState: false, + }); -initSharedRunnersForm(); -initVariableList(); -initInstallRunner(); + initSharedRunnersForm(); + initVariableList(); +}); diff --git a/app/assets/javascripts/pages/projects/settings/ci_cd/show/index.js b/app/assets/javascripts/pages/projects/settings/ci_cd/show/index.js index 5d4c1595342..d18cde4ac87 100644 --- a/app/assets/javascripts/pages/projects/settings/ci_cd/show/index.js +++ b/app/assets/javascripts/pages/projects/settings/ci_cd/show/index.js @@ -4,32 +4,32 @@ import registrySettingsApp from '~/registry/settings/registry_settings_bundle'; import initVariableList from '~/ci_variable_list'; import initDeployFreeze from '~/deploy_freeze'; import initSettingsPipelinesTriggers from '~/ci_settings_pipeline_triggers'; -import { initInstallRunner } from '~/pages/shared/mount_runner_instructions'; -// Initialize expandable settings panels -initSettingsPanels(); +document.addEventListener('DOMContentLoaded', () => { + // Initialize expandable settings panels + initSettingsPanels(); -const runnerToken = document.querySelector('.js-secret-runner-token'); -if (runnerToken) { - const runnerTokenSecretValue = new SecretValues({ - container: runnerToken, - }); - runnerTokenSecretValue.init(); -} + const runnerToken = document.querySelector('.js-secret-runner-token'); + if (runnerToken) { + const runnerTokenSecretValue = new SecretValues({ + container: runnerToken, + }); + runnerTokenSecretValue.init(); + } -initVariableList(); + initVariableList(); -// hide extra auto devops settings based checkbox state -const autoDevOpsExtraSettings = document.querySelector('.js-extra-settings'); -const instanceDefaultBadge = document.querySelector('.js-instance-default-badge'); -document.querySelector('.js-toggle-extra-settings').addEventListener('click', event => { - const { target } = event; - if (instanceDefaultBadge) instanceDefaultBadge.style.display = 'none'; - autoDevOpsExtraSettings.classList.toggle('hidden', !target.checked); -}); + // hide extra auto devops settings based checkbox state + const autoDevOpsExtraSettings = document.querySelector('.js-extra-settings'); + const instanceDefaultBadge = document.querySelector('.js-instance-default-badge'); + document.querySelector('.js-toggle-extra-settings').addEventListener('click', event => { + const { target } = event; + if (instanceDefaultBadge) instanceDefaultBadge.style.display = 'none'; + autoDevOpsExtraSettings.classList.toggle('hidden', !target.checked); + }); -registrySettingsApp(); -initDeployFreeze(); + registrySettingsApp(); + initDeployFreeze(); -initSettingsPipelinesTriggers(); -initInstallRunner(); + initSettingsPipelinesTriggers(); +}); diff --git a/app/assets/javascripts/pages/shared/mount_runner_instructions.js b/app/assets/javascripts/pages/shared/mount_runner_instructions.js deleted file mode 100644 index b7662155339..00000000000 --- a/app/assets/javascripts/pages/shared/mount_runner_instructions.js +++ /dev/null @@ -1,32 +0,0 @@ -import Vue from 'vue'; -import VueApollo from 'vue-apollo'; -import createDefaultClient from '~/lib/graphql'; -import InstallRunnerInstructions from '~/vue_shared/components/runner_instructions/runner_instructions.vue'; - -Vue.use(VueApollo); - -export function initInstallRunner(componentId = 'js-install-runner') { - const installRunnerEl = document.getElementById(componentId); - const { projectPath, groupPath } = installRunnerEl?.dataset; - - if (installRunnerEl) { - const defaultClient = createDefaultClient(); - - const apolloProvider = new VueApollo({ - defaultClient, - }); - - // eslint-disable-next-line no-new - new Vue({ - el: installRunnerEl, - apolloProvider, - provide: { - projectPath, - groupPath, - }, - render(createElement) { - return createElement(InstallRunnerInstructions); - }, - }); - } -} diff --git a/app/assets/javascripts/vue_merge_request_widget/components/deployment/constants.js b/app/assets/javascripts/vue_merge_request_widget/components/deployment/constants.js index 66de4f8b682..29d067a46a6 100644 --- a/app/assets/javascripts/vue_merge_request_widget/components/deployment/constants.js +++ b/app/assets/javascripts/vue_merge_request_widget/components/deployment/constants.js @@ -6,6 +6,7 @@ export const RUNNING = 'running'; export const SUCCESS = 'success'; export const FAILED = 'failed'; export const CANCELED = 'canceled'; +export const SKIPPED = 'skipped'; // ACTION STATUSES export const STOPPING = 'stopping'; diff --git a/app/assets/javascripts/vue_merge_request_widget/components/deployment/deployment_info.vue b/app/assets/javascripts/vue_merge_request_widget/components/deployment/deployment_info.vue index 2f922b990d9..390469dec24 100644 --- a/app/assets/javascripts/vue_merge_request_widget/components/deployment/deployment_info.vue +++ b/app/assets/javascripts/vue_merge_request_widget/components/deployment/deployment_info.vue @@ -4,7 +4,15 @@ import { __ } from '~/locale'; import TooltipOnTruncate from '~/vue_shared/components/tooltip_on_truncate.vue'; import timeagoMixin from '~/vue_shared/mixins/timeago'; import MemoryUsage from './memory_usage.vue'; -import { MANUAL_DEPLOY, WILL_DEPLOY, RUNNING, SUCCESS, FAILED, CANCELED } from './constants'; +import { + MANUAL_DEPLOY, + WILL_DEPLOY, + RUNNING, + SUCCESS, + FAILED, + CANCELED, + SKIPPED, +} from './constants'; export default { name: 'DeploymentInfo', @@ -38,6 +46,7 @@ export default { [SUCCESS]: __('Deployed to'), [FAILED]: __('Failed to deploy to'), [CANCELED]: __('Canceled deployment to'), + [SKIPPED]: __('Skipped deployment to'), }, computed: { deployTimeago() { diff --git a/app/assets/javascripts/vue_shared/components/runner_instructions/graphql/queries/get_runner_platforms.query.graphql b/app/assets/javascripts/vue_shared/components/runner_instructions/graphql/queries/get_runner_platforms.query.graphql deleted file mode 100644 index ff0626167a9..00000000000 --- a/app/assets/javascripts/vue_shared/components/runner_instructions/graphql/queries/get_runner_platforms.query.graphql +++ /dev/null @@ -1,20 +0,0 @@ -query getRunnerPlatforms($projectPath: ID!, $groupPath: ID!) { - runnerPlatforms { - nodes { - name - humanReadableName - architectures { - nodes { - name - downloadLocation - } - } - } - } - project(fullPath: $projectPath) { - id - } - group(fullPath: $groupPath) { - id - } -} diff --git a/app/assets/javascripts/vue_shared/components/runner_instructions/graphql/queries/get_runner_setup.query.graphql b/app/assets/javascripts/vue_shared/components/runner_instructions/graphql/queries/get_runner_setup.query.graphql deleted file mode 100644 index 643c1991807..00000000000 --- a/app/assets/javascripts/vue_shared/components/runner_instructions/graphql/queries/get_runner_setup.query.graphql +++ /dev/null @@ -1,16 +0,0 @@ -query runnerSetupInstructions( - $platform: String! - $architecture: String! - $projectId: ID! - $groupId: ID! -) { - runnerSetup( - platform: $platform - architecture: $architecture - projectId: $projectId - groupId: $groupId - ) { - installInstructions - registerInstructions - } -} diff --git a/app/assets/javascripts/vue_shared/components/runner_instructions/runner_instructions.vue b/app/assets/javascripts/vue_shared/components/runner_instructions/runner_instructions.vue deleted file mode 100644 index b70b1277155..00000000000 --- a/app/assets/javascripts/vue_shared/components/runner_instructions/runner_instructions.vue +++ /dev/null @@ -1,220 +0,0 @@ -<script> -import { - GlAlert, - GlButton, - GlModal, - GlModalDirective, - GlButtonGroup, - GlDropdown, - GlDropdownItem, - GlIcon, -} from '@gitlab/ui'; -import { __, s__ } from '~/locale'; -import getRunnerPlatforms from './graphql/queries/get_runner_platforms.query.graphql'; -import getRunnerSetupInstructions from './graphql/queries/get_runner_setup.query.graphql'; - -export default { - components: { - GlAlert, - GlButton, - GlButtonGroup, - GlDropdown, - GlDropdownItem, - GlModal, - GlIcon, - }, - directives: { - GlModalDirective, - }, - inject: { - projectPath: { - default: '', - }, - groupPath: { - default: '', - }, - }, - apollo: { - runnerPlatforms: { - query: getRunnerPlatforms, - variables() { - return { - projectPath: this.projectPath, - groupPath: this.groupPath, - }; - }, - update(data) { - return data; - }, - error() { - this.showAlert = true; - }, - }, - }, - data() { - return { - showAlert: false, - selectedPlatformArchitectures: [], - selectedPlatform: {}, - selectedArchitecture: {}, - runnerPlatforms: {}, - instructions: {}, - }; - }, - computed: { - isPlatformSelected() { - return Object.keys(this.selectedPlatform).length > 0; - }, - instructionsEmpty() { - return this.instructions && Object.keys(this.instructions).length === 0; - }, - groupId() { - return this.runnerPlatforms?.group?.id ?? ''; - }, - projectId() { - return this.runnerPlatforms?.project?.id ?? ''; - }, - platforms() { - return this.runnerPlatforms.runnerPlatforms?.nodes; - }, - }, - methods: { - selectPlatform(name) { - this.selectedPlatform = this.platforms.find(platform => platform.name === name); - this.selectedPlatformArchitectures = this.selectedPlatform?.architectures?.nodes; - [this.selectedArchitecture] = this.selectedPlatformArchitectures; - this.selectArchitecture(this.selectedArchitecture); - }, - selectArchitecture(architecture) { - this.selectedArchitecture = architecture; - - this.$apollo.addSmartQuery('instructions', { - variables() { - return { - platform: this.selectedPlatform.name, - architecture: this.selectedArchitecture.name, - projectId: this.projectId, - groupId: this.groupId, - }; - }, - query: getRunnerSetupInstructions, - update(data) { - return data?.runnerSetup; - }, - error() { - this.showAlert = true; - }, - }); - }, - toggleAlert(state) { - this.showAlert = state; - }, - }, - modalId: 'installation-instructions-modal', - i18n: { - installARunner: __('Install a Runner'), - architecture: s__('Runners|Architecture'), - downloadInstallBinary: s__('Runners|Download and Install Binary'), - downloadLatestBinary: s__('Runners|Download Latest Binary'), - registerRunner: s__('Runners|Register Runner'), - method: __('Method'), - fetchError: s__('An error has occurred fetching instructions'), - instructions: __('Show Runner installation instructions'), - }, - closeButton: { - text: __('Close'), - attributes: [{ variant: 'default' }], - }, -}; -</script> -<template> - <div> - <gl-button v-gl-modal-directive="$options.modalId" data-testid="show-modal-button"> - {{ $options.i18n.instructions }} - </gl-button> - <gl-modal - :modal-id="$options.modalId" - :title="$options.i18n.installARunner" - :action-secondary="$options.closeButton" - > - <gl-alert v-if="showAlert" variant="danger" @dismiss="toggleAlert(false)"> - {{ $options.i18n.fetchError }} - </gl-alert> - <h5>{{ __('Environment') }}</h5> - <gl-button-group class="gl-mb-5"> - <gl-button - v-for="platform in platforms" - :key="platform.name" - data-testid="platform-button" - @click="selectPlatform(platform.name)" - > - {{ platform.humanReadableName }} - </gl-button> - </gl-button-group> - <template v-if="isPlatformSelected"> - <h5> - {{ $options.i18n.architecture }} - </h5> - <gl-dropdown class="gl-mb-5" :text="selectedArchitecture.name"> - <gl-dropdown-item - v-for="architecture in selectedPlatformArchitectures" - :key="architecture.name" - data-testid="architecture-dropdown-item" - @click="selectArchitecture(architecture)" - > - {{ architecture.name }} - </gl-dropdown-item> - </gl-dropdown> - <div class="gl-display-flex gl-align-items-center gl-mb-5"> - <h5>{{ $options.i18n.downloadInstallBinary }}</h5> - <gl-button - class="gl-ml-auto" - :href="selectedArchitecture.downloadLocation" - download - data-testid="binary-download-button" - > - {{ $options.i18n.downloadLatestBinary }} - </gl-button> - </div> - </template> - <template v-if="!instructionsEmpty"> - <div class="gl-display-flex"> - <pre - class="bg-light gl-flex-fill-1 gl-white-space-pre-line" - data-testid="binary-instructions" - > - {{ instructions.installInstructions }} - </pre> - <gl-button - class="gl-align-self-start gl-ml-2 gl-mt-2" - category="tertiary" - variant="link" - :data-clipboard-text="instructions.installationInstructions" - > - <gl-icon name="copy-to-clipboard" /> - </gl-button> - </div> - - <hr /> - <h5 class="gl-mb-5">{{ $options.i18n.registerRunner }}</h5> - <h5 class="gl-mb-5">{{ $options.i18n.method }}</h5> - <div class="gl-display-flex"> - <pre - class="bg-light gl-flex-fill-1 gl-white-space-pre-line" - data-testid="runner-instructions" - > - {{ instructions.registerInstructions }} - </pre> - <gl-button - class="gl-align-self-start gl-ml-2 gl-mt-2" - category="tertiary" - variant="link" - :data-clipboard-text="instructions.registerInstructions" - > - <gl-icon name="copy-to-clipboard" /> - </gl-button> - </div> - </template> - </gl-modal> - </div> -</template> diff --git a/app/assets/stylesheets/page_bundles/ci_status.scss b/app/assets/stylesheets/page_bundles/ci_status.scss index 8522a0a8fe4..89fbe1c4caf 100644 --- a/app/assets/stylesheets/page_bundles/ci_status.scss +++ b/app/assets/stylesheets/page_bundles/ci_status.scss @@ -26,6 +26,7 @@ } &.ci-canceled, + &.ci-skipped, &.ci-disabled, &.ci-scheduled, &.ci-manual { diff --git a/app/helpers/environment_helper.rb b/app/helpers/environment_helper.rb index c4487ae8e4a..491d2731e91 100644 --- a/app/helpers/environment_helper.rb +++ b/app/helpers/environment_helper.rb @@ -52,6 +52,8 @@ module EnvironmentHelper s_('Deployment|failed') when 'canceled' s_('Deployment|canceled') + when 'skipped' + s_('Deployment|skipped') end klass = "ci-status ci-#{status.dasherize}" diff --git a/app/models/ci/build.rb b/app/models/ci/build.rb index 84abd01786d..8a07796fa07 100644 --- a/app/models/ci/build.rb +++ b/app/models/ci/build.rb @@ -379,8 +379,16 @@ module Ci Ci::BuildRunnerSession.where(build: build).delete_all end - after_transition any => [:skipped, :canceled] do |build| - build.deployment&.cancel + after_transition any => [:skipped, :canceled] do |build, transition| + if Feature.enabled?(:cd_skipped_deployment_status, build.project) + if transition.to_name == :skipped + build.deployment&.skip + else + build.deployment&.cancel + end + else + build.deployment&.cancel + end end end diff --git a/app/models/deployment.rb b/app/models/deployment.rb index 36ac1bdb236..74587c6a77a 100644 --- a/app/models/deployment.rb +++ b/app/models/deployment.rb @@ -63,6 +63,10 @@ class Deployment < ApplicationRecord transition any - [:canceled] => :canceled end + event :skip do + transition any - [:skipped] => :skipped + end + before_transition any => FINISHED_STATUSES do |deployment| deployment.finished_at = Time.current end @@ -105,7 +109,8 @@ class Deployment < ApplicationRecord running: 1, success: 2, failed: 3, - canceled: 4 + canceled: 4, + skipped: 5 } def self.last_for_environment(environment) @@ -297,6 +302,8 @@ class Deployment < ApplicationRecord drop when 'canceled' cancel + when 'skipped' + skip else raise ArgumentError, "The status #{status.inspect} is invalid" end diff --git a/app/services/projects/transfer_service.rb b/app/services/projects/transfer_service.rb index 5743efab81b..5178c76f0fc 100644 --- a/app/services/projects/transfer_service.rb +++ b/app/services/projects/transfer_service.rb @@ -71,7 +71,10 @@ module Projects Project.transaction do project.expire_caches_before_rename(@old_path) + # Apply changes to the project update_namespace_and_visibility(@new_namespace) + update_shared_runners_settings + project.save! # Notifications project.send_move_instructions(@old_path) @@ -84,10 +87,6 @@ module Projects # Move uploads move_project_uploads(project) - # If a project is being transferred to another group it means it can already - # have shared runners enabled but we need to check whether the new group allows that. - project.shared_runners_enabled = false if project.group && project.group.shared_runners_setting == 'disabled_and_unoverridable' - project.old_path_with_namespace = @old_path update_repository_configuration(@new_path) @@ -120,7 +119,6 @@ module Projects # Apply new namespace id and visibility level project.namespace = to_namespace project.visibility_level = to_namespace.visibility_level unless project.visibility_level_allowed_by_group? - project.save! end def update_repository_configuration(full_path) @@ -208,6 +206,14 @@ module Projects def new_design_repo_path "#{new_path}#{::Gitlab::GlRepository::DESIGN.path_suffix}" end + + def update_shared_runners_settings + # If a project is being transferred to another group it means it can already + # have shared runners enabled but we need to check whether the new group allows that. + if project.group && project.group.shared_runners_setting == 'disabled_and_unoverridable' + project.shared_runners_enabled = false + end + end end end diff --git a/app/views/admin/runners/index.html.haml b/app/views/admin/runners/index.html.haml index c2d7b63f1f9..3d3b8c28a17 100644 --- a/app/views/admin/runners/index.html.haml +++ b/app/views/admin/runners/index.html.haml @@ -39,9 +39,7 @@ = render partial: 'ci/runner/how_to_setup_runner', locals: { registration_token: Gitlab::CurrentSettings.runners_registration_token, type: 'shared', - reset_token_url: reset_registration_token_admin_application_settings_path, - project_path: '', - group_path: '' } + reset_token_url: reset_registration_token_admin_application_settings_path } .row .col-sm-9 diff --git a/app/views/ci/runner/_how_to_setup_runner.html.haml b/app/views/ci/runner/_how_to_setup_runner.html.haml index 0ff6fdc6354..4ea3b0f0fb9 100644 --- a/app/views/ci/runner/_how_to_setup_runner.html.haml +++ b/app/views/ci/runner/_how_to_setup_runner.html.haml @@ -19,5 +19,3 @@ data: { confirm: _("Are you sure you want to reset registration token?") } %li = _("Start the Runner!") - -#js-install-runner{ data: { project_path: project_path, group_path: group_path } } diff --git a/app/views/groups/runners/_group_runners.html.haml b/app/views/groups/runners/_group_runners.html.haml index 087c38c7b86..554240b7aef 100644 --- a/app/views/groups/runners/_group_runners.html.haml +++ b/app/views/groups/runners/_group_runners.html.haml @@ -17,6 +17,4 @@ = render partial: 'ci/runner/how_to_setup_runner', locals: { registration_token: @group.runners_token, type: 'group', - reset_token_url: reset_registration_token_group_settings_ci_cd_path, - project_path: '', - group_path: @group.path } + reset_token_url: reset_registration_token_group_settings_ci_cd_path } diff --git a/app/views/projects/runners/_specific_runners.html.haml b/app/views/projects/runners/_specific_runners.html.haml index e02e2cc784a..ed9e6aac346 100644 --- a/app/views/projects/runners/_specific_runners.html.haml +++ b/app/views/projects/runners/_specific_runners.html.haml @@ -9,9 +9,7 @@ = render partial: 'ci/runner/how_to_setup_runner', locals: { registration_token: @project.runners_token, type: 'specific', - reset_token_url: reset_registration_token_namespace_project_settings_ci_cd_path, - project_path: @project.path_with_namespace, - group_path: '' } + reset_token_url: reset_registration_token_namespace_project_settings_ci_cd_path } - if @project_runners.any? %h4.underlined-title= _('Runners activated for this project') diff --git a/changelogs/unreleased/37947-skipped-deployments.yml b/changelogs/unreleased/37947-skipped-deployments.yml new file mode 100644 index 00000000000..3b4f6e42715 --- /dev/null +++ b/changelogs/unreleased/37947-skipped-deployments.yml @@ -0,0 +1,5 @@ +--- +title: Skipped jobs no longer trigger a cancelled deployment +merge_request: 46614 +author: David Barr @davebarr +type: fixed diff --git a/changelogs/unreleased/ak-fix-project-transfer.yml b/changelogs/unreleased/ak-fix-project-transfer.yml new file mode 100644 index 00000000000..54556b2e3d7 --- /dev/null +++ b/changelogs/unreleased/ak-fix-project-transfer.yml @@ -0,0 +1,5 @@ +--- +title: Fix project transfer corrupting shared runners state +merge_request: 48032 +author: +type: fixed diff --git a/changelogs/unreleased/jivanvl-runner-guided-install-frontend.yml b/changelogs/unreleased/jivanvl-runner-guided-install-frontend.yml deleted file mode 100644 index d103c4015d4..00000000000 --- a/changelogs/unreleased/jivanvl-runner-guided-install-frontend.yml +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Add install GitLab runner popup -merge_request: 42877 -author: -type: added diff --git a/config/feature_flags/development/cd_skipped_deployment_status.yml b/config/feature_flags/development/cd_skipped_deployment_status.yml new file mode 100644 index 00000000000..45d9538ebfc --- /dev/null +++ b/config/feature_flags/development/cd_skipped_deployment_status.yml @@ -0,0 +1,7 @@ +name: cd_skipped_deployment_status +introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46614 +rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/283884 +milestone: '13.6' +type: development +group: group::release +default_enabled: false diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index bbb5c892298..a8ee7f8dbcc 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -216,7 +216,7 @@ jsdom JupyterHub kanban kanbans -Kaniko +kaniko Karma Kerberos keyset @@ -317,6 +317,7 @@ PgBouncer Phabricator phaser phasers +phpenv Pipfile Pipfiles Piwik diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 4d7c4623b67..b8af4bf0f6a 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -434,8 +434,8 @@ server (with `gitaly_address`) unless you setup with special ``` NOTE: **Note:** - `/some/local/path` should be set to a local folder that exists, however no data will be stored in - this folder. This will no longer be necessary after + `/some/local/path` should be set to a local folder that exists, however no data is stored in + this folder. This requirement is scheduled to be removed when [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). @@ -461,7 +461,7 @@ GitLab can reside on the same server as one of many Gitaly servers, but doesn't configuration that mixes local and remote configuration. The following setup is incorrect, because: - All addresses must be reachable from the other Gitaly servers. -- `storage1` will be assigned a Unix socket for `gitaly_address` which is +- `storage1` is assigned a Unix socket for `gitaly_address` which is invalid for some of the Gitaly servers. ```ruby @@ -493,7 +493,7 @@ gitaly['key_path'] = "/etc/gitlab/ssl/key.pem" ``` `path` can only be included for storage shards on the local Gitaly server. -If it's excluded, default Git storage directory will be used for that storage shard. +If it's excluded, default Git storage directory is used for that storage shard. ### Disable Gitaly where not required (optional) @@ -590,7 +590,7 @@ To configure Gitaly with TLS: ``` 1. Copy all Gitaly server certificates (or their certificate authority) to - `/etc/gitlab/trusted-certs` so that Gitaly servers will trust the certificate when calling into themselves + `/etc/gitlab/trusted-certs` so that Gitaly servers trust the certificate when calling into themselves or other Gitaly servers: ```shell @@ -647,8 +647,8 @@ To configure Gitaly with TLS: ``` NOTE: **Note:** - `/some/local/path` should be set to a local folder that exists, however no data will be stored - in this folder. This will no longer be necessary after + `/some/local/path` should be set to a local folder that exists, however no data is stored + in this folder. This requirement is scheduled to be removed when [Gitaly issue #1282](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). @@ -668,7 +668,7 @@ To configure Gitaly with TLS: ``` 1. Copy all Gitaly server certificates (or their certificate authority) to the system trusted - certificates folder so Gitaly server will trust the certificate when calling into itself or other Gitaly + certificates folder so Gitaly server trusts the certificate when calling into itself or other Gitaly servers. ```shell @@ -806,7 +806,7 @@ You can observe the behavior of this queue using the Gitaly logs and Prometheus: NOTE: **Note:** Though the name of the Prometheus metric contains `rate_limiting`, it is a concurrency limiter, not -a rate limiter. If a Gitaly client makes 1000 requests in a row very quickly, concurrency will not +a rate limiter. If a Gitaly client makes 1000 requests in a row very quickly, concurrency does not exceed 1 and the concurrency limiter has no effect. ## Rotate Gitaly authentication token @@ -835,7 +835,7 @@ behavior of your GitLab installation using Prometheus. Use the following Prometh sum(rate(gitaly_authentications_total[5m])) by (enforced, status) ``` -In a system where authentication is configured correctly and where you have live traffic, you will +In a system where authentication is configured correctly and where you have live traffic, you see something like this: ```prometheus @@ -891,7 +891,7 @@ To update to a new Gitaly authentication token, on each Gitaly client **and** Gi ``` If you run your [Prometheus query](#verify-authentication-monitoring) while this change is -being rolled out, you will see non-zero values for the `enforced="false",status="denied"` counter. +being rolled out, you see non-zero values for the `enforced="false",status="denied"` counter. ### Ensure there are no authentication failures @@ -1003,7 +1003,7 @@ When GitLab calls a function that has a "Rugged patch", it performs two checks: - Is the feature flag for this patch set in the database? If so, the feature flag setting controls GitLab's use of "Rugged patch" code. - If the feature flag is not set, GitLab tries accessing the filesystem underneath the - Gitaly server directly. If it can, it will use the "Rugged patch": + Gitaly server directly. If it can, it uses the "Rugged patch": - If using Unicorn. - If using Puma and [thread count](../../install/requirements.md#puma-threads) is set to `1`. @@ -1076,7 +1076,7 @@ gitaly-debug -h remote: GitLab: 401 Unauthorized ``` -You will need to sync your `gitlab-secrets.json` file with your Gitaly clients (GitLab +You need to sync your `gitlab-secrets.json` file with your Gitaly clients (GitLab app nodes). ### Client side gRPC logs diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index d091ae5895a..edee79ebee3 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -133,7 +133,7 @@ GitLab](https://about.gitlab.com/install/). - 3 Gitaly nodes (high CPU, high memory, fast storage) - 1 GitLab server -You will need the IP/host address for each node. +You need the IP/host address for each node. 1. `LOAD_BALANCER_SERVER_ADDRESS`: the IP/host address of the load balancer 1. `POSTGRESQL_SERVER_ADDRESS`: the IP/host address of the PostgreSQL server @@ -149,7 +149,7 @@ If you are using Google Cloud Platform, SoftLayer, or any other vendor that prov The communication between components is secured with different secrets, which are described below. Before you begin, generate a unique secret for each, and -make note of it. This will make it easy to replace these placeholder tokens +make note of it. This makes it easy to replace these placeholder tokens with secure tokens as you complete the setup process. 1. `GITLAB_SHELL_SECRET_TOKEN`: this is used by Git hooks to make callback HTTP @@ -164,7 +164,7 @@ with secure tokens as you complete the setup process. 1. `PRAEFECT_SQL_PASSWORD`: this password is used by Praefect to connect to PostgreSQL. -We will note in the instructions below where these secrets are required. +We note in the instructions below where these secrets are required. ### PostgreSQL @@ -184,13 +184,13 @@ failure. For greater fault tolerance, the following options are available: - Use a cloud-managed PostgreSQL service. AWS [Relational Database Service](https://aws.amazon.com/rds/) is recommended. -To complete this section you will need: +To complete this section you need: - 1 Praefect node - 1 PostgreSQL server (PostgreSQL 11 or newer) - An SQL user with permissions to create databases -During this section, we will configure the PostgreSQL server, from the Praefect +During this section, we configure the PostgreSQL server, from the Praefect node, using `psql` which is installed by Omnibus GitLab. 1. SSH into the **Praefect** node and login as root: @@ -207,7 +207,7 @@ node, using `psql` which is installed by Omnibus GitLab. /opt/gitlab/embedded/bin/psql -U postgres -d template1 -h POSTGRESQL_SERVER_ADDRESS ``` - Create a new user `praefect` which will be used by Praefect. Replace + Create a new user `praefect` to be used by Praefect. Replace `PRAEFECT_SQL_PASSWORD` with the strong password you generated in the preparation step. @@ -281,11 +281,10 @@ PostgreSQL instances. Otherwise you should change the configuration parameter NOTE: **Note:** If there are multiple Praefect nodes, complete these steps for **each** node. -To complete this section you will need: +To complete this section you need a [configured PostgreSQL server](#postgresql), including: -- [Configured PostgreSQL server](#postgresql), including: - - IP/host address (`POSTGRESQL_SERVER_ADDRESS`) - - password (`PRAEFECT_SQL_PASSWORD`) +- IP/host address (`POSTGRESQL_SERVER_ADDRESS`) +- Password (`PRAEFECT_SQL_PASSWORD`) Praefect should be run on a dedicated node. Do not run Praefect on the application server, or a Gitaly node. @@ -331,8 +330,8 @@ application server, or a Gitaly node. ``` 1. Configure a strong `auth_token` for **Praefect** by editing - `/etc/gitlab/gitlab.rb`. This will be needed by clients outside the cluster - (like GitLab Shell) to communicate with the Praefect cluster : + `/etc/gitlab/gitlab.rb`. This is needed by clients outside the cluster + (like GitLab Shell) to communicate with the Praefect cluster: ```ruby praefect['auth_token'] = 'PRAEFECT_EXTERNAL_TOKEN' @@ -341,7 +340,7 @@ application server, or a Gitaly node. 1. Configure **Praefect** to connect to the PostgreSQL database by editing `/etc/gitlab/gitlab.rb`. - You will need to replace `POSTGRESQL_SERVER_ADDRESS` with the IP/host address + You need to replace `POSTGRESQL_SERVER_ADDRESS` with the IP/host address of the database, and `PRAEFECT_SQL_PASSWORD` with the strong password set above. @@ -364,7 +363,7 @@ application server, or a Gitaly node. # praefect['database_sslrootcert'] = '/path/to/rootcert' ``` - By default Praefect will refuse to make an unencrypted connection to + By default, Praefect refuses to make an unencrypted connection to PostgreSQL. You can override this by uncommenting the following line: ```ruby @@ -377,7 +376,7 @@ application server, or a Gitaly node. The virtual storage's name must match the configured storage name in GitLab configuration. In a later step, we configure the storage name as `default` so we use `default` here as well. This cluster has three Gitaly nodes `gitaly-1`, - `gitaly-2`, and `gitaly-3`, which will be replicas of each other. + `gitaly-2`, and `gitaly-3`, which are intended to be replicas of each other. CAUTION: **Caution:** If you have data on an already existing storage called @@ -385,7 +384,7 @@ application server, or a Gitaly node. [migrate the data to the Gitaly Cluster storage](#migrate-existing-repositories-to-gitaly-cluster) afterwards. - Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which will be used by + Replace `PRAEFECT_INTERNAL_TOKEN` with a strong secret, which is used by Praefect when communicating with Gitaly nodes in the cluster. This token is distinct from the `PRAEFECT_EXTERNAL_TOKEN`. @@ -555,12 +554,12 @@ To configure Praefect with TLS: NOTE: **Note:** `/some/local/path` should be set to a local folder that exists, however no - data will be stored in this folder. This will no longer be necessary after + data is stored in this folder. This requirement is scheduled to be removed when [this issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1282) is resolved. 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source). 1. Copy all Praefect server certificates, or their certificate authority, to the system - trusted certificates on each Gitaly server so the Praefect server will trust the + trusted certificates on each Gitaly server so the Praefect server trusts the certificate when called by Gitaly servers: ```shell @@ -585,7 +584,7 @@ To configure Praefect with TLS: NOTE: **Note:** Complete these steps for **each** Gitaly node. -To complete this section you will need: +To complete this section you need: - [Configured Praefect node](#praefect) - 3 (or more) servers, with GitLab installed, to be configured as Gitaly nodes. @@ -595,19 +594,19 @@ Every Gitaly server assigned to the Praefect cluster needs to be configured. The configuration is the same as a normal [standalone Gitaly server](index.md), except: -- the storage names are exposed to Praefect, not GitLab -- the secret token is shared with Praefect, not GitLab +- The storage names are exposed to Praefect, not GitLab +- The secret token is shared with Praefect, not GitLab The configuration of all Gitaly nodes in the Praefect cluster can be identical, because we rely on Praefect to route operations correctly. Particular attention should be shown to: -- the `gitaly['auth_token']` configured in this section must match the `token` +- The `gitaly['auth_token']` configured in this section must match the `token` value under `praefect['virtual_storages']` on the Praefect node. This was set in the [previous section](#praefect). This document uses the placeholder `PRAEFECT_INTERNAL_TOKEN` throughout. -- the storage names in `git_data_dirs` configured in this section must match the +- The storage names in `git_data_dirs` configured in this section must match the storage names under `praefect['virtual_storages']` on the Praefect node. This was set in the [previous section](#praefect). This document uses `gitaly-1`, `gitaly-2`, and `gitaly-3` as Gitaly storage names. @@ -659,8 +658,8 @@ documentation](index.md#configure-gitaly-servers). ``` 1. Configure a strong `auth_token` for **Gitaly** by editing - `/etc/gitlab/gitlab.rb`. This will be needed by clients to communicate with - this Gitaly nodes. Typically, this token will be the same for all Gitaly + `/etc/gitlab/gitlab.rb`. This is needed by clients to communicate with + this Gitaly nodes. Typically, this token is the same for all Gitaly nodes. ```ruby @@ -754,7 +753,7 @@ We hope that if you’re managing HA systems like GitLab, you have a load balanc of choice already. Some examples include [HAProxy](https://www.haproxy.org/) (open-source), [Google Internal Load Balancer](https://cloud.google.com/load-balancing/docs/internal/), [AWS Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/), F5 -Big-IP LTM, and Citrix Net Scaler. This documentation will outline what ports +Big-IP LTM, and Citrix Net Scaler. This documentation outlines what ports and protocols you need configure. | LB Port | Backend Port | Protocol | @@ -763,7 +762,7 @@ and protocols you need configure. ### GitLab -To complete this section you will need: +To complete this section you need: - [Configured Praefect node](#praefect) - [Configured Gitaly nodes](#gitaly) @@ -787,15 +786,15 @@ Particular attention should be shown to: 1. Configure the `external_url` so that files could be served by GitLab by proper endpoint access by editing `/etc/gitlab/gitlab.rb`: - You will need to replace `GITLAB_SERVER_URL` with the real external facing + You need to replace `GITLAB_SERVER_URL` with the real external facing URL on which current GitLab instance is serving: ```ruby external_url 'GITLAB_SERVER_URL' ``` -1. Disable the default Gitaly service running on the GitLab host. It won't be needed - as GitLab will connect to the configured cluster. +1. Disable the default Gitaly service running on the GitLab host. It isn't needed + because GitLab connects to the configured cluster. CAUTION: **Caution:** If you have existing data stored on the default Gitaly storage, @@ -809,7 +808,7 @@ Particular attention should be shown to: 1. Add the Praefect cluster as a storage location by editing `/etc/gitlab/gitlab.rb`. - You will need to replace: + You need to replace: - `LOAD_BALANCER_SERVER_ADDRESS` with the IP address or hostname of the load balancer. @@ -828,7 +827,7 @@ Particular attention should be shown to: nodes during a `git push` are properly authenticated by editing `/etc/gitlab/gitlab.rb`: - You will need to replace `GITLAB_SHELL_SECRET_TOKEN` with the real secret. + You need to replace `GITLAB_SHELL_SECRET_TOKEN` with the real secret. ```ruby gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN' @@ -837,7 +836,7 @@ Particular attention should be shown to: 1. Add Prometheus monitoring settings by editing `/etc/gitlab/gitlab.rb`. If Prometheus is enabled on a different node, make edits on that node instead. - You will need to replace: + You need to replace: - `PRAEFECT_HOST` with the IP address or hostname of the Praefect node - `GITALY_HOST` with the IP address or hostname of each Gitaly node @@ -922,7 +921,7 @@ To get started quickly: gitlab-ctl reconfigure ``` -1. Set the Grafana admin password. This command will prompt you to enter a new +1. Set the Grafana admin password. This command prompts you to enter a new password: ```shell @@ -966,7 +965,7 @@ _Up to date_ in this context means that: - The last replication operation is in _completed_ state. If there is no such nodes, or any other error occurs during node selection, the primary -node will be chosen to serve the request. +node is chosen to serve the request. To track distribution of read operations, you can use the `gitaly_praefect_read_distribution` Prometheus counter metric. It has two labels: @@ -1040,9 +1039,9 @@ current primary node is found to be unhealthy. - **PostgreSQL (recommended):** Enabled by default, and equivalent to: `praefect['failover_election_strategy'] = sql`. This configuration - option will allow multiple Praefect nodes to coordinate via the + option allows multiple Praefect nodes to coordinate via the PostgreSQL database to elect a primary Gitaly node. This configuration - will cause Praefect nodes to elect a new primary, monitor its health, + causes Praefect nodes to elect a new primary, monitor its health, and elect a new primary if the current one has not been reachable in 10 seconds by a majority of the Praefect nodes. - **Memory:** Enabled by setting `praefect['failover_election_strategy'] = 'local'` @@ -1051,8 +1050,7 @@ current primary node is found to be unhealthy. be elected. **Do not use with multiple Praefect nodes!** Using with multiple Praefect nodes is likely to result in a split brain. -It is likely that we will implement support for Consul, and a cloud native -strategy in the future. +We are likely to implement support for Consul, and a cloud native, strategy in the future. ## Primary Node Failure diff --git a/doc/administration/gitaly/reference.md b/doc/administration/gitaly/reference.md index 53001b946d8..3ba6783ae3a 100644 --- a/doc/administration/gitaly/reference.md +++ b/doc/administration/gitaly/reference.md @@ -75,7 +75,7 @@ the `gitaly_authentications_total` metric. ### TLS -Gitaly supports TLS encryption. You will need to bring your own certificates as +Gitaly supports TLS encryption. You need to bring your own certificates as this isn't provided automatically. | Name | Type | Required | Description | @@ -128,7 +128,7 @@ The following values can be set in the `[git]` section of the configuration file | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | -| `bin_path` | string | no | Path to Git binary. If not set, will be resolved using `PATH`. | +| `bin_path` | string | no | Path to Git binary. If not set, is resolved using `PATH`. | | `catfile_cache_size` | integer | no | Maximum number of cached [cat-file processes](#cat-file-cache). Default is `100`. | #### `cat-file` cache @@ -192,8 +192,8 @@ For historical reasons [GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) contains the Git hooks that allow GitLab to validate and react to Git pushes. Because Gitaly "owns" Git pushes, GitLab Shell must therefore be -installed alongside Gitaly. This will be [simplified in the -future](https://gitlab.com/gitlab-org/gitaly/-/issues/1226). +installed alongside Gitaly. We plan to +[simplify this](https://gitlab.com/gitlab-org/gitaly/-/issues/1226). | Name | Type | Required | Description | | ---- | ---- | -------- | ----------- | @@ -238,9 +238,11 @@ The following values configure logging in Gitaly under the `[logging]` section. While the main Gitaly application logs go to `stdout`, there are some extra log files that go to a configured directory, like the GitLab Shell logs. -GitLab Shell does not support `panic` or `trace` level logs. `panic` will fall -back to `error`, while `trace` will fall back to `debug`. Any other invalid log -levels will default to `info`. +GitLab Shell does not support `panic` or `trace` level logs: + +- `panic` falls back to `error`. +- `trace` falls back to `debug`. +- Any other invalid log levels default to `info`. Example: diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index fcaf9aaaaee..c02634fb932 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -14,13 +14,13 @@ health of their GitLab instance. To surface this experience in a native way (similar to how you would interact with an application deployed using GitLab), a base project called "GitLab self monitoring" with [internal visibility](../../../public_access/public_access.md#internal-projects) -will be added under a group called "GitLab Instance Administrators" +is added under a group called "GitLab Instance Administrators" specifically created for visualizing and configuring the monitoring of your GitLab instance. -All administrators at the time of creation of the project and group will be -added as maintainers of the group and project, and as an admin, you'll be able -to add new members to the group to give them maintainer access to the project. +All administrators at the time of creation of the project and group are +added as maintainers of the group and project, and as an admin, you can +add new members to the group to give them maintainer access to the project. This project is used to self monitor your GitLab instance. The metrics dashboard of the project shows some basic resource usage charts, such as CPU and memory usage @@ -34,13 +34,13 @@ metrics exposed by the [GitLab exporter](../prometheus/gitlab_metrics.md#metrics 1. Navigate to **Admin Area > Settings > Metrics and profiling**, and expand the **Self monitoring** section. 1. Toggle the **Create Project** button on. -1. Once your GitLab instance creates the project, you'll see a link to the project in the text above the **Create Project** toggle. You can also find it under **Projects > Your projects**. +1. Once your GitLab instance creates the project, GitLab displays a link to the project in the text above the **Create Project** toggle. You can also find it under **Projects > Your projects**. ## Deleting the self monitoring project CAUTION: **Warning:** If you delete the self monitoring project, you will lose any changes made to the -project. If you create the project again, it will be created in its default state. +project. If you create the project again, it is created in its default state. 1. Navigate to **Admin Area > Settings > Metrics and profiling**, and expand the **Self monitoring** section. 1. Toggle the **Create Project** button off. @@ -63,7 +63,7 @@ You can also ## Connection to Prometheus -The project will be automatically configured to connect to the +The project is automatically configured to connect to the [internal Prometheus](../prometheus/index.md) instance if the Prometheus instance is present (should be the case if GitLab was installed via Omnibus and you haven't disabled it). diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 91f810dc681..22c59c5a7fb 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -10,10 +10,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w > > - Prometheus and the various exporters listed in this page are bundled in the > Omnibus GitLab package. Check each exporter's documentation for the timeline -> they got added. For installations from source you will have to install them -> yourself. Over subsequent releases additional GitLab metrics will be captured. +> they got added. For installations from source you must install them +> yourself. Over subsequent releases additional GitLab metrics are captured. > - Prometheus services are on by default with GitLab 9.0. -> - Prometheus and its exporters don't authenticate users, and will be available +> - Prometheus and its exporters don't authenticate users, and are available > to anyone who can access them. [Prometheus](https://prometheus.io) is a powerful time-series monitoring service, providing a flexible @@ -34,9 +34,9 @@ dashboard tool like [Grafana](https://grafana.com). For installations from source, you must install and configure it yourself. Prometheus and its exporters are on by default, starting with GitLab 9.0. -Prometheus will run as the `gitlab-prometheus` user and listen on +Prometheus runs as the `gitlab-prometheus` user and listen on `http://localhost:9090`. By default, Prometheus is only accessible from the GitLab server itself. -Each exporter will be automatically set up as a +Each exporter is automatically set up as a monitoring target for Prometheus, unless individually disabled. To disable Prometheus and all of its exporters, as well as any added in the future: @@ -179,8 +179,7 @@ The next step is to tell all the other nodes where the monitoring node is: After monitoring using Service Discovery is enabled with `consul['monitoring_service_discovery'] = true`, ensure that `prometheus['scrape_configs']` is not set in `/etc/gitlab/gitlab.rb`. Setting both -`consul['monitoring_service_discovery'] = true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb` -will result in errors. +`consul['monitoring_service_discovery'] = true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb` results in errors. ### Using an external Prometheus server @@ -234,7 +233,7 @@ To use an external Prometheus server: gitlab_rails['prometheus_address'] = '192.168.0.1:9090' ``` -1. To scrape NGINX metrics, you'll also need to configure NGINX to allow the Prometheus server +1. To scrape NGINX metrics, you must also configure NGINX to allow the Prometheus server IP. For example: ```ruby @@ -399,7 +398,7 @@ The GitLab exporter allows you to measure various GitLab metrics, pulled from Re > - Introduced in GitLab 9.0. > - Pod monitoring introduced in GitLab 9.4. -If your GitLab server is running within Kubernetes, Prometheus will collect metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration](../../../user/project/integrations/prometheus.md) to monitor them. +If your GitLab server is running within Kubernetes, Prometheus collects metrics from the Nodes and [annotated Pods](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) in the cluster, including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration](../../../user/project/integrations/prometheus.md) to monitor them. To disable the monitoring of Kubernetes: diff --git a/doc/administration/monitoring/prometheus/node_exporter.md b/doc/administration/monitoring/prometheus/node_exporter.md index fea78a3685c..b8d01f87e9f 100644 --- a/doc/administration/monitoring/prometheus/node_exporter.md +++ b/doc/administration/monitoring/prometheus/node_exporter.md @@ -24,5 +24,5 @@ To enable the node exporter: 1. Save the file, and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now begin collecting performance data from the node exporter +Prometheus begins collecting performance data from the node exporter exposed at `localhost:9100`. diff --git a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md index ff0cfc65e10..0029a6867c7 100644 --- a/doc/administration/monitoring/prometheus/pgbouncer_exporter.md +++ b/doc/administration/monitoring/prometheus/pgbouncer_exporter.md @@ -26,9 +26,9 @@ To enable the PgBouncer exporter: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now begin collecting performance data from the PgBouncer exporter +Prometheus begins collecting performance data from the PgBouncer exporter exposed at `localhost:9188`. -The PgBouncer exporter will also be enabled by default if the +The PgBouncer exporter is enabled by default if the [`pgbouncer_role`](https://docs.gitlab.com/omnibus/roles/#postgresql-roles) role is enabled. diff --git a/doc/administration/monitoring/prometheus/postgres_exporter.md b/doc/administration/monitoring/prometheus/postgres_exporter.md index f7368556235..b28d541371f 100644 --- a/doc/administration/monitoring/prometheus/postgres_exporter.md +++ b/doc/administration/monitoring/prometheus/postgres_exporter.md @@ -21,12 +21,12 @@ To enable the PostgreSQL Server Exporter: If PostgreSQL Server Exporter is configured on a separate node, make sure that the local address is [listed in `trust_auth_cidr_addresses`](../../postgresql/replication_and_failover.md#network-information) or the - exporter will not be able to connect to the database. + exporter can't connect to the database. 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now automatically begin collecting performance data from +Prometheus begins collecting performance data from the PostgreSQL Server Exporter exposed under `localhost:9187`. ## Advanced configuration diff --git a/doc/administration/monitoring/prometheus/redis_exporter.md b/doc/administration/monitoring/prometheus/redis_exporter.md index 41a84f1f3ed..024624f5c67 100644 --- a/doc/administration/monitoring/prometheus/redis_exporter.md +++ b/doc/administration/monitoring/prometheus/redis_exporter.md @@ -25,5 +25,5 @@ To enable the Redis exporter: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now begin collecting performance data from +Prometheus begins collecting performance data from the Redis exporter exposed at `localhost:9121`. diff --git a/doc/administration/monitoring/prometheus/registry_exporter.md b/doc/administration/monitoring/prometheus/registry_exporter.md index 3bf4db8a665..c3cfacd835a 100644 --- a/doc/administration/monitoring/prometheus/registry_exporter.md +++ b/doc/administration/monitoring/prometheus/registry_exporter.md @@ -21,7 +21,7 @@ To enable it: 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. -Prometheus will now automatically begin collecting performance data from +Prometheus automatically begins collecting performance data from the registry exporter exposed under `localhost:5001/metrics`. [← Back to the main Prometheus page](index.md) diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 16e17458e10..74c6e3d23f7 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -50,7 +50,7 @@ storage2: > structure than Omnibus. In `gitlab.yml` you indicate the path for the > repositories, for example `/home/git/repositories`, while in Omnibus you > indicate `git_data_dirs`, which for the example above would be `/home/git`. -> Then, Omnibus will create a `repositories` directory under that path to use with +> Then, Omnibus creates a `repositories` directory under that path to use with > `gitlab.yml`. > > This little detail matters because while restoring a backup, the current @@ -90,8 +90,7 @@ This example uses NFS. We do not recommend using EFS for storage as it may impac 1. [Restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect. NOTE: **Note:** -The [`gitlab_shell: repos_path` entry](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-9-stable/config/gitlab.yml.example#L457) in `gitlab.yml` will be -deprecated and replaced by `repositories: storages` in the future, so if you +We plan to replace [`gitlab_shell: repos_path` entry](https://gitlab.com/gitlab-org/gitlab-foss/-/blob/8-9-stable/config/gitlab.yml.example#L457) in `gitlab.yml` with `repositories: storages`. If you are upgrading from a version prior to 8.10, make sure to add the configuration as described in the step above. After you make the changes and confirm they are working, you can remove the `repos_path` line. @@ -112,16 +111,15 @@ working, you can remove the `repos_path` line. Note that Omnibus stores the repositories in a `repositories` subdirectory of the `git-data` directory. -## Choose where new repositories will be stored +## Choose where new repositories are stored Once you set the multiple storage paths, you can choose where new repositories -will be stored under **Admin Area > Settings > Repository > -Repository storage > Storage nodes for new repositories**. +are stored in the Admin Area under **Settings > Repository > Repository storage > Storage nodes for new repositories**. Each storage can be assigned a weight from 0-100. When a new project is created, these -weights are used to determine the storage location the repository will be created on. +weights are used to determine the storage location the repository is created on.  Beginning with GitLab 8.13.4, multiple paths can be chosen. New repositories -will be randomly placed on one of the selected paths. +are randomly placed on one of the selected paths. diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index d2d492c8f1a..2401dfa5812 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -19,7 +19,7 @@ locations that can be: - Accessed via [Gitaly](gitaly/index.md) on its own machine. In GitLab, this is configured in `/etc/gitlab/gitlab.rb` by the `git_data_dirs({})` -configuration hash. The storage layouts discussed here will apply to any shard +configuration hash. The storage layouts discussed here apply to any shard defined in it. The `default` repository shard that is available in any installations @@ -30,22 +30,22 @@ Anything discussed below is expected to be part of that folder. NOTE: **Note:** In GitLab 13.0, hashed storage is enabled by default and the legacy storage is -deprecated. Support for legacy storage will be removed in GitLab 14.0. +deprecated. Support for legacy storage is scheduled to be removed in GitLab 14.0. If you haven't migrated yet, check the [migration instructions](raketasks/storage.md#migrate-to-hashed-storage). The option to choose between hashed and legacy storage in the admin area has been disabled. Hashed storage is the storage behavior we rolled out with 10.0. Instead -of coupling project URL and the folder structure where the repository will be +of coupling project URL and the folder structure where the repository is stored on disk, we are coupling a hash, based on the project's ID. This makes the folder structure immutable, and therefore eliminates any requirement to synchronize state from URLs to disk structure. This means that renaming a group, -user, or project will cost only the database transaction, and will take effect +user, or project costs only the database transaction, and takes effect immediately. The hash also helps to spread the repositories more evenly on the disk, so the -top-level directory will contain less folders than the total amount of top-level +top-level directory contains fewer folders than the total number of top-level namespaces. The hash format is based on the hexadecimal representation of SHA256: @@ -64,7 +64,7 @@ by another folder with the next 2 characters. They are both stored in a special ### Translating hashed storage paths Troubleshooting problems with the Git repositories, adding hooks, and other -tasks will require you translate between the human readable project name +tasks requires you translate between the human readable project name and the hashed storage path. #### From project name to hashed path @@ -102,7 +102,7 @@ To translate from a hashed storage path to a project name: ProjectRepository.find_by(disk_path: '@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9').project ``` -The quoted string in that command is the directory tree you'll find on your +The quoted string in that command is the directory tree you can find on your GitLab server. For example, on a default Omnibus installation this would be `/var/opt/gitlab/git-data/repositories/@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git` with `.git` from the end of the directory name removed. @@ -135,7 +135,7 @@ when housekeeping is run on the source project. ### Hashed storage coverage migration -Files stored in an S3 compatible endpoint will not have the downsides +Files stored in an S3-compatible endpoint do not have the downsides mentioned earlier, if they are not prefixed with `#{namespace}/#{project_name}`, which is true for CI Cache and LFS Objects. @@ -183,7 +183,7 @@ NOTE: **Deprecated:** In GitLab 13.0, hashed storage is enabled by default and the legacy storage is deprecated. If you haven't migrated yet, check the [migration instructions](raketasks/storage.md#migrate-to-hashed-storage). -Support for legacy storage will be removed in GitLab 14.0. If you're on GitLab +Support for legacy storage is scheduled to be removed in GitLab 14.0. If you're on GitLab 13.0 and later, switching new projects to legacy storage is not possible. The option to choose between hashed and legacy storage in the admin area has been disabled. @@ -199,7 +199,7 @@ easy for Administrators to find where the repository is stored. On the other hand this has some drawbacks: -Storage location will concentrate huge amount of top-level namespaces. The +Storage location concentrates a huge number of top-level namespaces. The impact can be reduced by the introduction of [multiple storage paths](repository_storage_paths.md). @@ -209,6 +209,6 @@ an old removed or renamed project sharing the same URL. This means that `mygroup/myproject` from your backup may not be the same original project that is at that same URL today. -Any change in the URL will need to be reflected on disk (when groups / users or +Any change in the URL needs to be reflected on disk (when groups / users or projects are renamed). This can add a lot of load in big installations, especially if using any type of network based filesystem. diff --git a/doc/api/README.md b/doc/api/README.md index 3933431407c..3226b699932 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -97,7 +97,7 @@ HTTP/2 200 This can help you investigate an unexpected response. -### API Request that includes the exit code +### API request that includes the exit code If you want to expose the HTTP exit code, include the `--fail` option: @@ -110,8 +110,8 @@ The HTTP exit code can help you diagnose the success or failure of your REST cal ## Authentication -Most API requests require authentication, or will return public data only when -authentication isn't provided. For cases where it isn't required, this will be +Most API requests require authentication, or only return public data when +authentication isn't provided. For cases where it isn't required, this is mentioned in the documentation for each individual endpoint (for example, the [`/projects/:id` endpoint](projects.md#get-single-project)). @@ -133,7 +133,7 @@ to build applications or scripts that do so, the following options are available - [Impersonation tokens](#impersonation-tokens) - [Sudo](#sudo) -If authentication information is invalid or omitted, GitLab will return an error +If authentication information is invalid or omitted, GitLab returns an error message with a status code of `401`: ```json @@ -221,13 +221,13 @@ The token is valid as long as the job is running. ### Impersonation tokens Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md) -that can only be created by an admin for a specific user. They are a great fit +that can only be created by an administrator for a specific user. They are a great fit if you want to build applications or scripts that authenticate with the API as a specific user. They're an alternative to directly using the user's password or one of their personal access tokens, and to using the [Sudo](#sudo) feature, as the user's -(or admin's, in the case of Sudo) password or token may not be known, or may +(or administrator's in the case of Sudo) password or token may not be known, or may change over time. For more information, see the [users API](users.md#create-an-impersonation-token) @@ -292,7 +292,7 @@ message with a status code of `403`: } ``` -If an access token without the `sudo` scope is provided, an error message will +If an access token without the `sudo` scope is provided, an error message is be returned with a status code of `403`: ```json @@ -303,7 +303,7 @@ be returned with a status code of `403`: } ``` -If the sudo user ID or username cannot be found, an error message will be +If the sudo user ID or username cannot be found, an error message is returned with a status code of `404`: ```json @@ -357,7 +357,7 @@ The following table shows the possible return codes for API requests. | `204 No Content` | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. | | `201 Created` | The `POST` request was successful and the resource is returned as JSON. | | `304 Not Modified` | Indicates that the resource has not been modified since the last request. | -| `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. | +| `400 Bad Request` | A required attribute of the API request is missing. For example, the title of an issue is not given. | | `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. | | `403 Forbidden` | The request is not allowed. For example, the user is not allowed to delete a project. | | `404 Not Found` | A resource could not be accessed. For example, an ID for a resource could not be found. | @@ -411,7 +411,7 @@ of the issue with ID `8` which belongs to the project with ID `9`: curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/issues/8/notes?per_page=3&page=2" ``` -The response will then be: +The response is: ```http HTTP/2 200 OK @@ -479,7 +479,7 @@ Status: 200 OK ``` CAUTION: **Deprecation:** -The `Links` header will be removed in GitLab 14.0 to be aligned with the +The `Links` header is scheduled to be removed in GitLab 14.0 to be aligned with the [W3C `Link` specification](https://www.w3.org/wiki/LinkHeader). The `Link` header was [added in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33714) and should be used instead. @@ -525,8 +525,8 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ``` Path parameters that are required to be URL-encoded must be followed. If not, -it won't match an API endpoint, and will respond with a 404. If there's -something in front of the API (for example, Apache), ensure that it won't decode +it doesn't match an API endpoint and responds with a 404. If there's +something in front of the API (for example, Apache), ensure that it doesn't decode the URL-encoded path parameters. ## Namespaced path encoding @@ -657,7 +657,7 @@ Such errors appear in the following cases: - An attribute did not pass the validation (for example, the user bio is too long). -When an attribute is missing, you will get something like: +When an attribute is missing, you receive something like: ```http HTTP/1.1 400 Bad Request @@ -667,7 +667,7 @@ Content-Type: application/json } ``` -When a validation error occurs, error messages will be different. They will hold +When a validation error occurs, error messages are different. They hold all details of validation errors: ```http @@ -706,7 +706,7 @@ follows: ## Unknown route -When you attempt to access an API URL that doesn't exist, you will receive +When you attempt to access an API URL that doesn't exist, you receive a 404 Not Found message. ```http diff --git a/doc/api/metrics_dashboard_annotations.md b/doc/api/metrics_dashboard_annotations.md index c23ed657583..65e31eafd56 100644 --- a/doc/api/metrics_dashboard_annotations.md +++ b/doc/api/metrics_dashboard_annotations.md @@ -24,7 +24,7 @@ Parameters: |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `dashboard_path` | string | yes | ID of the dashboard which needs to be annotated. Treated as a CGI-escaped path, and automatically un-escaped. | | `starting_at` | string | yes | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking start point of annotation. | -| `ending_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking end point of annotation. When not supplied annotation will be displayed as single event at start point. | +| `ending_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking end point of annotation. When not supplied, an annotation displays as a single event at the start point. | | `description` | string | yes | Description of the annotation. | ```shell diff --git a/doc/api/metrics_user_starred_dashboards.md b/doc/api/metrics_user_starred_dashboards.md index 8c2894293ba..a4040b53289 100644 --- a/doc/api/metrics_user_starred_dashboards.md +++ b/doc/api/metrics_user_starred_dashboards.md @@ -54,7 +54,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `dashboard_path` | string | no | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied all dashboards within given projects will be removed from favorites. | +| `dashboard_path` | string | no | URL-encoded path to file defining the dashboard which should no longer be marked as favorite. When not supplied, all dashboards within given projects are removed from favorites. | ```shell curl --request DELETE --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/projects/20/metrics/user_starred_dashboards \ diff --git a/doc/api/settings.md b/doc/api/settings.md index 5b04ee9d368..907256f3901 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -331,7 +331,7 @@ listed in the descriptions of the relevant settings. | `receive_max_input_size` | integer | no | Maximum push size (MB). | | `repository_checks_enabled` | boolean | no | GitLab will periodically run `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | | `repository_size_limit` | integer | no | **(PREMIUM)** Size limit per repository (MB) | -| `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to [weights](../administration/repository_storage_paths.md#choose-where-new-repositories-will-be-stored). New projects are created in one of these stores, chosen by a weighted random selection. | +| `repository_storages_weighted` | hash of strings to integers | no | (GitLab 13.1 and later) Hash of names of taken from `gitlab.yml` to [weights](../administration/repository_storage_paths.md#choose-where-new-repositories-are-stored). New projects are created in one of these stores, chosen by a weighted random selection. | | `repository_storages` | array of strings | no | (GitLab 13.0 and earlier) List of names of enabled storage paths, taken from `gitlab.yml`. New projects are created in one of these stores, chosen at random. | | `require_admin_approval_after_user_signup` | boolean | no | When enabled, any user that signs up for an account using the registration form is placed under a **Pending approval** state and has to be explicitly [approved](../user/admin_area/approving_users.md) by an administrator. | | `require_two_factor_authentication` | boolean | no | (**If enabled, requires:** `two_factor_grace_period`) Require all users to set up Two-factor authentication. | diff --git a/doc/architecture/blueprints/cloud_native_build_logs/index.md b/doc/architecture/blueprints/cloud_native_build_logs/index.md index f901a724653..27b7a8ffae3 100644 --- a/doc/architecture/blueprints/cloud_native_build_logs/index.md +++ b/doc/architecture/blueprints/cloud_native_build_logs/index.md @@ -109,16 +109,22 @@ of complexity, maintenance cost and enormous, negative impact on availability. 1. ✓ Evaluate performance and edge-cases, iterate to improve the new architecture 1. ✓ Design cloud native build logs correctness verification mechanisms 1. ✓ Build observability mechanisms around performance and correctness -1. Rollout the feature into production environment incrementally +1. ✓ Rollout the feature into production environment incrementally The work needed to make the new architecture production ready and enabled on -GitLab.com is being tracked in [Cloud Native Build Logs on +GitLab.com had been tracked in [Cloud Native Build Logs on GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/4275) epic. Enabling this feature on GitLab.com is a subtask of [making the new architecture generally available](https://gitlab.com/groups/gitlab-org/-/epics/3791) for everyone. +## Status + +This change has been implemented and enabled on GitLab.com. + +We are working on [an epic to make this feature more resilient and observable](https://gitlab.com/groups/gitlab-org/-/epics/4860). + ## Who Proposal: @@ -137,7 +143,7 @@ DRIs: | Role | Who |------------------------------|------------------------| -| Product | Jason Yavorska | +| Product | Thao Yeager | | Leadership | Darby Frey | | Engineering | Grzegorz Bizon | diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index dfa92d469bc..3f1aea0a4d9 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -38,12 +38,12 @@ runtime dependencies needed to compile the project: be configured to pass intermediate build results between stages, this should be done with artifacts instead. -- `artifacts`: **Use for stage results that will be passed between stages.** +- `artifacts`: **Use for stage results that are passed between stages.** Artifacts are files generated by a job which are stored and uploaded, and can then be fetched and used by jobs in later stages of the **same pipeline**. In other words, [you can't create an artifact in job-A in stage-1, and then use this artifact in job-B in stage-1](https://gitlab.com/gitlab-org/gitlab/-/issues/25837). - This data will not be available in different pipelines, but is available to be downloaded + This data is be available in different pipelines, but is available to be downloaded from the UI. The name `artifacts` sounds like it's only useful outside of the job, like for downloading @@ -87,7 +87,7 @@ cache, when declaring `cache` in your jobs, use one or a mix of the following: - [Tag your runners](../runners/README.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs that share their cache. - [Use sticky runners](../runners/README.md#prevent-a-specific-runner-from-being-enabled-for-other-projects) - that will be only available to a particular project. + that are only available to a particular project. - [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example, different caches on each branch). For that, you can take advantage of the [CI/CD predefined variables](../variables/README.md#predefined-environment-variables). @@ -106,7 +106,7 @@ of the following must be true: where the cache is stored in S3 buckets (like shared runners on GitLab.com). - Use multiple runners (not in autoscale mode) of the same architecture that share a common network-mounted directory (using NFS or something similar) - where the cache will be stored. + where the cache is stored. TIP: **Tip:** Read about the [availability of the cache](#availability-of-the-cache) @@ -125,7 +125,7 @@ cache: While this feels like it might be safe from accidentally overwriting the cache, it means merge requests get slow first pipelines, which might be a bad developer experience. The next time a new commit is pushed to the branch, the -cache will be re-used. +cache is re-used. To enable per-job and per-branch caching: @@ -160,7 +160,7 @@ cache: ### Disabling cache on specific jobs -If you have defined the cache globally, it means that each job will use the +If you have defined the cache globally, it means that each job uses the same definition. You can override this behavior per-job, and if you want to disable it completely, use an empty hash: @@ -431,9 +431,9 @@ Here's what happens behind the scenes: 1. `script` is executed. 1. Pipeline finishes. -By using a single runner on a single machine, you'll not have the issue where +By using a single runner on a single machine, you don't have the issue where `job B` might execute on a runner different from `job A`, thus guaranteeing the -cache between stages. That will only work if the build goes from stage `build` +cache between stages. That only works if the build goes from stage `build` to `test` in the same runner/machine, otherwise, you [might not have the cache available](#cache-mismatch). @@ -442,7 +442,7 @@ During the caching process, there's also a couple of things to consider: - If some other job, with another cache configuration had saved its cache in the same zip file, it is overwritten. If the S3 based shared cache is used, the file is additionally uploaded to S3 to an object based on the cache - key. So, two jobs with different paths, but the same cache key, will overwrite + key. So, two jobs with different paths, but the same cache key, overwrites their cache. - When extracting the cache from `cache.zip`, everything in the zip file is extracted in the job's working directory (usually the repository which is @@ -450,7 +450,7 @@ During the caching process, there's also a couple of things to consider: things in the archive of `job B`. The reason why it works this way is because the cache created for one runner -often will not be valid when used by a different one which can run on a +often isn't valid when used by a different one which can run on a **different architecture** (e.g., when the cache includes binary files). And since the different steps might be executed by runners running on different machines, it is a safe default. @@ -472,7 +472,7 @@ Let's explore some examples. #### Examples Let's assume you have only one runner assigned to your project, so the cache -will be stored in the runner's machine by default. If two jobs, A and B, +is stored in the runner's machine by default. If two jobs, A and B, have the same cache key, but they cache different paths, cache B would overwrite cache A, even if their `paths` don't match: @@ -506,15 +506,15 @@ job B: 1. `job B` runs. 1. The previous cache, if any, is unzipped. 1. `vendor/` is cached as cache.zip and overwrites the previous one. -1. The next time `job A` runs it will use the cache of `job B` which is different - and thus will be ineffective. +1. The next time `job A` runs it uses the cache of `job B` which is different + and thus isn't effective. To fix that, use different `keys` for each job. In another case, let's assume you have more than one runner assigned to your project, but the distributed cache is not enabled. The second time the pipeline is run, we want `job A` and `job B` to re-use their cache (which in this case -will be different): +is different): ```yaml stages: @@ -553,7 +553,7 @@ To start with a fresh copy of the cache, there are two ways to do that. ### Clearing the cache by changing `cache:key` All you have to do is set a new `cache: key` in your `.gitlab-ci.yml`. In the -next run of the pipeline, the cache will be stored in a different location. +next run of the pipeline, the cache is stored in a different location. ### Clearing the cache manually @@ -567,7 +567,7 @@ via GitLab's UI:  -1. On the next push, your CI/CD job will use a new cache. +1. On the next push, your CI/CD job uses a new cache. Behind the scenes, this works by increasing a counter in the database, and the value of that counter is used to create the key for the cache by appending an diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index f8e2a2b7eb0..8430fe4cd1b 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -19,12 +19,12 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:  - GitLab will import the repository and enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository). + GitLab imports the repository and enables [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository). 1. In GitLab create a [Personal Access Token](../../user/profile/personal_access_tokens.md) - with `api` scope. This will be used to authenticate requests from the web - hook that will be created in Bitbucket to notify GitLab of new commits. + with `api` scope. This is used to authenticate requests from the web + hook that is created in Bitbucket to notify GitLab of new commits. 1. In Bitbucket, from **Settings > Webhooks**, create a new web hook to notify GitLab of new commits. @@ -62,7 +62,7 @@ To use GitLab CI/CD with a Bitbucket Cloud repository: 1. In Bitbucket, add a script to push the pipeline status to Bitbucket. - > Note: changes made in GitLab will be overwritten by any changes made + > Note: changes made in GitLab are overwritten by any changes made > upstream in Bitbucket. Create a file `build_status` and insert the script below and run diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index b6f885ff220..1060f576be3 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -28,7 +28,7 @@ To perform a one-off authorization with GitHub to grant GitLab access your repositories: 1. Open <https://github.com/settings/tokens/new> to create a **Personal Access - Token**. This token will be used to access your repository and push commit + Token**. This token is used to access your repository and push commit statuses to GitHub. The `repo` and `admin:repo_hook` should be enable to allow GitLab access to @@ -43,12 +43,12 @@ repositories: 1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). -GitLab will: +GitLab: -1. Import the project. -1. Enable [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) -1. Enable [GitHub project integration](../../user/project/integrations/github.md) -1. Create a web hook on GitHub to notify GitLab of new commits. +1. Imports the project. +1. Enables [Pull Mirroring](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository) +1. Enables [GitHub project integration](../../user/project/integrations/github.md) +1. Creates a web hook on GitHub to notify GitLab of new commits. ## Connect manually @@ -57,7 +57,7 @@ To use **GitHub Enterprise** with **GitLab.com**, use this method. To manually enable GitLab CI/CD for your repository: 1. In GitHub open <https://github.com/settings/tokens/new> create a **Personal - Access Token.** GitLab will use this token to access your repository and + Access Token.** GitLab uses this token to access your repository and push commit statuses. Enter a **Token description** and update the scope to allow: @@ -68,7 +68,7 @@ To manually enable GitLab CI/CD for your repository: URL for your GitHub repository. If your project is private, use the personal access token you just created for authentication. - GitLab will automatically configure polling-based pull mirroring. + GitLab automatically configures polling-based pull mirroring. 1. Still in GitLab, enable the [GitHub project integration](../../user/project/integrations/github.md) from **Settings > Integrations.** diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index ae6cb759d23..db90714fa6b 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -18,7 +18,7 @@ GitLab CI/CD can be used with: Instead of moving your entire project to GitLab, you can connect your external repository to get the benefits of GitLab CI/CD. -Connecting an external repository will set up [repository mirroring](../../user/project/repository/repository_mirroring.md) +Connecting an external repository sets up [repository mirroring](../../user/project/repository/repository_mirroring.md) and create a lightweight project with issues, merge requests, wiki, and snippets disabled. These features [can be re-enabled later](../../user/project/settings/index.md#sharing-and-permissions). @@ -74,7 +74,7 @@ If changes are pushed to the branch referenced by the Pull Request and the Pull Request is still open, a pipeline for the external pull request is created. -GitLab CI/CD will create 2 pipelines in this case. One for the +GitLab CI/CD creates 2 pipelines in this case. One for the branch push and one for the external pull request. After the Pull Request is closed, no pipelines are created for the external pull @@ -89,10 +89,10 @@ The variable names are prefixed with `CI_EXTERNAL_PULL_REQUEST_`. ### Limitations -This feature currently does not support Pull Requests from fork repositories. Any Pull Requests from fork repositories will be ignored. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/5667). +This feature currently does not support Pull Requests from fork repositories. Any Pull Requests from fork repositories are ignored. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/5667). -Given that GitLab will create 2 pipelines, if changes are pushed to a remote branch that -references an open Pull Request, both will contribute to the status of the Pull Request +Given that GitLab creates 2 pipelines, if changes are pushed to a remote branch that +references an open Pull Request, both contribute to the status of the Pull Request via GitHub integration. If you want to exclusively run pipelines on external pull requests and not on branches you can add `except: [branches]` to the job specs. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/24089#workaround). diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index 04f27c584b7..47cc6f8e677 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -17,7 +17,7 @@ be set up. For example, you may have a specific tool or separate website that is built as part of your main project. Using a DAG, you can specify the relationship between -these jobs and GitLab will then execute the jobs as soon as possible instead of waiting +these jobs and GitLab executes the jobs as soon as possible instead of waiting for each stage to complete. Unlike other DAG solutions for CI/CD, GitLab does not require you to choose one or the @@ -44,9 +44,9 @@ It has a pipeline that looks like the following: | build_d | test_d | deploy_d | Using a DAG, you can relate the `_a` jobs to each other separately from the `_b` jobs, -and even if service `a` takes a very long time to build, service `b` will not -wait for it and will finish as quickly as it can. In this very same pipeline, `_c` and -`_d` can be left alone and will run together in staged sequence just like any normal +and even if service `a` takes a very long time to build, service `b` doesn't +wait for it and finishes as quickly as it can. In this very same pipeline, `_c` and +`_d` can be left alone and run together in staged sequence just like any normal GitLab pipeline. ## Use cases @@ -60,7 +60,7 @@ but related microservices. Additionally, a DAG can help with general speediness of pipelines and helping to deliver fast feedback. By creating dependency relationships that don't unnecessarily -block each other, your pipelines will run as quickly as possible regardless of +block each other, your pipelines run as quickly as possible regardless of pipeline stages, ensuring output (including errors) is available to developers as quickly as possible. @@ -88,13 +88,13 @@ are certain use cases that you may need to work around. For more information: > - It's enabled on GitLab.com. > - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-needs-visualization). -The needs visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph will display all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view. +The needs visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph displays all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view. To see the needs visualization, click on the **Needs** tab when viewing a pipeline that uses the `needs:` keyword.  -Clicking a node will highlight all the job paths it depends on. +Clicking a node highlights all the job paths it depends on.  diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index ebbfde09c67..3ef244ab473 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -381,7 +381,7 @@ content: Update the `config.toml` file to mount the file to `/etc/docker/daemon.json`. This would mount the file for **every** -container that is created by GitLab Runner. The configuration will be +container that is created by GitLab Runner. The configuration is picked up by the `dind` service. ```toml diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index f9b09bada14..fdb13f384ce 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -37,8 +37,8 @@ few important details: - The kaniko debug image is recommended (`gcr.io/kaniko-project/executor:debug`) because it has a shell, and a shell is required for an image to be used with GitLab CI/CD. -- The entrypoint will need to be [overridden](using_docker_images.md#overriding-the-entrypoint-of-an-image), - otherwise the build script will not run. +- The entrypoint needs to be [overridden](using_docker_images.md#overriding-the-entrypoint-of-an-image), + otherwise the build script doesn't run. - A Docker `config.json` file needs to be created with the authentication information for the desired container registry. @@ -47,7 +47,7 @@ In the following example, kaniko is used to: 1. Build a Docker image. 1. Then push it to [GitLab Container Registry](../../user/packages/container_registry/index.md). -The job will run only when a tag is pushed. A `config.json` file is created under +The job runs only when a tag is pushed. A `config.json` file is created under `/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the [environment variables](../variables/README.md#predefined-environment-variables) GitLab CI/CD provides. diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index 699d04f632c..85f0424554a 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -15,17 +15,17 @@ using the Shell executor. ## Test PHP projects using the Docker executor While it is possible to test PHP apps on any system, this would require manual -configuration from the developer. To overcome this we will be using the +configuration from the developer. To overcome this we use the official [PHP Docker image](https://hub.docker.com/_/php) that can be found in Docker Hub. -This will allow us to test PHP projects against different versions of PHP. +This allows us to test PHP projects against different versions of PHP. However, not everything is plug 'n' play, you still need to configure some things manually. As with every job, you need to create a valid `.gitlab-ci.yml` describing the build environment. -Let's first specify the PHP image that will be used for the job process +Let's first specify the PHP image that is used for the job process (you can read more about what an image means in the runner's lingo reading about [Using Docker images](../docker/using_docker_images.md#what-is-an-image)). @@ -106,7 +106,7 @@ test:app: ### Test against different PHP versions in Docker builds Testing against multiple versions of PHP is super easy. Just add another job -with a different Docker image version and the runner will do the rest: +with a different Docker image version and the runner does the rest: ```yaml before_script: @@ -128,7 +128,7 @@ test:7.0: ### Custom PHP configuration in Docker builds -There are times where you will need to customise your PHP environment by +There are times where you need to customise your PHP environment by putting your `.ini` file into `/usr/local/etc/php/conf.d/`. For that purpose add a `before_script` action: @@ -168,7 +168,7 @@ The [phpenv](https://github.com/phpenv/phpenv) project allows you to easily mana each with its own configuration. This is especially useful when testing PHP projects with the Shell executor. -You will have to install it on your build machine under the `gitlab-runner` +You have to install it on your build machine under the `gitlab-runner` user following [the upstream installation guide](https://github.com/phpenv/phpenv#installation). Using phpenv also allows to easily configure the PHP environment with: @@ -181,7 +181,7 @@ phpenv config-add my_config.ini [is abandoned](https://github.com/phpenv/phpenv/issues/57). There is a fork at [madumlao/phpenv](https://github.com/madumlao/phpenv) that tries to bring the project back to life. [CHH/phpenv](https://github.com/CHH/phpenv) also - seems like a good alternative. Picking any of the mentioned tools will work + seems like a good alternative. Picking any of the mentioned tools works with the basic phpenv commands. Guiding you to choose the right phpenv is out of the scope of this tutorial.* @@ -274,4 +274,4 @@ that runs on [GitLab.com](https://gitlab.com) using our publicly available [shared runners](../runners/README.md). Want to hack on it? Simply fork it, commit, and push your changes. Within a few -moments the changes will be picked by a public runner and the job will begin. +moments the changes are picked by a public runner and the job begins. diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index b24ee66fdba..4a296ddcd1c 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -8,7 +8,7 @@ type: concepts # Introduction to CI/CD with GitLab -In this document, we'll present an overview of the concepts of Continuous Integration, +This document presents an overview of the concepts of Continuous Integration, Continuous Delivery, and Continuous Deployment, as well as an introduction to GitLab CI/CD. @@ -100,18 +100,18 @@ located in the root path of your repository. In this file, you can define the scripts you want to run, define include and cache dependencies, choose commands you want to run in sequence and those you want to run in parallel, define where you want to -deploy your app, and specify whether you will want to run the scripts automatically +deploy your app, and specify whether you want to run the scripts automatically or trigger any of them manually. After you're familiar with GitLab CI/CD you can add more advanced steps into the configuration file. -To add scripts to that file, you'll need to organize them in a +To add scripts to that file, you need to organize them in a sequence that suits your application and are in accordance with the tests you wish to perform. To visualize the process, imagine that all the scripts you add to the configuration file are the same as the commands you run on a terminal on your computer. After you've added your `.gitlab-ci.yml` configuration file to your -repository, GitLab will detect it and run your scripts with the +repository, GitLab detects it and run your scripts with the tool called [GitLab Runner](https://docs.gitlab.com/runner/), which works similarly to your terminal. @@ -191,7 +191,7 @@ lifecycle, as shown in the illustration below.  If you look at the image from the left to the right, -you'll see some of the features available in GitLab +you can see some of the features available in GitLab according to each stage (Verify, Package, Release). 1. **Verify**: diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index ac9cda4e46c..1e405bfd9ec 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -57,7 +57,7 @@ When you use this method, you have to specify `only: - merge_requests` for each example, the pipeline contains a `test` job that is configured to run on merge requests. The `build` and `deploy` jobs don't have the `only: - merge_requests` keyword, -so they will not run on merge requests. +so they don't run on merge requests. ```yaml build: @@ -82,7 +82,7 @@ deploy: #### Excluding certain jobs The behavior of the `only: [merge_requests]` keyword is such that _only_ jobs with -that keyword are run in the context of a merge request; no other jobs will be run. +that keyword are run in the context of a merge request; no other jobs run. However, you can invert this behavior and have all of your jobs run _except_ for one or two. @@ -120,8 +120,8 @@ C: Therefore: -- Since `A` and `B` are getting the `only:` rule to execute in all cases, they will always run. -- Since `C` specifies that it should only run for merge requests, it will not run for any pipeline +- Since `A` and `B` are getting the `only:` rule to execute in all cases, they always run. +- Since `C` specifies that it should only run for merge requests, it doesn't run for any pipeline except a merge request pipeline. This helps you avoid having to add the `only:` rule to all of your jobs to make @@ -209,7 +209,7 @@ The variable names begin with the `CI_MERGE_REQUEST_` prefix. If you are experiencing duplicated pipelines when using `rules`, take a look at the [important differences between `rules` and `only`/`except`](../yaml/README.md#prevent-duplicate-pipelines), -which will help you get your starting configuration correct. +which helps you get your starting configuration correct. If you are seeing two pipelines when using `only/except`, please see the caveats related to using `only/except` above (or, consider moving to `rules`). diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md index 9c6fbba1337..28d205ad8b1 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -19,8 +19,8 @@ the source branch have already been merged into the target branch. If the pipeline fails due to a problem in the target branch, you can wait until the target is fixed and re-run the pipeline. -This new pipeline will run as if the source is merged with the updated target, and you -will not need to rebase. +This new pipeline runs as if the source is merged with the updated target, and you +don't need to rebase. The pipeline does not automatically run when the target branch changes. Only changes to the source branch trigger a new pipeline. If a long time has passed since the last successful @@ -33,7 +33,7 @@ When the merge request can't be merged, the pipeline runs against the source bra - The merge request is a [**Draft** merge request](../../../user/project/merge_requests/work_in_progress_merge_requests.md). In these cases, the pipeline runs as a [pipeline for merge requests](../index.md) -and is labeled as `detached`. If these cases no longer exist, new pipelines will +and is labeled as `detached`. If these cases no longer exist, new pipelines again run against the merged results. Any user who has developer [permissions](../../../user/permissions.md) can run a @@ -71,7 +71,7 @@ GitLab [automatically displays](merge_trains/index.md#add-a-merge-request-to-a-m a **Start/Add Merge Train button**. Generally, this is a safer option than merging merge requests immediately, because your -merge request will be evaluated with an expected post-merge result before the actual +merge request is evaluated with an expected post-merge result before the actual merge happens. For more information, read the [documentation on Merge Trains](merge_trains/index.md). @@ -84,10 +84,10 @@ GitLab CI/CD can detect the presence of redundant pipelines, and cancels them to conserve CI resources. When a user merges a merge request immediately within an ongoing merge -train, the train will be reconstructed, as it will recreate the expected +train, the train is reconstructed, because it recreates the expected post-merge commit and pipeline. In this case, the merge train may already have pipelines running against the previous expected post-merge commit. -These pipelines are considered redundant and will be automatically +These pipelines are considered redundant and are automatically canceled. ## Troubleshooting diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md index d4099cdeafd..a7d111f7ee6 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -39,7 +39,7 @@ To add a merge request to a merge train, you need [permissions](../../../../user Each merge train can run a maximum of **twenty** pipelines in parallel. If more than twenty merge requests are added to the merge train, the merge requests -will be queued until a slot in the merge train is free. There is no limit to the +are queued until a slot in the merge train is free. There is no limit to the number of merge requests that can be queued. ## Merge train example @@ -55,7 +55,7 @@ If the pipeline for `B` fails, it is removed from the train. The pipeline for `C` restarts with the `A` and `C` changes, but without the `B` changes. If `A` then completes successfully, it merges into the target branch, and `C` continues -to run. If more merge requests are added to the train, they will now include the `A` +to run. If more merge requests are added to the train, they now include the `A` changes that are included in the target branch, and the `C` changes that are from the merge request already in the train. @@ -152,7 +152,7 @@ is recreated and all pipelines restart. ### Merge request dropped from the merge train immediately If a merge request is not mergeable (for example, it's a draft merge request, there is a merge -conflict, etc.), your merge request will be dropped from the merge train automatically. +conflict, etc.), your merge request is dropped from the merge train automatically. In these cases, the reason for dropping the merge request is in the **system notes**. @@ -179,7 +179,7 @@ for more information. A Merge Train pipeline cannot be retried because the merge request is dropped from the merge train upon failure. For this reason, the retry button does not appear next to the pipeline icon. -In the case of pipeline failure, you should [re-enqueue](#add-a-merge-request-to-a-merge-train) the merge request to the merge train, which will then initiate a new pipeline. +In the case of pipeline failure, you should [re-enqueue](#add-a-merge-request-to-a-merge-train) the merge request to the merge train, which then initiates a new pipeline. ### Unable to add to merge train with message "The pipeline for this merge request failed." @@ -195,9 +195,10 @@ you can clear the **Pipelines must succeed** check box and keep **Enable merge trains and pipelines for merged results** (merge trains) enabled. If you want to keep the **Pipelines must succeed** option enabled along with Merge -Trains, you can create a new pipeline for merged results when this error occurs by -going to the **Pipelines** tab and clicking **Run pipeline**. Then click -**Start/Add to merge train when pipeline succeeds**. +Trains, create a new pipeline for merged results when this error occurs: + +1. Go to the **Pipelines** tab and click **Run pipeline**. +1. Click **Start/Add to merge train when pipeline succeeds**. See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/35135) for more information. diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 6d277f9ae99..53c81901718 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -59,7 +59,7 @@ on non-Go GitLab subsystems. GitLab uses the `GITLAB_TRACING` environment variable to configure distributed tracing. The same configuration is used for all components (e.g., Workhorse, Rails, etc). -When `GITLAB_TRACING` is not set, the application will not be instrumented, meaning that there is +When `GITLAB_TRACING` is not set, the application isn't instrumented, meaning that there is no overhead at all. To enable `GITLAB_TRACING`, a valid _"configuration-string"_ value should be set, with a URL-like @@ -94,8 +94,8 @@ by typing `p` `b` in the browser window. Once the performance bar is enabled, click on the **Trace** link in the performance bar to go to the Jaeger UI. -The Jaeger search UI will return a query for the `Correlation-ID` of the current request. Normally, -this search should return a single trace result. Clicking this result will show the detail of the +The Jaeger search UI returns a query for the `Correlation-ID` of the current request. Normally, +this search should return a single trace result. Clicking this result shows the detail of the trace in a hierarchical time-line.  @@ -154,7 +154,7 @@ This should start the process with the default listening ports. ### 2. Configure the `GITLAB_TRACING` environment variable -Once you have Jaeger running, you'll need to configure the `GITLAB_TRACING` variable with the +Once you have Jaeger running, configure the `GITLAB_TRACING` variable with the appropriate configuration string. **TL;DR:** If you are running everything on the same host, use the following value: @@ -178,7 +178,7 @@ This configuration string uses the Jaeger driver `opentracing://jaeger` with the | `udp_endpoint` | `localhost:6831` | This is the default. Configures Jaeger to send trace information to the UDP listener on port `6831` using compact thrift protocol. Note that we've experienced some issues with the [Jaeger Client for Ruby](https://github.com/salemove/jaeger-client-ruby) when using this protocol. | | `sampler` | `probabalistic` | Configures Jaeger to use a probabilistic random sampler. The rate of samples is configured by the `sampler_param` value. | | `sampler_param` | `0.01` | Use a ratio of `0.01` to configure the `probabalistic` sampler to randomly sample _1%_ of traces. | -| `service_name` | `api` | Override the service name used by the Jaeger backend. This parameter will take precedence over the application-supplied value. | +| `service_name` | `api` | Override the service name used by the Jaeger backend. This parameter takes precedence over the application-supplied value. | NOTE: **Note:** The same `GITLAB_TRACING` value should to be configured in the environment @@ -189,7 +189,7 @@ variables for all GitLab processes, including Workhorse, Gitaly, Rails, and Side After the `GITLAB_TRACING` environment variable is exported to all GitLab services, start the application. -When `GITLAB_TRACING` is configured properly, the application will log this on startup: +When `GITLAB_TRACING` is configured properly, the application logs this on startup: ```shell 13:41:53 gitlab-workhorse.1 | 2019/02/12 13:41:53 Tracing enabled @@ -198,7 +198,7 @@ When `GITLAB_TRACING` is configured properly, the application will log this on s ... ``` -If `GITLAB_TRACING` is not configured correctly, this will also be logged: +If `GITLAB_TRACING` is not configured correctly, this issue is logged: ```shell 13:43:45 gitaly.1 | 2019/02/12 13:43:45 skipping tracing configuration step: tracer: unable to load driver mytracer @@ -216,5 +216,5 @@ not set. By default, the Jaeger search UI is available at <http://localhost:16686/search>. TIP: **Tip:** -Don't forget that you will need to generate traces by using the application before +Don't forget that you must generate traces by using the application before they appear in the Jaeger UI. diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 69a8ff10878..d7b1c41feec 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -38,8 +38,8 @@ Documentation issues and merge requests are part of their respective repositorie The [CI pipeline for the main GitLab project](../pipelines.md) is configured to automatically run only the jobs that match the type of contribution. If your contribution contains -**only** documentation changes, then only documentation-related jobs will be run, and -the pipeline will complete much faster than a code contribution. +**only** documentation changes, then only documentation-related jobs run, and +the pipeline completes much faster than a code contribution. If you are submitting documentation-only changes to Runner, Omnibus, or Charts, the fast pipeline is not determined automatically. Instead, create branches for @@ -152,7 +152,7 @@ comments: false Each page can have additional, optional metadata (set in the [default.html](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/fc3577921343173d589dfa43d837b4307e4e620f/layouts/default.html#L30-52) -Nanoc layout), which will be displayed at the top of the page if defined: +Nanoc layout), which is displayed at the top of the page if defined: - `reading_time`: If you want to add an indication of the approximate reading time of a page, you can set `reading_time` to `true`. This uses a simple @@ -225,9 +225,9 @@ Things to note: the document might also be referenced in the views of GitLab (`app/`) which will render when visiting `/help`, and sometimes in the testing suite (`spec/`). You must search these paths for references to the doc and update them as well. -- The above `git grep` command will search recursively in the directory you run +- The above `git grep` command searches recursively in the directory you run it in for `workflow/lfs/lfs_administration` and `lfs/lfs_administration` - and will print the file and the line where this file is mentioned. + and prints the file and the line where this file is mentioned. You may ask why the two greps. Since [we use relative paths to link to documentation](styleguide/index.md#links), sometimes it might be useful to search a path deeper. - The `*.md` extension is not used when a document is linked to GitLab's @@ -267,7 +267,7 @@ Before getting started, make sure you read the introductory section - Label the MR `Documentation` (can only be done by people with `developer` access, for example, GitLab team members) - Assign the correct milestone per note below (can only be done by people with `developer` access, for example, GitLab team members) -Documentation will be merged if it is an improvement on existing content, +Documentation is merged if it is an improvement on existing content, represents a good-faith effort to follow the template and style standards, and is believed to be accurate. @@ -285,16 +285,16 @@ Every GitLab instance includes the documentation, which is available at `/help` (`https://gitlab.example.com/help`). For example, <https://gitlab.com/help>. The documentation available online on <https://docs.gitlab.com> is deployed every four hours from the `master` branch of GitLab, Omnibus, and Runner. Therefore, -after a merge request gets merged, it will be available online on the same day. -However, it will be shipped (and available on `/help`) within the milestone assigned +after a merge request gets merged, it is available online on the same day. +However, it's shipped (and available on `/help`) within the milestone assigned to the MR. For example, let's say your merge request has a milestone set to 11.3, which -will be released on 2018-09-22. If it gets merged on 2018-09-15, it will be +a release date of 2018-09-22. If it gets merged on 2018-09-15, it is available online on 2018-09-15, but, as the feature freeze date has passed, if the MR does not have a `~"Pick into 11.3"` label, the milestone has to be changed -to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22, -with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab +to 11.4 and it ships with all GitLab packages only on 2018-10-22, +with GitLab 11.4. Meaning, it's available only with `/help` from GitLab 11.4 onward, but available on <https://docs.gitlab.com/> on the same day it was merged. ### Linking to `/help` @@ -365,7 +365,7 @@ You can combine one or more of the following: ### GitLab `/help` tests Several [RSpec tests](https://gitlab.com/gitlab-org/gitlab/blob/master/spec/features/help_pages_spec.rb) -are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) will work correctly from `/help`. +are run to ensure GitLab documentation renders and works correctly. In particular, that [main docs landing page](../../README.md) works correctly from `/help`. For example, [GitLab.com's `/help`](https://gitlab.com/help). ## Docs site architecture @@ -392,20 +392,20 @@ The live preview is currently enabled for the following projects: If your merge request has docs changes, you can use the manual `review-docs-deploy` job to deploy the docs review app for your merge request. -You will need at least Maintainer permissions to be able to run it. +You need at least Maintainer permissions to be able to run it.  You must push a branch to those repositories, as it doesn't work for forks. -The `review-docs-deploy*` job will: +The `review-docs-deploy*` job: -1. Create a new branch in the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) +1. Creates a new branch in the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) project named after the scheme: `docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID`, where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ee` for EE, `omnibus` for Omnibus GitLab, etc, and `CI_MERGE_REQUEST_IID` is the ID of the respective merge request. -1. Trigger a cross project pipeline and build the docs site with your changes. +1. Triggers a cross project pipeline and build the docs site with your changes. In case the review app URL returns 404, this means that either the site is not yet deployed, or something went wrong with the remote pipeline. Give it a few @@ -414,8 +414,8 @@ remote pipeline from the link in the merge request's job output. If the pipeline failed or got stuck, drop a line in the `#docs` chat channel. Make sure that you always delete the branch of the merge request you were -working on. If you don't, the remote docs branch won't be removed either, -and the server where the Review Apps are hosted will eventually be out of +working on. If you don't, the remote docs branch isn't removed either, +and the server where the Review Apps are hosted can eventually run out of disk space. TIP: **Tip:** @@ -449,7 +449,7 @@ If you want to know the in-depth details, here's what's really happening: - The number of the merge request is added so that you can know by the `gitlab-docs` branch name the merge request it originated from. 1. The remote branch is then created if it doesn't exist (meaning you can - re-run the manual job as many times as you want and this step will be skipped). + re-run the manual job as many times as you want and this step is skipped). 1. A new cross-project pipeline is triggered in the docs project. 1. The preview URL is shown both at the job output and in the merge request widget. You also get the link to the remote pipeline. @@ -537,7 +537,8 @@ To have the screenshot focuses few more steps are needed: - **wait for the content**: `expect(screenshot_area).to have_content 'Expiration interval'` - **set the crop area**: `set_crop_data(screenshot_area, 20)` -In particular `set_crop_data` accepts as arguments: a `DOM` element and a padding, the padding will be added around the element enlarging the screenshot area. +In particular, `set_crop_data` accepts as arguments: a `DOM` element and a +padding. The padding is added around the element, enlarging the screenshot area. #### Live example diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 8b4e5090abb..9b2081b2821 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -84,7 +84,7 @@ If your test-suite is failing with Gitaly issues, as a first step, try running: rm -rf tmp/tests/gitaly ``` -During RSpec tests, the Gitaly instance will write logs to `gitlab/log/gitaly-test.log`. +During RSpec tests, the Gitaly instance writes logs to `gitlab/log/gitaly-test.log`. ## Legacy Rugged code @@ -124,23 +124,23 @@ Most of this code exists in the `lib/gitlab/git/rugged_impl` directory. NOTE: **Note:** You should NOT need to add or modify code related to Rugged unless explicitly discussed with the [Gitaly -Team](https://gitlab.com/groups/gl-gitaly/group_members). This code will +Team](https://gitlab.com/groups/gl-gitaly/group_members). This code does NOT work on GitLab.com or other GitLab instances that do not use NFS. ## `TooManyInvocationsError` errors During development and testing, you may experience `Gitlab::GitalyClient::TooManyInvocationsError` failures. -The `GitalyClient` will attempt to block against potential n+1 issues by raising this error +The `GitalyClient` attempts to block against potential n+1 issues by raising this error when Gitaly is called more than 30 times in a single Rails request or Sidekiq execution. -As a temporary measure, export `GITALY_DISABLE_REQUEST_LIMITS=1` to suppress the error. This will disable the n+1 detection +As a temporary measure, export `GITALY_DISABLE_REQUEST_LIMITS=1` to suppress the error. This disables the n+1 detection in your development environment. Please raise an issue in the GitLab CE or EE repositories to report the issue. Include the labels ~Gitaly ~performance ~"technical debt". Please ensure that the issue contains the full stack trace and error message of the `TooManyInvocationsError`. Also include any known failing tests if possible. -Isolate the source of the n+1 problem. This will normally be a loop that results in Gitaly being called for each +Isolate the source of the n+1 problem. This is normally a loop that results in Gitaly being called for each element in an array. If you are unable to isolate the problem, please contact a member of the [Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members) for assistance. @@ -154,7 +154,7 @@ Gitlab::GitalyClient.allow_n_plus_1_calls do end ``` -Once the code is wrapped in this block, this code-path will be excluded from n+1 detection. +Once the code is wrapped in this block, this code path is excluded from n+1 detection. ## Request counts @@ -184,12 +184,12 @@ branches and SHA to use a custom commit in <https://gitlab.com/gitlab-org/gitaly NOTE: **Note:** With the introduction of auto-deploy for Gitaly, the format of `GITALY_SERVER_VERSION` was aligned with Omnibus syntax. -It no longer supports `=revision`, it will evaluate the file content as a Git -reference (branch or SHA), only if it matches a semver it will prepend a `v`. +It no longer supports `=revision`, it evaluates the file content as a Git +reference (branch or SHA). Only if it matches a semver does it prepend a `v`. If you want to run tests locally against a modified version of Gitaly you can replace `tmp/tests/gitaly` with a symlink. This is much faster -because if will avoid a Gitaly re-install each time you run `rspec`. +because it avoids a Gitaly re-install each time you run `rspec`. ```shell rm -rf tmp/tests/gitaly @@ -197,12 +197,12 @@ ln -s /path/to/gitaly tmp/tests/gitaly ``` Make sure you run `make` in your local Gitaly directory before running -tests. Otherwise, Gitaly will fail to boot. +tests. Otherwise, Gitaly fails to boot. If you make changes to your local Gitaly in between test runs you need to manually run `make` again. -Note that CI tests will not use your locally modified version of +Note that CI tests do not use your locally modified version of Gitaly. To use a custom Gitaly version in CI you need to update GITALY_SERVER_VERSION as described at the beginning of this paragraph. diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index bdbcd52eb61..07e39c66a6c 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -19,13 +19,14 @@ Instrumenting methods is done by using the `Gitlab::Metrics::Instrumentation` module. This module offers a few different methods that can be used to instrument code: -- `instrument_method`: instruments a single class method. -- `instrument_instance_method`: instruments a single instance method. -- `instrument_class_hierarchy`: given a Class this method will recursively - instrument all sub-classes (both class and instance methods). -- `instrument_methods`: instruments all public and private class methods of a Module. -- `instrument_instance_methods`: instruments all public and private instance methods of a +- `instrument_method`: Instruments a single class method. +- `instrument_instance_method`: Instruments a single instance method. +- `instrument_class_hierarchy`: Given a Class, this method recursively + instruments all sub-classes (both class and instance methods). +- `instrument_methods`: Instruments all public and private class methods of a Module. +- `instrument_instance_methods`: Instruments all public and private instance + methods of a Module. To remove the need for typing the full `Gitlab::Metrics::Instrumentation` namespace you can use the `configure` class method. This method simply yields @@ -91,7 +92,7 @@ Ruby code. In case of the above snippet you'd run the following: - `$ Banzai::Renderer.render` -This will print out something along the lines of: +This prints a result similar to: ```plaintext From: /path/to/your/gitlab/lib/gitlab/metrics/instrumentation.rb @ line 148: @@ -131,7 +132,7 @@ Three values are measured for a block: Both the real and CPU timings are measured in milliseconds. -Multiple calls to the same block will result in the final values being the sum +Multiple calls to the same block results in the final values being the sum of all individual values. Take this code for example: ```ruby @@ -142,7 +143,7 @@ of all individual values. Take this code for example: end ``` -Here the final value of `sleep_real_time` will be `3`, _not_ `1`. +Here, the final value of `sleep_real_time` is `3`, and not `1`. ## Tracking Custom Events diff --git a/doc/development/logging.md b/doc/development/logging.md index 14812978f2d..4ddb0e5f5cf 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -35,14 +35,14 @@ Completed 200 OK in 166ms (Views: 117.4ms | ActiveRecord: 27.2ms) These logs suffer from a number of problems: -1. They often lack timestamps or other contextual information (e.g. project ID, user) +1. They often lack timestamps or other contextual information (for example, project ID or user) 1. They may span multiple lines, which make them hard to find via Elasticsearch. 1. They lack a common structure, which make them hard to parse by log forwarders, such as Logstash or Fluentd. This also makes them hard to search. -Note that currently on GitLab.com, any messages in `production.log` will -NOT get indexed by Elasticsearch due to the sheer volume and noise. They +Note that currently on GitLab.com, any messages in `production.log` aren't +indexed by Elasticsearch due to the sheer volume and noise. They do end up in Google Stackdriver, but it is still harder to search for logs there. See the [GitLab.com logging documentation](https://gitlab.com/gitlab-com/runbooks/blob/master/logging/doc/README.md) @@ -73,7 +73,7 @@ importer progresses. Here's what to do: make it easy for people to search pertinent logs in one place. For example, `geo.log` contains all logs pertaining to GitLab Geo. To create a new file: - 1. Choose a filename (e.g. `importer_json.log`). + 1. Choose a filename (for example, `importer_json.log`). 1. Create a new subclass of `Gitlab::JsonLogger`: ```ruby @@ -99,7 +99,7 @@ importer progresses. Here's what to do: ``` Note that it's useful to memoize this because creating a new logger - each time you log will open a file, adding unnecessary overhead. + each time you log opens a file, adding unnecessary overhead. 1. Now insert log messages into your code. When adding logs, make sure to include all the context as key-value pairs: @@ -129,7 +129,7 @@ an Elasticsearch-specific way, the concepts should translate to many systems you might use to index structured logs. GitLab.com uses Elasticsearch to index log data. -Unless a field type is explicitly mapped, Elasticsearch will infer the type from +Unless a field type is explicitly mapped, Elasticsearch infers the type from the first instance of that field value it sees. Subsequent instances of that field value with different types will either fail to be indexed, or in some cases (scalar/object conflict), the whole log line will be dropped. @@ -138,7 +138,7 @@ GitLab.com's logging Elasticsearch sets [`ignore_malformed`](https://www.elastic.co/guide/en/elasticsearch/reference/current/ignore-malformed.html), which allows documents to be indexed even when there are simpler sorts of mapping conflict (for example, number / string), although indexing on the affected fields -will break. +breaks. Examples: @@ -177,17 +177,24 @@ challenged to choose between seconds, milliseconds or any other unit, lean towar (with microseconds precision, i.e. `Gitlab::InstrumentationHelper::DURATION_PRECISION`). In order to make it easier to track timings in the logs, make sure the log key has `_s` as -suffix and `duration` within its name (e.g., `view_duration_s`). +suffix and `duration` within its name (for example, `view_duration_s`). ## Multi-destination Logging -GitLab is transitioning from unstructured/plaintext logs to structured/JSON logs. During this transition period some logs will be recorded in multiple formats through multi-destination logging. +GitLab is transitioning from unstructured/plaintext logs to structured/JSON logs. During this transition period some logs are recorded in multiple formats through multi-destination logging. ### How to use multi-destination logging -Create a new logger class, inheriting from `MultiDestinationLogger` and add an array of loggers to a `LOGGERS` constant. The loggers should be classes that descend from `Gitlab::Logger`. e.g. the user defined loggers in the following examples, could be inheriting from `Gitlab::Logger` and `Gitlab::JsonLogger`, respectively. +Create a new logger class, inheriting from `MultiDestinationLogger` and add an +array of loggers to a `LOGGERS` constant. The loggers should be classes that +descend from `Gitlab::Logger`. For example, the user-defined loggers in the +following examples could be inheriting from `Gitlab::Logger` and +`Gitlab::JsonLogger`, respectively. -You must specify one of the loggers as the `primary_logger`. The `primary_logger` will be used when information about this multi-destination logger is displayed in the app, e.g. using the `Gitlab::Logger.read_latest` method. +You must specify one of the loggers as the `primary_logger`. The +`primary_logger` is used when information about this multi-destination logger is +displayed in the application (for example, using the `Gitlab::Logger.read_latest` +method). The following example sets one of the defined `LOGGERS` as a `primary_logger`. @@ -207,19 +214,19 @@ module Gitlab end ``` -You can now call the usual logging methods on this multi-logger, e.g. +You can now call the usual logging methods on this multi-logger. For example: ```ruby FancyMultiLogger.info(message: "Information") ``` -This message will be logged by each logger registered in `FancyMultiLogger.loggers`. +This message is logged by each logger registered in `FancyMultiLogger.loggers`. ### Passing a string or hash for logging When passing a string or hash to a `MultiDestinationLogger`, the log lines could be formatted differently, depending on the kinds of `LOGGERS` set. -e.g. let's partially define the loggers from the previous example: +For example, let's partially define the loggers from the previous example: ```ruby module Gitlab @@ -356,7 +363,7 @@ end ## Additional steps with new log files -1. Consider log retention settings. By default, Omnibus will rotate any +1. Consider log retention settings. By default, Omnibus rotates any logs in `/var/log/gitlab/gitlab-rails/*.log` every hour and [keep at most 30 compressed files](https://docs.gitlab.com/omnibus/settings/logs.html#logrotate). On GitLab.com, that setting is only 6 compressed files. These settings should suffice diff --git a/doc/development/prometheus_metrics.md b/doc/development/prometheus_metrics.md index 8fcc025b35b..f51c39e6b45 100644 --- a/doc/development/prometheus_metrics.md +++ b/doc/development/prometheus_metrics.md @@ -31,7 +31,7 @@ The requirement for adding a new metric is to make each query to have an unique ### Update existing metrics -After you add or change an existing common metric, you must [re-run the import script](../administration/raketasks/maintenance.md#import-common-metrics) that will query and update all existing metrics. +After you add or change an existing common metric, you must [re-run the import script](../administration/raketasks/maintenance.md#import-common-metrics) that queries and updates all existing metrics. Or, you can create a database migration: @@ -51,7 +51,7 @@ class ImportCommonMetrics < ActiveRecord::Migration[4.2] end ``` -If a query metric (which is identified by `id:`) is removed it will not be removed from database by default. +If a query metric (which is identified by `id:`) is removed, it isn't removed from database by default. You might want to add additional database migration that makes a decision what to do with removed one. For example: you might be interested in migrating all dependent data to a different metric. @@ -75,5 +75,5 @@ This section describes how to add new metrics for self-monitoring 1. Select the appropriate name for your metric. Refer to the guidelines for [Prometheus metric names](https://prometheus.io/docs/practices/naming/#metric-names). 1. Update the list of [GitLab Prometheus metrics](../administration/monitoring/prometheus/gitlab_metrics.md). -1. Trigger the relevant page/code that will record the new metric. +1. Trigger the relevant page or code that records the new metric. 1. Check that the new metric appears at `/-/metrics`. diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index fad2c0e39be..569ced5bde3 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -20,7 +20,7 @@ You can sign up to the cloud hosted [Sentry](https://sentry.io), deploy your own ### Enabling Sentry -GitLab provides an easy way to connect Sentry to your project. You will need at +GitLab provides an easy way to connect Sentry to your project. You need at least Maintainer [permissions](../user/permissions.md) to enable the Sentry integration. 1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. @@ -31,7 +31,7 @@ least Maintainer [permissions](../user/permissions.md) to enable the Sentry inte click **Enable Error Tracking**. 1. Navigate to your project’s **Settings > Operations**. In the **Error Tracking** section, ensure the **Active** checkbox is set. -1. In the **Sentry API URL** field, enter your Sentry hostname. For example, enter `https://sentry.example.com` if this is the address at which your Sentry instance is available. For the SaaS version of Sentry, the hostname will be `https://sentry.io`. +1. In the **Sentry API URL** field, enter your Sentry hostname. For example, enter `https://sentry.example.com` if this is the address at which your Sentry instance is available. For the SaaS version of Sentry, the hostname is `https://sentry.io`. 1. In the **Auth Token** field, enter the token you previously generated. 1. Click the **Connect** button to test the connection to Sentry and populate the **Project** dropdown. 1. From the **Project** dropdown, choose a Sentry project to link to your GitLab project. @@ -65,7 +65,7 @@ By default, a **Create issue** button is displayed:  -If you create a GitLab issue from the error, the **Create issue** button will change to a **View issue** button and a link to the GitLab issue will surface within the error detail section: +If you create a GitLab issue from the error, the **Create issue** button changes to a **View issue** button and a link to the GitLab issue displays within the error detail section:  @@ -79,7 +79,7 @@ You can take action on Sentry Errors from within the GitLab UI. From within the [Error Details](#error-details) page you can ignore a Sentry error by simply clicking the **Ignore** button near the top of the page. -Ignoring an error will prevent it from appearing in the [Error Tracking List](#error-tracking-list), and will silence notifications that were set up within Sentry. +Ignoring an error prevents it from appearing in the [Error Tracking List](#error-tracking-list), and silences notifications that were set up within Sentry. ### Resolving errors @@ -88,6 +88,6 @@ Ignoring an error will prevent it from appearing in the [Error Tracking List](#e From within the [Error Details](#error-details) page you can resolve a Sentry error by clicking the **Resolve** button near the top of the page. -Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue will be closed. +Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue closes. If another event occurs, the error reverts to unresolved. diff --git a/doc/operations/incident_management/alert_integrations.md b/doc/operations/incident_management/alert_integrations.md index 7850841d380..650c4fea645 100644 --- a/doc/operations/incident_management/alert_integrations.md +++ b/doc/operations/incident_management/alert_integrations.md @@ -60,7 +60,7 @@ and you can [customize the payload](#customize-the-alert-payload-outside-of-gitl 1. In the **Integration** dropdown menu, select **HTTP Endpoint**. 1. Name the integration. 1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** - for the webhook configuration. You will input the URL and Authorization Key + for the webhook configuration. You must also input the URL and Authorization Key in your external service. 1. _(Optional)_ To generate a test alert to test the new integration, enter a sample payload, then click **Save and test alert payload**.Valid JSON is required. diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index 37836f4ab50..883ae204373 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Alerts -Alerts are a critical entity in your incident managment workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened. +Alerts are a critical entity in your incident management workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened. ## Alert List @@ -84,7 +84,7 @@ The **Alert details** tab has two sections. The top section provides a short lis > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2. -The **Metrics** tab will display a metrics chart for alerts coming from Prometheus. If the alert originated from any other tool, the **Metrics** tab will be empty. To set up alerts for GitLab-managed Prometheus instances, see [Managed Prometheus instances](../metrics/alerts.md#managed-prometheus-instances). For externally-managed Prometheus instances, you will need to configure your alerting +The **Metrics** tab displays a metrics chart for alerts coming from Prometheus. If the alert originated from any other tool, the **Metrics** tab is empty. To set up alerts for GitLab-managed Prometheus instances, see [Managed Prometheus instances](../metrics/alerts.md#managed-prometheus-instances). For externally-managed Prometheus instances, you must configure your alerting rules to display a chart in the alert. For information about how to configure your alerting rules, see [Embedding metrics based on alerts in incident issues](../metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues). See [External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) @@ -127,7 +127,7 @@ To view the logs for an alert: The **Activity feed** tab is a log of activity on the alert. When you take action on an alert, this is logged as a system note. This gives you a linear timeline of the alert's investigation and assignment history. -The following actions will result in a system note: +The following actions result in a system note: - [Updating the status of an alert](#update-an-alerts-status) - [Creating an incident based on an alert](#create-an-incident-from-an-alert) @@ -137,7 +137,7 @@ The following actions will result in a system note: ## Alert actions -There are different actions avilable in GitLab to help triage and respond to alerts. +There are different actions available in GitLab to help triage and respond to alerts. ### Update an alert's status diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index 4230091866e..1436e18ccc4 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -128,11 +128,11 @@ To publish an incident: issue to the GitLab Status Page. Confidential issues can't be published. A background worker publishes the issue onto the Status Page using the credentials -you provided during setup. As part of publication, GitLab will: +you provided during setup. As part of publication, GitLab: -- Anonymize user and group mentions with `Incident Responder`. -- Remove titles of non-public [GitLab references](../../user/markdown.md#special-gitlab-references). -- Publish any files attached to incident issue descriptions, up to 5000 per issue. +- Anonymizes user and group mentions with `Incident Responder`. +- Removes titles of non-public [GitLab references](../../user/markdown.md#special-gitlab-references). +- Publishes any files attached to incident issue descriptions, up to 5000 per issue. ([Introduced in GitLab 13.1](https://gitlab.com/gitlab-org/gitlab/-/issues/205166).) After publication, you can access the incident's details page by clicking the diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 79e3bdbd69c..2fa844e362a 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -53,8 +53,8 @@ as soon as the alert fires: For manually configured Prometheus servers, GitLab provides a notify endpoint for use with Prometheus webhooks. If you have manual configuration enabled, an **Alerts** section is added to **Settings > Integrations > Prometheus**. -This section contains the **URL** and **Authorization Key** you will need. The -**Reset Key** button will invalidate the key and generate a new one. +This section contains the needed **URL** and **Authorization Key**. The +**Reset Key** button invalidates the key and generates a new one.  @@ -85,7 +85,7 @@ Prometheus server to use the ## Trigger actions from alerts **(ULTIMATE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. -> - [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. +> - [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it automatically closes the associated issue. Alerts can be used to trigger actions, like opening an issue automatically (disabled by default since `13.1`). To configure the actions: diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index c11da2926bb..7717f589b09 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -66,8 +66,8 @@ To create a new dashboard from the command line: Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`. NOTE: **Note:** -Configuration files nested under subdirectories of `.gitlab/dashboards` are not -supported and won't be available in the UI. +Configuration files nested under subdirectories of `.gitlab/dashboards` aren't +supported or available in the UI. ## Add a new metrics panel to a dashboard @@ -156,7 +156,7 @@ and end times to the URL, enabling you to share specific timeframes more easily. You can use **Metrics Dashboard Annotations** to mark any important events on every metrics dashboard by adding annotations to it. While viewing a dashboard, -annotation entries assigned to the selected time range will be automatically +annotation entries assigned to the selected time range are automatically fetched and displayed on every chart within that dashboard. On mouse hover, each annotation presents additional details, including the exact time of an event and its description. diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md index fd9d2bf7899..589e10cf4c6 100644 --- a/doc/operations/metrics/dashboards/panel_types.md +++ b/doc/operations/metrics/dashboards/panel_types.md @@ -39,7 +39,7 @@ Note the following properties:  -Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/202696), the y-axis values will automatically scale according to the data. Previously, it always started from 0. +Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/202696), the y-axis values scale according to the data. Previously, it always started from 0. ## Anomaly chart diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md index 1c0b05b0e53..6cd9fd26917 100644 --- a/doc/operations/metrics/dashboards/templating_variables.md +++ b/doc/operations/metrics/dashboards/templating_variables.md @@ -25,8 +25,8 @@ CAUTION: **Warning:** This variable type is an _alpha_ feature, and is subject to change at any time without prior notice! -For each `text` variable defined in the dashboard YAML, there will be a free text -box on the dashboard UI, allowing you to enter a value for each variable. +For each `text` variable defined in the dashboard YAML, a free text field displays +on the dashboard UI, allowing you to enter a value for each variable. The `text` variable type supports a simple and a full syntax. @@ -44,7 +44,7 @@ templating: ### Full syntax This example creates a variable called `variable1`, with a default value of `default`. -The label for the text box on the UI will be the value of the `label` key: +The label for the text box on the UI is the value of the `label` key: ```yaml templating: @@ -70,7 +70,7 @@ The `custom` variable type supports a simple and a full syntax. ### Simple syntax This example creates a variable called `variable1`, with a default value of `value1`. -The dashboard UI will display a dropdown with `value1`, `value2` and `value3` +The dashboard UI displays a dropdown with `value1`, `value2` and `value3` as the choices. ```yaml @@ -82,12 +82,12 @@ templating: ### Full syntax This example creates a variable called `variable1`, with a default value of `value_option_2`. -The label for the text box on the UI will be the value of the `label` key. -The dashboard UI will display a dropdown with `Option 1` and `Option 2` +The label for the text box on the UI is the value of the `label` key. +The dashboard UI displays a dropdown with `Option 1` and `Option 2` as the choices. -If you select `Option 1` from the dropdown, the variable will be replaced with `value option 1`. -Similarly, if you select `Option 2`, the variable will be replaced with `value_option_2`: +If you select `Option 1` from the dropdown, the variable is replaced with `value option 1`. +Similarly, if you select `Option 2`, the variable is replaced with `value_option_2`: ```yaml templating: @@ -112,8 +112,8 @@ without prior notice! ### Full syntax -This example creates a variable called `variable2`. The values of the dropdown will -be all the different values of the `backend` label in the Prometheus series described by +This example creates a variable called `variable2`. The values of the dropdown are +all the different values of the `backend` label in the Prometheus series described by `up{env="production"}`. ```yaml diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index e1f5f0ce6f4..1227c937671 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -12,7 +12,7 @@ Variables can be specified using double curly braces, such as `"{{ci_environment Support for the `"%{ci_environment_slug}"` format was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31581) in GitLab 13.0. -Queries that continue to use the old format will show no data. +Queries that continue to use the old format display no data. ## Predefined variables diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index 13397eb702a..4932afc5047 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -53,7 +53,7 @@ is no longer used. | `group` | string | required | Heading for the panel group. | | `panels` | array | required | The panels which should be in the panel group. | -Panels in a panel group are laid out in rows consisting of two panels per row. An exception to this rule are single panels on a row: these panels will take the full width of their containing row. +Panels in a panel group are laid out in rows consisting of two panels per row. An exception to this rule are single panels on a row: these panels take the full width of their containing row. ## **Panel (`panels`) properties** @@ -87,15 +87,15 @@ is no longer used. | `id` | string | no | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](../alerts.md) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/27980)). | | `unit` | string | yes | Defines the unit of the query's return data. | | `label` | string | no, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. Can contain time series labels as interpolated variables. | -| `query` | string/number | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be used. | -| `query_range` | string/number | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be used. | +| `query` | string/number | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) is used. | +| `query_range` | string/number | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) is used. | | `step` | number | no, value is calculated if not defined | Defines query resolution step width in float number of seconds. Metrics on the same panel should use the same `step` value. | ## Dynamic labels Dynamic labels are useful when multiple time series are returned from a Prometheus query. -When a static label is used and a query returns multiple time series, then all the legend items will be labeled the same, which makes identifying each time series difficult: +When a static label is used and a query returns multiple time series, then all the legend items are labeled the same, which makes identifying each time series difficult: ```yaml metrics: @@ -109,7 +109,7 @@ This may render a legend like this:  -For labels to be more explicit, using variables that reflect time series labels is a good practice. The variables will be replaced by the values of the time series labels when the legend is rendered: +For labels to be more explicit, using variables that reflect time series labels is a good practice. The variables are replaced by the values of the time series labels when the legend is rendered: ```yaml metrics: @@ -119,7 +119,7 @@ metrics: unit: 'count' ``` -The resulting rendered legend will look like this: +The resulting rendered legend looks like this:  @@ -133,7 +133,7 @@ metrics: unit: 'count' ``` -This works by lowercasing the value of `label` and, if there are more words separated by spaces, replacing those spaces with an underscore (`_`). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value will be used and rendered in the legend like this: +This works by lowercasing the value of `label` and, if there are more words separated by spaces, replacing those spaces with an underscore (`_`). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value renders in the legend like this:  diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 6ce0bd42d3c..54187e10142 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -147,7 +147,7 @@ After saving them, they display on the environment metrics dashboard provided th A few fields are required: - **Name**: Chart title -- **Type**: Type of metric. Metrics of the same type will be shown together. +- **Type**: Type of metric. Metrics of the same type are shown together. - **Query**: Valid [PromQL query](https://prometheus.io/docs/prometheus/latest/querying/basics/). - **Y-axis label**: Y axis title to display on the dashboard. - **Unit label**: Query units, for example `req / sec`. Shown next to the value. diff --git a/doc/operations/tracing.md b/doc/operations/tracing.md index b6ef552772e..94e9fdf5dff 100644 --- a/doc/operations/tracing.md +++ b/doc/operations/tracing.md @@ -38,4 +38,4 @@ GitLab provides an easy way to open the Jaeger UI from within your project: 1. Navigate to your project's **Settings > Operations** and provide the Jaeger URL. 1. Click **Save changes** for the changes to take effect. 1. You can now visit **Operations > Tracing** in your project's sidebar and - GitLab will redirect you to the configured Jaeger URL. + GitLab redirects you to the configured Jaeger URL. diff --git a/doc/raketasks/generate_sample_prometheus_data.md b/doc/raketasks/generate_sample_prometheus_data.md index f37aa95c63b..f84fe4249ae 100644 --- a/doc/raketasks/generate_sample_prometheus_data.md +++ b/doc/raketasks/generate_sample_prometheus_data.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Generate sample Prometheus data **(CORE ONLY)** -This command will run Prometheus queries for each of the metrics of a specific environment +This command runs Prometheus queries for each of the metrics of a specific environment for a series of time intervals to now: - 30 minutes diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 9273fb7b361..249abe9140c 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -79,8 +79,8 @@ project. That way you can have different clusters for different environments, like dev, staging, production, and so on. Simply add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope) that will -differentiate the new cluster with the rest. +[set an environment scope](#setting-the-environment-scope) that +differentiates the new cluster from the rest. #### Setting the environment scope @@ -89,9 +89,9 @@ them with an environment scope. The environment scope associates clusters with [ [environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. The default environment scope is `*`, which means all jobs, regardless of their -environment, will use that cluster. Each scope can only be used by a single -cluster in a project, and a validation error will occur if otherwise. -Also, jobs that don't have an environment keyword set will not be able to access any cluster. +environment, use that cluster. Each scope can be used only by a single cluster +in a project, and a validation error occurs if otherwise. Also, jobs that don't +have an environment keyword set can't access any cluster. For example, let's say the following Kubernetes clusters exist in a project: @@ -127,13 +127,13 @@ deploy to production: url: https://example.com/ ``` -The result will then be: +The results: -- The Development cluster details will be available in the `deploy to staging` +- The Development cluster details are available in the `deploy to staging` job. -- The production cluster details will be available in the `deploy to production` +- The production cluster details are available in the `deploy to production` job. -- No cluster details will be available in the `test` job because it doesn't +- No cluster details are available in the `test` job because it doesn't define any environment. ## Configuring your Kubernetes cluster @@ -157,15 +157,15 @@ applications running on the cluster. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 11.5. > - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/26565) in GitLab 11.11. -You can choose to allow GitLab to manage your cluster for you. If your cluster is -managed by GitLab, resources for your projects will be automatically created. See the -[Access controls](add_remove_clusters.md#access-controls) section for details on which resources will -be created. +You can choose to allow GitLab to manage your cluster for you. If your cluster +is managed by GitLab, resources for your projects are automatically created. See +the [Access controls](add_remove_clusters.md#access-controls) section for +details about the created resources. -If you choose to manage your own cluster, project-specific resources will not be created -automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will -need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) -that will be used by your deployment jobs, otherwise a namespace will be created for you. +If you choose to manage your own cluster, project-specific resources aren't created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you must +explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) +for your deployment jobs to use; otherwise a namespace is created for you. #### Important notes @@ -198,10 +198,10 @@ To clear the cache: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24580) in GitLab 11.8. You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case -will be specified as part of the Knative installation. See [Installing Applications](#installing-applications). +is specified as part of the Knative installation. See [Installing Applications](#installing-applications). -Specifying a base domain will automatically set `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. -If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain will be used for the different +Specifying a base domain automatically sets `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. +If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain is used for the different stages. For example, Auto Review Apps and Auto Deploy. The domain should have a wildcard DNS configured to the Ingress IP address. After Ingress has been installed (see [Installing Applications](#installing-applications)), @@ -224,7 +224,7 @@ Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. To make full use of Auto DevOps (Auto Deploy, Auto Review Apps, and -Auto Monitoring) you will need the Kubernetes project integration enabled, but +Auto Monitoring) the Kubernetes project integration must be enabled, but Kubernetes clusters can be used without Auto DevOps. [Read more about Auto DevOps](../../../topics/autodevops/index.md) @@ -238,7 +238,7 @@ A Kubernetes cluster can be the destination for a deployment job. If and configuration is not required. You can immediately begin interacting with the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use GitLab's cluster integration you can still deploy to your - cluster. However, you will need configure Kubernetes tools yourself + cluster. However, you must configure Kubernetes tools yourself using [environment variables](../../../ci/variables/README.md#custom-environment-variables) before you can interact with the cluster from your jobs. @@ -257,14 +257,14 @@ The Kubernetes cluster integration exposes the following GitLab CI/CD build environment to deployment jobs, which are jobs that have [defined a target environment](../../../ci/environments/index.md#defining-environments). -| Variable | Description | -| -------- | ----------- | -| `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | -| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | -| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | -| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | -| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | +| Variable | Description | +|----------------------------|-------------| +| `KUBE_URL` | Equal to the API URL. | +| `KUBE_TOKEN` | The Kubernetes token of the [environment service account](add_remove_clusters.md#access-controls). Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. | +| `KUBE_NAMESPACE` | The namespace associated with the project's deployment service account. In the format `<project_name>-<project_id>-<environment>`. For GitLab-managed clusters, a matching namespace is automatically created by GitLab in the cluster. If your cluster was created before GitLab 12.2, the default `KUBE_NAMESPACE` is set to `<project_name>-<project_id>`. | +| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | +| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | +| `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This configuration also embeds the same token defined in `KUBE_TOKEN` so you likely need only this variable. This variable name is also automatically picked up by `kubectl` so you don't need to reference it explicitly if using `kubectl`. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | ### Custom namespace @@ -362,7 +362,7 @@ the deployment job: - A namespace. - A service account. -However, sometimes GitLab can not create them. In such instances, your job will fail with the message: +However, sometimes GitLab can not create them. In such instances, your job can fail with the message: ```plaintext This job failed because the necessary resources were not successfully created. @@ -376,7 +376,7 @@ Reasons for failure include: privileges required by GitLab. - Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching [`environment:name`](../../../ci/environments/index.md#defining-environments). If your job has no - `environment:name` set, it will not be passed the Kubernetes credentials. + `environment:name` set, the Kubernetes credentials are not passed to it. NOTE: **Note:** Project-level clusters upgraded from GitLab 12.0 or older may be configured @@ -396,6 +396,6 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Core in 13.2. -When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. +When [Prometheus is deployed](#installing-applications), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start.  diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 97be16f8dd3..9793717fdf3 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -19,7 +19,7 @@ There are two ways to set up Prometheus integration, depending on where your app - For deployments on Kubernetes, GitLab can automatically [deploy and manage Prometheus](#managed-prometheus-on-kubernetes). - For other deployment targets, simply [specify the Prometheus server](#manual-configuration-of-prometheus). -Once enabled, GitLab will automatically detect metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create +Once enabled, GitLab detects metrics from known services in the [metric library](prometheus_library/index.md). You can also [add your own metrics](../../../operations/metrics/index.md#adding-custom-metrics) and create [custom dashboards](../../../operations/metrics/dashboards/index.md). ## Enabling Prometheus Integration @@ -48,7 +48,7 @@ Once you have a connected Kubernetes cluster, deploying a managed Prometheus is Prometheus is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/prometheus). Prometheus is only accessible within the cluster, with GitLab communicating through the [Kubernetes API](https://kubernetes.io/docs/concepts/overview/kubernetes-api/). -The Prometheus server will [automatically detect and monitor](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): +The Prometheus server [automatically detects and monitors](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#kubernetes_sd_config) nodes, pods, and endpoints. To configure a resource to be monitored by Prometheus, simply set the following [Kubernetes annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/): - `prometheus.io/scrape` to `true` to enable monitoring of the resource. - `prometheus.io/port` to define the port of the metrics endpoint. @@ -165,8 +165,8 @@ Installing and configuring Prometheus to monitor applications is fairly straight #### Configuration in GitLab -The actual configuration of Prometheus integration within GitLab is very simple. -All you will need is the domain name or IP address of the Prometheus server you'd like +The actual configuration of Prometheus integration within GitLab +requires the domain name or IP address of the Prometheus server you'd like to integrate with. If the Prometheus resource is secured with Google's Identity-Aware Proxy (IAP), additional information like Client ID and Service Account credentials can be passed which GitLab can use to access the resource. More information about authentication from a @@ -189,7 +189,7 @@ service account can be found at Google's documentation for #### Thanos configuration in GitLab You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prometheus -with GitLab. You will need the domain name or IP address of the Thanos server you'd like +with GitLab, using the domain name or IP address of the Thanos server you'd like to integrate with. 1. Navigate to the [Integrations page](overview.md#accessing-integrations). @@ -199,9 +199,10 @@ to integrate with. ### Precedence with multiple Prometheus configurations +12345678901234567890123456789012345678901234567890123456789012345678901234567890 Although you can enable both a [manual configuration](#manual-configuration-of-prometheus) -and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, only -one of them will be used: +and [auto configuration](#managed-prometheus-on-kubernetes) of Prometheus, you +can use only one: - If you have enabled a [Prometheus manual configuration](#manual-configuration-of-prometheus) @@ -225,16 +226,16 @@ Developers can view the performance impact of their changes within the merge request workflow. This feature requires [Kubernetes](prometheus_library/kubernetes.md) metrics. When a source branch has been deployed to an environment, a sparkline and -numeric comparison of the average memory consumption will appear. On the +numeric comparison of the average memory consumption displays. On the sparkline, a dot indicates when the current changes were deployed, with up to 30 minutes of performance data displayed before and after. The comparison shows the difference between the 30 minute average before and after the deployment. This information is updated after each commit has been deployed. -Once merged and the target branch has been redeployed, the metrics will switch +Once merged and the target branch has been redeployed, the metrics switches to show the new environments this revision has been deployed to. -Performance data will be available for the duration it is persisted on the +Performance data is available for the duration it is persisted on the Prometheus server.  diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 70f8a55bb07..c28a1314c75 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -33,4 +33,4 @@ A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB mo ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 0fbc49ddad7..fc1463ea92b 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -28,4 +28,4 @@ To get started with NGINX monitoring, you should install and configure the [HAPr ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 35b111ab2b2..5f9376e19ab 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -21,8 +21,8 @@ Currently supported exporters are: - [HAProxy](haproxy.md) - [Amazon Cloud Watch](cloudwatch.md) -We have tried to surface the most important metrics for each exporter, and will -be continuing to add support for additional exporters in future releases. If you +We have tried to surface the most important metrics for each exporter, and +continue to add support for additional exporters in future releases. If you would like to add support for other official exporters, contributions are welcome. ## Identifying Environments diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 1757378fb70..de1208ae9ce 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -29,11 +29,11 @@ NGINX server metrics are detected, which tracks the pages and content directly s ## Configuring Prometheus to monitor for NGINX metrics -To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This will capture and display statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. +To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This captures and displays statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. -If you are using NGINX as your Kubernetes Ingress, GitLab will [automatically detect](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. +If you are using NGINX as your Kubernetes Ingress, GitLab [automatically detects](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab [looks for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index fdea800c410..1e510296f7d 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -27,7 +27,7 @@ NGINX Ingress versions prior to 0.16.0 offer an included [VTS Prometheus metrics ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors it](#about-managed-nginx-ingress-deployments). For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) have built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint starts running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `ingress` label must `<CI_ENVIRONMENT_SLUG>`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index ec7b1ee6d10..80f29d31341 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -27,7 +27,7 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI ## Configuring NGINX Ingress monitoring -If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), it will [automatically be monitored](#about-managed-nginx-ingress-deployments) by Prometheus. +If you have deployed NGINX Ingress using GitLab's [Kubernetes cluster integration](../../clusters/index.md#installing-applications), Prometheus [automatically monitors](#about-managed-nginx-ingress-deployments) it. For other deployments, there is [some configuration](#manually-setting-up-nginx-ingress-for-prometheus-monitoring) required depending on your installation: @@ -37,7 +37,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress is [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: @@ -45,11 +45,11 @@ NGINX is configured for Prometheus monitoring, by setting: - `prometheus.io/scrape: "true"`, to enable automatic discovery. - `prometheus.io/port: "10254"`, to specify the metrics port. -When used in conjunction with the GitLab deployed Prometheus service, response metrics will be automatically collected. +When used in conjunction with the GitLab deployed Prometheus service, response metrics are automatically collected. ### Manually setting up NGINX Ingress for Prometheus monitoring -Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint will start running on port 10254. +Version 0.9.0 and above of [NGINX Ingress](https://github.com/kubernetes/ingress-nginx) has built-in support for exporting Prometheus metrics. To enable, a ConfigMap setting must be passed: `enable-vts-status: "true"`. Once enabled, a Prometheus metrics endpoint begins running on port 10254. Next, the Ingress needs to be annotated for Prometheus monitoring. Two new annotations need to be added: @@ -60,6 +60,6 @@ Managing these settings depends on how NGINX Ingress has been deployed. If you h ## Specifying the Environment label -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab will search for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. +In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do this, GitLab searches for metrics with appropriate labels. In this case, the `upstream` label must be of the form `<KUBE_NAMESPACE>-<CI_ENVIRONMENT_SLUG>-*`. -If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. +If you have used [Auto Deploy](../../../../topics/autodevops/stages.md#auto-deploy) to deploy your app, this format is used automatically and metrics are detected with no action on your part. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 040ca4b439b..ec22cd06051 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -47,8 +47,8 @@ For an example Performance job, see NOTE: **Note:** If the Browser Performance report has no data to compare, such as when you add the Browser Performance job in your `.gitlab-ci.yml` for the very first time, -the Browser Performance report widget won't show. It must have run at least -once on the target branch (`master`, for example), before it will display in a +the Browser Performance report widget doesn't show. It must have run at least +once on the target branch (`master`, for example), before it displays in a merge request targeting that branch.  @@ -81,7 +81,7 @@ The above example creates a `performance` job in your CI/CD pipeline and runs sitespeed.io against the webpage you defined in `URL` to gather key metrics. The example uses a CI/CD template that is included in all GitLab installations since -12.4, but it will not work with Kubernetes clusters. If you are using GitLab 12.3 +12.4, but it doesn't work with Kubernetes clusters. If you are using GitLab 12.3 or older, you must [add the configuration manually](#gitlab-versions-123-and-older) The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), @@ -115,7 +115,7 @@ performance: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27599) in GitLab 13.0. You can configure the sensitivity of degradation alerts to avoid getting alerts for minor drops in metrics. -This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert will only show up +This is done by setting the `DEGRADATION_THRESHOLD` variable. In the example below, the alert only shows up if the `Total Score` metric degrades by 5 points or more: ```yaml @@ -181,7 +181,7 @@ performance: ### GitLab versions 12.3 and older Browser Performance Testing has gone through several changes since it's introduction. -In this section we'll detail these changes and how you can run the test based on your +In this section we detail these changes and how you can run the test based on your GitLab version: - In GitLab 12.4 [a job template was made available](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Browser-Performance.gitlab-ci.yml). diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index d50056c9450..cc772f65668 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -84,8 +84,8 @@ include: - template: Code-Quality.gitlab-ci.yml ``` -The above example will create a `code_quality` job in your CI/CD pipeline which -will scan your source code for code quality issues. The report will be saved as a +The above example creates a `code_quality` job in your CI/CD pipeline which +scans your source code for code quality issues. The report is saved as a [Code Quality report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality) that you can later download and analyze. @@ -132,17 +132,17 @@ stages: ``` TIP: **Tip:** -This information will be automatically extracted and shown right in the merge request widget. +This information is automatically extracted and shown right in the merge request widget. CAUTION: **Caution:** On self-managed instances, if a malicious actor compromises the Code Quality job -definition they will be able to execute privileged Docker commands on the runner +definition they could execute privileged Docker commands on the runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. ### Disabling the code quality job -The `code_quality` job will not run if the `$CODE_QUALITY_DISABLED` environment +The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` environment variable is present. Please refer to the environment variables [documentation](../../../ci/variables/README.md) to learn more about how to define one. @@ -185,7 +185,7 @@ job1: - if: '$CI_COMMIT_TAG' # Run job1 in pipelines for tags ``` -To make these work together, you will need to overwrite the code quality `rules` +To make these work together, you need to overwrite the code quality `rules` so that they match your current `rules`. From the example above, it could look like: ```yaml @@ -260,7 +260,7 @@ Once the Code Quality job has completed: Code Quality tab of the Pipeline Details page. - Potential changes to code quality are shown directly in the merge request. The Code Quality widget in the merge request compares the reports from the base and head of the branch, - then lists any violations that will be resolved or created when the branch is merged. + then lists any violations that are resolved or created when the branch is merged. - The full JSON report is available as a [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) for the `code_quality` job. @@ -341,11 +341,11 @@ is still used. This can be due to multiple reasons: - You just added the Code Quality job in your `.gitlab-ci.yml`. The report does not - have anything to compare to yet, so no information can be displayed. Future merge - requests will have something to compare to. + have anything to compare to yet, so no information can be displayed. It only displays + after future merge requests have something to compare to. - Your pipeline is not set to run the code quality job on your default branch. If there is no report generated from the default branch, your MR branch reports will not have anything to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), - nothing will be displayed. + nothing is displayed. - The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. - Large `codeclimate.json` files (esp. >10 MB) are [known to prevent the report from being displayed](https://gitlab.com/gitlab-org/gitlab/-/issues/2737). diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 9f4dfe54c47..a25e2786193 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -87,7 +87,7 @@ download all the advertised refs. git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must remove branch protection, push, and then re-enable protected branches. 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: @@ -96,7 +96,7 @@ download all the advertised refs. git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. 1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. @@ -131,7 +131,7 @@ To purge files from GitLab storage: tar xzf project-backup.tar.gz ``` - This will contain a `project.bundle` file, which was created by + This contains a `project.bundle` file, which was created by [`git bundle`](https://git-scm.com/docs/git-bundle). 1. Clone a fresh copy of the repository from the bundle: @@ -141,12 +141,12 @@ To purge files from GitLab storage: ``` 1. Using `git filter-repo`, purge any files from the history of your repository. Because we are - trying to remove internal refs, we will rely on the `commit-map` produced by each run to tell us + trying to remove internal refs, we rely on the `commit-map` produced by each run to tell us which internal refs to remove. NOTE: **Note:** `git filter-repo` creates a new `commit-map` file every run, and overwrite the `commit-map` from - the previous run. You will need this file from **every** run. Do the next step every time you run + the previous run. You need this file from **every** run. Do the next step every time you run `git filter-repo`. To purge all large files, the `--strip-blobs-bigger-than` option can be used: @@ -178,7 +178,7 @@ To purge files from GitLab storage: git push origin --force 'refs/heads/*' ``` - [Protected branches](../protected_branches.md) will cause this to fail. To proceed, you must + [Protected branches](../protected_branches.md) cause this to fail. To proceed, you must remove branch protection, push, and then re-enable protected branches. 1. To remove large files from tagged releases, force push your changes to all tags on GitLab: @@ -187,7 +187,7 @@ To purge files from GitLab storage: git push origin --force 'refs/tags/*' ``` - [Protected tags](../protected_tags.md) will cause this to fail. To proceed, you must remove tag + [Protected tags](../protected_tags.md) cause this to fail. To proceed, you must remove tag protection, push, and then re-enable protected tags. 1. To prevent dead links to commits that no longer exist, push the `refs/replace` created by `git filter-repo`. @@ -205,12 +205,12 @@ To purge files from GitLab storage: NOTE: **Note:** Safely cleaning the repository requires it to be made read-only for the duration of the operation. This happens automatically, but submitting the cleanup request -will fail if any writes are ongoing, so cancel any outstanding `git push` +fails if any writes are ongoing, so cancel any outstanding `git push` operations before continuing. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19376) in GitLab 11.6. -Repository cleanup allows you to upload a text file of objects and GitLab will remove internal Git +Repository cleanup allows you to upload a text file of objects and GitLab removes internal Git references to these objects. You can use [`git filter-repo`](https://github.com/newren/git-filter-repo) to produce a list of objects (in a `commit-map` file) that can be used with repository cleanup. @@ -230,25 +230,25 @@ To clean up a repository: 1. Click **Start cleanup**. -This will: +This: -- Remove any internal Git references to old commits. -- Run `git gc` against the repository to remove unreferenced objects. Repacking your repository will temporarily - cause the size of your repository to increase significantly, because the old pack files are not removed until the +- Removes any internal Git references to old commits. +- Runs `git gc` against the repository to remove unreferenced objects. Repacking your repository temporarily + causes the size of your repository to increase significantly, because the old pack files are not removed until the new pack files have been created. -- Unlink any unused LFS objects currently attached to your project, freeing up storage space. -- Recalculate the size of your repository on disk. +- Unlinks any unused LFS objects currently attached to your project, freeing up storage space. +- Recalculates the size of your repository on disk. -You will receive an email notification with the recalculated repository size after the cleanup has completed. +GitLab sends an email notification with the recalculated repository size after the cleanup has completed. When using repository cleanup, note: - Project statistics are cached. You may need to wait 5-10 minutes to see a reduction in storage utilization. - Housekeeping prunes loose objects older than 2 weeks. This means objects added in the last 2 weeks - will not be removed immediately. If you have access to the + are not be removed immediately. If you have access to the [Gitaly](../../../administration/gitaly/index.md) server, you may run `git gc --prune=now` to prune all loose objects immediately. -- This process will remove some copies of the rewritten commits from GitLab's cache and database, +- This process removes some copies of the rewritten commits from GitLab's cache and database, but there are still numerous gaps in coverage and some of the copies may persist indefinitely. [Clearing the instance cache](../../../administration/raketasks/maintenance.md#clear-redis-cache) may help to remove some of them, but it should not be depended on for security purposes! @@ -290,7 +290,7 @@ history. We recommend the open-source community-maintained tool [`git filter-repo`](https://github.com/newren/git-filter-repo). NOTE: **Note:** -Until `git gc` runs on the GitLab side, the "removed" commits and blobs will still exist. You also +Until `git gc` runs on the GitLab side, the "removed" commits and blobs still exist. You also must be able to push the rewritten history to GitLab, which may be impossible if you've already exceeded the maximum size limit. @@ -304,7 +304,7 @@ increased, your only option is to: CAUTION: **Caution:** This process is not suitable for removing sensitive data like password or keys from your repository. -Information about commits, including file content, is cached in the database, and will remain +Information about commits, including file content, is cached in the database, and remain visible even after they have been removed from the repository. ## Troubleshooting diff --git a/locale/gitlab.pot b/locale/gitlab.pot index 51b2d980229..9b400d6832e 100644 --- a/locale/gitlab.pot +++ b/locale/gitlab.pot @@ -2943,9 +2943,6 @@ msgstr "" msgid "An error has occurred" msgstr "" -msgid "An error has occurred fetching instructions" -msgstr "" - msgid "An error occured while making the changes: %{error}" msgstr "" @@ -9238,6 +9235,9 @@ msgstr "" msgid "Deployment|running" msgstr "" +msgid "Deployment|skipped" +msgstr "" + msgid "Deployment|success" msgstr "" @@ -14499,9 +14499,6 @@ msgstr "" msgid "Install Runner on Kubernetes" msgstr "" -msgid "Install a Runner" -msgstr "" - msgid "Install a soft token authenticator like %{free_otp_link} or Google Authenticator from your application repository and use that app to scan this QR code. More information is available in the %{help_link_start}documentation%{help_link_end}." msgstr "" @@ -23435,12 +23432,6 @@ msgstr "" msgid "Runners|Description" msgstr "" -msgid "Runners|Download Latest Binary" -msgstr "" - -msgid "Runners|Download and Install Binary" -msgstr "" - msgid "Runners|Group" msgstr "" @@ -23468,9 +23459,6 @@ msgstr "" msgid "Runners|Protected" msgstr "" -msgid "Runners|Register Runner" -msgstr "" - msgid "Runners|Revision" msgstr "" @@ -24878,9 +24866,6 @@ msgstr "" msgid "Should you ever lose your phone or access to your one time password secret, each of these recovery codes can be used one time each to regain access to your account. Please save them in a safe place, or you %{b_start}will%{b_end} lose access to your account." msgstr "" -msgid "Show Runner installation instructions" -msgstr "" - msgid "Show all activity" msgstr "" @@ -25125,6 +25110,9 @@ msgstr "" msgid "Skipped" msgstr "" +msgid "Skipped deployment to" +msgstr "" + msgid "Slack application" msgstr "" diff --git a/spec/frontend/vue_mr_widget/deployment/deployment_spec.js b/spec/frontend/vue_mr_widget/deployment/deployment_spec.js index 17d7fcc4bff..19a5566c3b1 100644 --- a/spec/frontend/vue_mr_widget/deployment/deployment_spec.js +++ b/spec/frontend/vue_mr_widget/deployment/deployment_spec.js @@ -8,6 +8,7 @@ import { SUCCESS, FAILED, CANCELED, + SKIPPED, } from '~/vue_merge_request_widget/components/deployment/constants'; import { deploymentMockData, playDetails, retryDetails } from './deployment_mock_data'; @@ -77,6 +78,10 @@ describe('Deployment component', () => { ${CANCELED} | ${true} | ${noDetails} | ${'Canceled deployment to'} | ${defaultGroup} ${CANCELED} | ${false} | ${deployDetail} | ${'Canceled deployment to'} | ${noActions} ${CANCELED} | ${false} | ${noDetails} | ${'Canceled deployment to'} | ${noActions} + ${SKIPPED} | ${true} | ${deployDetail} | ${'Skipped deployment to'} | ${defaultGroup} + ${SKIPPED} | ${true} | ${noDetails} | ${'Skipped deployment to'} | ${defaultGroup} + ${SKIPPED} | ${false} | ${deployDetail} | ${'Skipped deployment to'} | ${noActions} + ${SKIPPED} | ${false} | ${noDetails} | ${'Skipped deployment to'} | ${noActions} `( '$status + previous: $previous + manual: $deploymentDetails.isManual', ({ status, previous, deploymentDetails, text, actionButtons }) => { diff --git a/spec/frontend/vue_shared/components/runner_instructions/mock_data.js b/spec/frontend/vue_shared/components/runner_instructions/mock_data.js deleted file mode 100644 index 01f7f3d49c7..00000000000 --- a/spec/frontend/vue_shared/components/runner_instructions/mock_data.js +++ /dev/null @@ -1,107 +0,0 @@ -export const mockGraphqlRunnerPlatforms = { - data: { - runnerPlatforms: { - nodes: [ - { - name: 'linux', - humanReadableName: 'Linux', - architectures: { - nodes: [ - { - name: 'amd64', - downloadLocation: - 'https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64', - __typename: 'RunnerArchitecture', - }, - { - name: '386', - downloadLocation: - 'https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-386', - __typename: 'RunnerArchitecture', - }, - { - name: 'arm', - downloadLocation: - 'https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-arm', - __typename: 'RunnerArchitecture', - }, - { - name: 'arm64', - downloadLocation: - 'https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-arm64', - __typename: 'RunnerArchitecture', - }, - ], - __typename: 'RunnerArchitectureConnection', - }, - __typename: 'RunnerPlatform', - }, - { - name: 'osx', - humanReadableName: 'macOS', - architectures: { - nodes: [ - { - name: 'amd64', - downloadLocation: - 'https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64', - __typename: 'RunnerArchitecture', - }, - ], - __typename: 'RunnerArchitectureConnection', - }, - __typename: 'RunnerPlatform', - }, - { - name: 'windows', - humanReadableName: 'Windows', - architectures: { - nodes: [ - { - name: 'amd64', - downloadLocation: - 'https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-amd64.exe', - __typename: 'RunnerArchitecture', - }, - { - name: '386', - downloadLocation: - 'https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-windows-386.exe', - __typename: 'RunnerArchitecture', - }, - ], - __typename: 'RunnerArchitectureConnection', - }, - __typename: 'RunnerPlatform', - }, - { - name: 'docker', - humanReadableName: 'Docker', - architectures: null, - __typename: 'RunnerPlatform', - }, - { - name: 'kubernetes', - humanReadableName: 'Kubernetes', - architectures: null, - __typename: 'RunnerPlatform', - }, - ], - __typename: 'RunnerPlatformConnection', - }, - project: { id: 'gid://gitlab/Project/1', __typename: 'Project' }, - group: null, - }, -}; - -export const mockGraphqlInstructions = { - data: { - runnerSetup: { - installInstructions: - "# Download the binary for your system\nsudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64\n\n# Give it permissions to execute\nsudo chmod +x /usr/local/bin/gitlab-runner\n\n# Create a GitLab CI user\nsudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash\n\n# Install and run as service\nsudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner\nsudo gitlab-runner start\n", - registerInstructions: - 'sudo gitlab-runner register --url http://192.168.1.81:3000/ --registration-token GE5gsjeep_HAtBf9s3Yz', - __typename: 'RunnerSetup', - }, - }, -}; diff --git a/spec/frontend/vue_shared/components/runner_instructions/runner_instructions_spec.js b/spec/frontend/vue_shared/components/runner_instructions/runner_instructions_spec.js deleted file mode 100644 index afbcee506c7..00000000000 --- a/spec/frontend/vue_shared/components/runner_instructions/runner_instructions_spec.js +++ /dev/null @@ -1,119 +0,0 @@ -import { shallowMount, createLocalVue } from '@vue/test-utils'; -import VueApollo from 'vue-apollo'; -import createMockApollo from 'jest/helpers/mock_apollo_helper'; -import RunnerInstructions from '~/vue_shared/components/runner_instructions/runner_instructions.vue'; -import getRunnerPlatforms from '~/vue_shared/components/runner_instructions/graphql/queries/get_runner_platforms.query.graphql'; -import getRunnerSetupInstructions from '~/vue_shared/components/runner_instructions/graphql/queries/get_runner_setup.query.graphql'; - -import { mockGraphqlRunnerPlatforms, mockGraphqlInstructions } from './mock_data'; - -const projectPath = 'gitlab-org/gitlab'; -const localVue = createLocalVue(); -localVue.use(VueApollo); - -describe('RunnerInstructions component', () => { - let wrapper; - let fakeApollo; - - const findModalButton = () => wrapper.find('[data-testid="show-modal-button"]'); - const findPlatformButtons = () => wrapper.findAll('[data-testid="platform-button"]'); - const findArchitectureDropdownItems = () => - wrapper.findAll('[data-testid="architecture-dropdown-item"]'); - const findBinaryInstructionsSection = () => wrapper.find('[data-testid="binary-instructions"]'); - const findRunnerInstructionsSection = () => wrapper.find('[data-testid="runner-instructions"]'); - - beforeEach(() => { - const requestHandlers = [ - [getRunnerPlatforms, jest.fn().mockResolvedValue(mockGraphqlRunnerPlatforms)], - [getRunnerSetupInstructions, jest.fn().mockResolvedValue(mockGraphqlInstructions)], - ]; - - fakeApollo = createMockApollo(requestHandlers); - - wrapper = shallowMount(RunnerInstructions, { - provide: { - projectPath, - }, - localVue, - apolloProvider: fakeApollo, - }); - }); - - afterEach(() => { - wrapper.destroy(); - wrapper = null; - }); - - it('should show the "Show Runner installation instructions" button', () => { - const button = findModalButton(); - - expect(button.exists()).toBe(true); - expect(button.text()).toBe('Show Runner installation instructions'); - }); - - it('should contain a number of platforms buttons', () => { - const buttons = findPlatformButtons(); - - expect(buttons).toHaveLength(mockGraphqlRunnerPlatforms.data.runnerPlatforms.nodes.length); - }); - - it('should contain a number of dropdown items for the architecture options', () => { - const platformButton = findPlatformButtons().at(0); - platformButton.vm.$emit('click'); - - return wrapper.vm.$nextTick(() => { - const dropdownItems = findArchitectureDropdownItems(); - - expect(dropdownItems).toHaveLength( - mockGraphqlRunnerPlatforms.data.runnerPlatforms.nodes[0].architectures.nodes.length, - ); - }); - }); - - it('should display the binary installation instructions for a selected architecture', async () => { - const platformButton = findPlatformButtons().at(0); - platformButton.vm.$emit('click'); - - await wrapper.vm.$nextTick(); - - const dropdownItem = findArchitectureDropdownItems().at(0); - dropdownItem.vm.$emit('click'); - - await wrapper.vm.$nextTick(); - - const runner = findBinaryInstructionsSection(); - - expect(runner.text()).toEqual( - expect.stringContaining('sudo chmod +x /usr/local/bin/gitlab-runner'), - ); - expect(runner.text()).toEqual( - expect.stringContaining( - `sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash`, - ), - ); - expect(runner.text()).toEqual( - expect.stringContaining( - 'sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner', - ), - ); - expect(runner.text()).toEqual(expect.stringContaining('sudo gitlab-runner start')); - }); - - it('should display the runner register instructions for a selected architecture', async () => { - const platformButton = findPlatformButtons().at(0); - platformButton.vm.$emit('click'); - - await wrapper.vm.$nextTick(); - - const dropdownItem = findArchitectureDropdownItems().at(0); - dropdownItem.vm.$emit('click'); - - await wrapper.vm.$nextTick(); - - const runner = findRunnerInstructionsSection(); - - expect(runner.text()).toEqual( - expect.stringContaining(mockGraphqlInstructions.data.runnerSetup.registerInstructions), - ); - }); -}); diff --git a/spec/models/ci/build_spec.rb b/spec/models/ci/build_spec.rb index 5ff9b4dd493..7f162f761a9 100644 --- a/spec/models/ci/build_spec.rb +++ b/spec/models/ci/build_spec.rb @@ -1151,12 +1151,26 @@ RSpec.describe Ci::Build do end context 'when transits to skipped' do - before do - build.skip! + context 'when cd_skipped_deployment_status is disabled' do + before do + stub_feature_flags(cd_skipped_deployment_status: false) + build.skip! + end + + it 'transits deployment status to canceled' do + expect(deployment).to be_canceled + end end - it 'transits deployment status to canceled' do - expect(deployment).to be_canceled + context 'when cd_skipped_deployment_status is enabled' do + before do + stub_feature_flags(cd_skipped_deployment_status: project) + build.skip! + end + + it 'transits deployment status to skipped' do + expect(deployment).to be_skipped + end end end diff --git a/spec/models/deployment_spec.rb b/spec/models/deployment_spec.rb index 9afacd518af..ee5eaec3f84 100644 --- a/spec/models/deployment_spec.rb +++ b/spec/models/deployment_spec.rb @@ -202,6 +202,31 @@ RSpec.describe Deployment do deployment.cancel! end end + + context 'when deployment was skipped' do + let(:deployment) { create(:deployment, :running) } + + it 'has correct status' do + deployment.skip! + + expect(deployment).to be_skipped + expect(deployment.finished_at).to be_nil + end + + it 'does not execute Deployments::LinkMergeRequestWorker asynchronously' do + expect(Deployments::LinkMergeRequestWorker) + .not_to receive(:perform_async).with(deployment.id) + + deployment.skip! + end + + it 'does not execute Deployments::ExecuteHooksWorker' do + expect(Deployments::ExecuteHooksWorker) + .not_to receive(:perform_async).with(deployment.id) + + deployment.skip! + end + end end describe '#success?' do @@ -320,6 +345,7 @@ RSpec.describe Deployment do deployment2 = create(:deployment, status: :running ) create(:deployment, status: :failed ) create(:deployment, status: :canceled ) + create(:deployment, status: :skipped) is_expected.to contain_exactly(deployment1, deployment2) end @@ -350,6 +376,20 @@ RSpec.describe Deployment do is_expected.to contain_exactly(with_deployable) end end + + describe 'visible' do + subject { described_class.visible } + + it 'retrieves the visible deployments' do + deployment1 = create(:deployment, status: :running) + deployment2 = create(:deployment, status: :success) + deployment3 = create(:deployment, status: :failed) + deployment4 = create(:deployment, status: :canceled) + create(:deployment, status: :skipped) + + is_expected.to contain_exactly(deployment1, deployment2, deployment3, deployment4) + end + end end describe '#includes_commit?' do diff --git a/spec/services/projects/transfer_service_spec.rb b/spec/services/projects/transfer_service_spec.rb index 3ae96d7a5ab..8e6147e7a3c 100644 --- a/spec/services/projects/transfer_service_spec.rb +++ b/spec/services/projects/transfer_service_spec.rb @@ -9,7 +9,7 @@ RSpec.describe Projects::TransferService do let_it_be(:group) { create(:group) } let(:project) { create(:project, :repository, :legacy_storage, namespace: user.namespace) } - subject(:execute_transfer) { described_class.new(project, user).execute(group) } + subject(:execute_transfer) { described_class.new(project, user).execute(group).tap { project.reload } } context 'with npm packages' do before do |