diff --git a/doc/_index.md b/doc/_index.md index b4ba90f7e67de5a0eaf0300b3d33acfe4d286bd1..c55a5384718d74a259b1840924b7b74e656bc1aa 100644 --- a/doc/_index.md +++ b/doc/_index.md @@ -49,7 +49,7 @@ Learn about GitLab account management: |:-----------------------------------------------------------|:------------| | [User account](user/profile/_index.md) | Manage your account. | | [Authentication](administration/auth/_index.md) | Account security with two-factor authentication, set up your SSH keys, and deploy keys for secure access to your projects. | -| [User settings](user/profile/_index.md#access-your-user-settings) | Manage your user settings, two factor authentication, and more. | +| User settings | Manage your user settings, two factor authentication, and more. | | [User permissions](user/permissions.md) | Learn what each role in a project can do. | ## Coming to GitLab from another platform @@ -59,7 +59,7 @@ If you are coming to GitLab from another platform: | Topic | Description | |:---------------------------------------------------------------------------------------|:------------| | [Import to GitLab](user/project/import/_index.md) | Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz, and SVN into GitLab. | -| [Migrate from SVN](user/project/import/_index.md#import-repositories-from-subversion) | Convert a SVN repository to Git and GitLab. | +| Migrate from SVN | Convert a SVN repository to Git and GitLab. | ## Build an integration with GitLab diff --git a/doc/ci/chatops/_index.md b/doc/ci/chatops/_index.md index e8bfc864ba5c168193376fd266985d58894d2613..7baa6c0d286a69ed88ea4634370333d4af0fc779 100644 --- a/doc/ci/chatops/_index.md +++ b/doc/ci/chatops/_index.md @@ -40,7 +40,7 @@ pipeline, but the job doesn't start automatically. A job run with ChatOps has the same functionality as a job run from GitLab. The job can use existing [CI/CD variables](../variables/_index.md#predefined-cicd-variables) like `GITLAB_USER_ID` to perform additional rights validation, but these -variables can be [overridden](../variables/_index.md#cicd-variable-precedence). +variables can be overridden. You should set [`rules`](../yaml/_index.md#rules) so the job does not run as part of the standard CI/CD pipeline. diff --git a/doc/ci/components/examples.md b/doc/ci/components/examples.md index 80eae1b6c7d7c906885ab6d0b9ade3bfadfb7d5b..d5610e70aea0f935d05684652d2ce2522dbfe354 100644 --- a/doc/ci/components/examples.md +++ b/doc/ci/components/examples.md @@ -264,8 +264,8 @@ The CI/CD template migration involves the following steps: with `latest` as default value for more flexible and reusable pipelines. The input must match the Docker Hub image tag values. - The `compile` job builds the binaries into a hard-coded target directory `mybinaries`, - which can be enhanced with a dynamic [input](../inputs/_index.md) and default value `mybinaries`. -1. Create a template [directory structure](_index.md#directory-structure) for the new component, + which can be enhanced with a dynamic input and default value `mybinaries`. +1. Create a template directory structure for the new component, based on one template for each job. - The name of the template should follow the `go` command, for example `format.yml`, `build.yml`, and `test.yml`. diff --git a/doc/ci/docker/authenticate_registry.md b/doc/ci/docker/authenticate_registry.md index 319adf21531ace33425854d939275ae0461613ee..1f057753e3c9e5a3ebac9b33c3dfd7a2d936e305 100644 --- a/doc/ci/docker/authenticate_registry.md +++ b/doc/ci/docker/authenticate_registry.md @@ -121,7 +121,7 @@ You can define this authentication in several ways: - In [`pre_build_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) in the runner configuration file. - In [`before_script`](../yaml/_index.md#before_script). -- In [`script`](../yaml/_index.md#script). +- In `script`. The following example shows [`before_script`](../yaml/_index.md#before_script). The same commands apply for any solution you implement. diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 279c3877100035d9f6b2ac36a1d7f16ca4f80c7c..ebd60b1e4251b40f6f2b0457acb709aac610a340 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -504,7 +504,7 @@ For the `docker-windows` executor, use a configuration similar to this example: ``` For complex Docker-in-Docker setups like [Code Quality scanning using CodeClimate](../testing/code_quality_codeclimate_scanning.md), you must match host and container paths for proper execution. For more details, see -[Use private runners for CodeClimate-based scanning](../testing/code_quality_codeclimate_scanning.md#use-private-runners). +Use private runners for CodeClimate-based scanning. #### Enable registry mirror for `docker:dind` service diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index e9fec219f9232ed6c9f0bc345b6560d7790fbdf4..8cc10274783e7dd89457bb38b5136e66e3f074b7 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -161,8 +161,8 @@ CI/CD jobs: 1. The runner attaches itself to a running container. 1. The runner prepares a script (the combination of [`before_script`](../yaml/_index.md#before_script), - [`script`](../yaml/_index.md#script), - and [`after_script`](../yaml/_index.md#after_script)). + `script`, + and `after_script`). 1. The runner sends the script to the container's shell `stdin` and receives the output. diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index b7ccfc3474c000f1167d40319d8d8f6869af545f..8bd726ddbf9a2124650e6843720600bd9e1926cb 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -14,4 +14,4 @@ title: Use kaniko to build Docker images (removed) [kaniko](https://github.com/GoogleContainerTools/kaniko) is no longer a maintained project. For more information, see [issue 3348](https://github.com/GoogleContainerTools/kaniko/issues/3348). -Use [Docker to build Docker images](using_docker_build.md), [Buildah](using_docker_build.md#buildah-example), [Podman to run Docker commands](https://docs.gitlab.com/runner/executors/docker/#use-podman-to-run-docker-commands), or [Podman with GitLab Runner on Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes/use_podman_with_kubernetes/) instead. +Use [Docker to build Docker images](using_docker_build.md), Buildah, [Podman to run Docker commands](https://docs.gitlab.com/runner/executors/docker/#use-podman-to-run-docker-commands), or [Podman with GitLab Runner on Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes/use_podman_with_kubernetes/) instead. diff --git a/doc/ci/environments/_index.md b/doc/ci/environments/_index.md index b3b60cabe86f7fe8dcc73c255c1610bbfca741af..7979d086f1ecb2b334bde299a72e82ba433db606 100644 --- a/doc/ci/environments/_index.md +++ b/doc/ci/environments/_index.md @@ -293,7 +293,7 @@ you can use tiers: By default, GitLab assumes a tier based on [the environment name](../yaml/_index.md#environmentname). You cannot set an environment tier using the UI. -Instead, you can use the [`deployment_tier` keyword](../yaml/_index.md#environmentdeployment_tier) to specify a tier. +Instead, you can use the `deployment_tier` keyword to specify a tier. ### Rename an environment @@ -354,7 +354,7 @@ These environment scopes match as follows: | `review/feature-1` | | | Match | | You should not use environment-scoped variables with [`rules`](../yaml/_index.md#rules) -or [`include`](../yaml/_index.md#include). The variables might not be defined when +or `include`. The variables might not be defined when GitLab validates the pipeline configuration at pipeline creation. ## Search environments @@ -641,8 +641,8 @@ Prerequisites: - The stop job must have the following keywords defined: - `when`, defined at either: - [The job level](../yaml/_index.md#when). - - [In a rules clause](../yaml/_index.md#rules). If you use `rules` and `when: manual`, you should - also set [`allow_failure: true`](../yaml/_index.md#allow_failure) so the pipeline can complete + - In a rules clause. If you use `rules` and `when: manual`, you should + also set `allow_failure: true` so the pipeline can complete even if the job doesn't run. - `environment:name` - `environment:action` @@ -697,7 +697,7 @@ When an environment is stopped, the matching `on_stop` actions from only success All `on_stop` actions for an environment must belong to the same pipeline. To use multiple `on_stop` actions in [downstream pipelines](../pipelines/downstream_pipelines.md), you must configure the environment actions in -the parent pipeline. For more information, see [downstream pipelines for deployments](../pipelines/downstream_pipelines.md#advanced-example). +the parent pipeline. For more information, see downstream pipelines for deployments. {{< /alert >}} diff --git a/doc/ci/environments/deployments.md b/doc/ci/environments/deployments.md index b3674a13da6ea18482588e60cb1661a069397354..a1f0d466340bc9e4d9bfeff2e48f53c5de9eaf10 100644 --- a/doc/ci/environments/deployments.md +++ b/doc/ci/environments/deployments.md @@ -144,7 +144,7 @@ To retry or roll back a deployment: If you have [prevented outdated deployment jobs](deployment_safety.md#prevent-outdated-deployment-jobs) in your project, the rollback buttons might be hidden or disabled. -In this case, see [job retries for rollback deployments](deployment_safety.md#job-retries-for-rollback-deployments). +In this case, see job retries for rollback deployments. {{< /alert >}} diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index eaa193d977050597e723cfa9ed39a977970a72a8..91978568625d0d77ec4f308f71c6de8d3e3b8a2a 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -295,6 +295,6 @@ Protected environments can also be used to require manual approvals before deplo ### Reporter can't run a trigger job that deploys to a protected environment in downstream pipeline -A user who has [deployment-only access to protected environments](#deployment-only-access-to-protected-environments) might **not** be able to run a job if it's with a [`trigger`](../yaml/_index.md#trigger) keyword. This is because the job is missing the [`environment`](../yaml/_index.md#environment) keyword definition to associate the job with the protected environment, therefore the job is recognized as a standard job that uses [regular CI/CD permission model](../../user/permissions.md#cicd). +A user who has [deployment-only access to protected environments](#deployment-only-access-to-protected-environments) might **not** be able to run a job if it's with a [`trigger`](../yaml/_index.md#trigger) keyword. This is because the job is missing the `environment` keyword definition to associate the job with the protected environment, therefore the job is recognized as a standard job that uses [regular CI/CD permission model](../../user/permissions.md#cicd). See [this issue](https://gitlab.com/groups/gitlab-org/-/epics/8483) for more information about supporting `environment` keyword with `trigger` keyword. diff --git a/doc/ci/pipeline_editor/_index.md b/doc/ci/pipeline_editor/_index.md index cd39e4dda37ccf42b549009bc7966741dee6819b..6f271f5226e4d98fea3f294c4220524ce55fa27f 100644 --- a/doc/ci/pipeline_editor/_index.md +++ b/doc/ci/pipeline_editor/_index.md @@ -112,10 +112,10 @@ pipeline editor's **Full configuration** tab. This tab displays an expanded conf where: - Configuration imported with [`include`](../yaml/_index.md#include) is copied into the view. -- Jobs that use [`extends`](../yaml/_index.md#extends) display with the +- Jobs that use `extends` display with the [extended configuration merged into the job](../yaml/yaml_optimization.md#merge-details). -- [YAML anchors](../yaml/yaml_optimization.md#anchors) are replaced with the linked configuration. -- [YAML `!reference` tags](../yaml/yaml_optimization.md#reference-tags) are also replaced +- YAML anchors are replaced with the linked configuration. +- YAML `!reference` tags are also replaced with the linked configuration. - Conditional rules are evaluated assuming a default branch push event. diff --git a/doc/ci/pipeline_security/_index.md b/doc/ci/pipeline_security/_index.md index 6878da93857d2ba6848186836e8615ddebd6646b..3ff20fd25db50549d5100383afd6ba5e87926e3d 100644 --- a/doc/ci/pipeline_security/_index.md +++ b/doc/ci/pipeline_security/_index.md @@ -44,7 +44,7 @@ Variable values: - Are stored in the GitLab project, group, or instance settings. Users with access to the settings have access to variables values that are not [hidden](../variables/_index.md#hide-a-cicd-variable). -- Can be [overridden](../variables/_index.md#use-pipeline-variables), +- Can be overridden, making it hard to determine which value was used. - Can be exposed by accidental pipeline misconfiguration. diff --git a/doc/ci/pipelines/_index.md b/doc/ci/pipelines/_index.md index 455c2c0caf8e594b345d4a3092ccf19e274a6972..291e6da3afcc730b8628ec4e97084178fee3cee4 100644 --- a/doc/ci/pipelines/_index.md +++ b/doc/ci/pipelines/_index.md @@ -60,7 +60,7 @@ Pipelines can be configured in many different ways: - [Parent-child pipelines](downstream_pipelines.md#parent-child-pipelines) break down complex pipelines into one parent pipeline that can trigger multiple child sub-pipelines, which all run in the same project and with the same SHA. This pipeline architecture is commonly used for mono-repos. -- [Multi-project pipelines](downstream_pipelines.md#multi-project-pipelines) combine pipelines for different projects together. +- Multi-project pipelines combine pipelines for different projects together. ## Configure a pipeline @@ -130,8 +130,8 @@ that have a `description` defined in the `.gitlab-ci.yml` file. The description below the variable. You can change the prefilled value, which [overrides the value](../variables/_index.md#use-pipeline-variables) for that single pipeline run. -Any variables overridden by using this process are [expanded](../variables/_index.md#prevent-cicd-variable-expansion) -and not [masked](../variables/_index.md#mask-a-cicd-variable). +Any variables overridden by using this process are expanded +and not masked. If you do not define a `value` for the variable in the configuration file, the variable name is still listed, but the value field is blank. @@ -157,7 +157,7 @@ In this example: Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/382857), projects that use [compliance pipelines](../../user/compliance/compliance_pipelines.md) can have prefilled variables not appear when running a pipeline manually. To workaround this issue, -[change the compliance pipeline configuration](../../user/compliance/compliance_pipelines.md#prefilled-variables-are-not-shown). +change the compliance pipeline configuration. {{< /alert >}} diff --git a/doc/ci/pipelines/compute_minutes.md b/doc/ci/pipelines/compute_minutes.md index f4fe1776874d43c37e236e664ff324c0d740e0dd..437d7db63f8af8012c1b9b228135db5e040d8a68 100644 --- a/doc/ci/pipelines/compute_minutes.md +++ b/doc/ci/pipelines/compute_minutes.md @@ -77,7 +77,7 @@ that ran in the pipeline. Jobs can run concurrently, so the total compute usage can be higher than the end-to-end duration of a pipeline. [Trigger jobs](../yaml/_index.md#trigger) do not execute on runners, so they do not -consume compute minutes, even when using [`strategy:depend`](../yaml/_index.md#triggerstrategy) +consume compute minutes, even when using `strategy:depend` to wait for the [downstream pipeline](downstream_pipelines.md) status. The triggered downstream pipeline consumes compute minutes the same as other pipelines. diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index e36dbda6c4bde674c5a49d66a86a18e7e8867b5a..f0f895238acd815c877abcaa28e4a43633ed814d 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -39,7 +39,7 @@ Child pipelines: if a pipeline fails for the main branch, it's common to say that "main is broken". The status of child pipelines only affects the status of the ref if the child pipeline is triggered with [`trigger:strategy`](../yaml/_index.md#triggerstrategy). -- Are automatically canceled if the pipeline is configured with [`interruptible`](../yaml/_index.md#interruptible) +- Are automatically canceled if the pipeline is configured with `interruptible` when a new pipeline is created for the same ref. - Are not displayed in the project's pipeline list. You can only view child pipelines on their parent pipeline's details page. @@ -68,7 +68,7 @@ Multi-project pipelines: - Affect the overall status of the ref of the project it runs in, but does not affect the status of the triggering pipeline's ref, unless it was triggered with [`trigger:strategy`](../yaml/_index.md#triggerstrategy). -- Are not automatically canceled in the downstream project when using [`interruptible`](../yaml/_index.md#interruptible) +- Are not automatically canceled in the downstream project when using `interruptible` if a new pipeline runs for the same ref in the upstream pipeline. They can be automatically canceled if a new pipeline is triggered for the same ref on the downstream project. - Are visible in the downstream project's pipeline list. @@ -242,7 +242,7 @@ this issue. ### Run child pipelines with merge request pipelines Pipelines, including child pipelines, run as branch pipelines by default when not using -[`rules`](../yaml/_index.md#rules) or [`workflow:rules`](../yaml/_index.md#workflowrules). +[`rules`](../yaml/_index.md#rules) or `workflow:rules`. To configure child pipelines to run when triggered from a [merge request (parent) pipeline](merge_request_pipelines.md), use `rules` or `workflow:rules`. For example, using `rules`: @@ -893,7 +893,7 @@ are considered trigger variables, which have the [highest precedence](../variabl {{< /history >}} -You can use the [`environment`](../yaml/_index.md#environment) keyword with [`trigger`](../yaml/_index.md#trigger). +You can use the [`environment`](../yaml/_index.md#environment) keyword with `trigger`. You might want to use `environment` from a trigger job if your deployment and application projects are separately managed. ```yaml diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index c598911f5134e0a3ba90c4ab836e119760b35120..708ad971eeed8a03bd7d2bc170358817d1bef9f8 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -154,7 +154,7 @@ When you use merge request pipelines, you can use: - All the same [predefined variables](../variables/predefined_variables.md) that are available in branch pipelines. -- [Additional predefined variables](../variables/predefined_variables.md#predefined-variables-for-merge-request-pipelines) +- Additional predefined variables available only to jobs in merge request pipelines. ## Control access to protected variables and runners diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index 60cb8f56d9bacf6287cb5325eacd3f26f32f07db..b16330f6a6bfdca677c43046cda2befa19faf17e 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -215,7 +215,7 @@ You can combine parent-child pipelines with: - The [`rules` keyword](../yaml/_index.md#rules): For example, have the child pipelines triggered only when there are changes to that area. -- The [`include` keyword](../yaml/_index.md#include): Bring in common behaviors, ensuring +- The `include` keyword: Bring in common behaviors, ensuring you are not repeating yourself. - The [`needs` keyword](#pipelines-with-the-needs-keyword) inside of child pipelines, achieving the benefits of both. diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 7d8a58442457a0327e3c6d980ebbec97d714f72c..8be9921391ed260991b82db169cdd04fff839296 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -165,10 +165,10 @@ to stop them from running: - Use the [`interruptible`](../yaml/_index.md#interruptible) keyword to stop old pipelines when they are superseded by a newer pipeline. -- Use [`rules`](../yaml/_index.md#rules) to skip tests that aren't needed. For example, +- Use `rules` to skip tests that aren't needed. For example, skip backend tests when only the frontend code is changed. - Run non-essential [scheduled pipelines](schedules.md) less frequently. -- Distribute [`cron` schedules](schedules.md#view-and-optimize-pipeline-schedules) evenly across time. +- Distribute `cron` schedules evenly across time. ### Fail fast @@ -194,7 +194,7 @@ be more efficient, but can also make pipelines harder to understand and analyze. ### Caching Another optimization method is to [cache](../caching/_index.md) dependencies. If your -dependencies change rarely, like [NodeJS `/node_modules`](../caching/_index.md#cache-nodejs-dependencies), +dependencies change rarely, like NodeJS `/node_modules`, caching can make pipeline execution much faster. You can use [`cache:when`](../yaml/_index.md#cachewhen) to cache downloaded dependencies diff --git a/doc/ci/resource_groups/_index.md b/doc/ci/resource_groups/_index.md index be41e0a772cde760885a95087d41cbdc2fafd99f..8f9d4cd2f7e69e900371ddf7ddd708c4bee5e247 100644 --- a/doc/ci/resource_groups/_index.md +++ b/doc/ci/resource_groups/_index.md @@ -130,7 +130,7 @@ Depending on the process mode of the resource group: You can define `resource_group` for downstream pipelines that are sensitive to concurrent executions. The [`trigger` keyword](../yaml/_index.md#trigger) can trigger downstream pipelines and the -[`resource_group` keyword](../yaml/_index.md#resource_group) can co-exist with it. `resource_group` is efficient to control the +`resource_group` keyword can co-exist with it. `resource_group` is efficient to control the concurrency of deployment pipelines, while other jobs can continue to run concurrently. The following example has two pipeline configurations in a project. When a pipeline starts running, diff --git a/doc/ci/secrets/_index.md b/doc/ci/secrets/_index.md index 30210f18a49e609ab11744db5bc9b714beb205c9..36cd3c3f9c253929b642ff347c9a59c742199e58 100644 --- a/doc/ci/secrets/_index.md +++ b/doc/ci/secrets/_index.md @@ -257,7 +257,7 @@ generated by this GitLab instance may be allowed to authenticate using this role For a full list of ID token JWT claims, read the [How It Works](hashicorp_vault.md) section of the -[Authenticating and Reading Secrets With HashiCorp Vault](hashicorp_vault.md) tutorial. +Authenticating and Reading Secrets With HashiCorp Vault tutorial. You can also specify some attributes for the resulting Vault tokens, such as time-to-live, IP address range, and number of uses. The full list of options is available in diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md index 6f5ca4cf0c0db70a9d6a042d07054faa6c262691..9d84cf27e14c9ab7874545bbfa0b2e48382e5789 100644 --- a/doc/ci/secrets/id_token_authentication.md +++ b/doc/ci/secrets/id_token_authentication.md @@ -24,7 +24,7 @@ You can authenticate with third party services using GitLab CI/CD's ## ID Tokens [ID tokens](../yaml/_index.md#id_tokens) are JSON Web Tokens (JWTs) that can be added to a GitLab CI/CD job. They can be used for OIDC -authentication with third-party services, and are used by the [`secrets`](../yaml/_index.md#secrets) keyword to authenticate with HashiCorp Vault. +authentication with third-party services, and are used by the `secrets` keyword to authenticate with HashiCorp Vault. ID tokens are configured in the `.gitlab-ci.yml`. For example: diff --git a/doc/ci/secure_files/_index.md b/doc/ci/secure_files/_index.md index c96ad3aa33ef75e2e146a4ba15c4bc3d45015d20..36c12e3fd5c775232a118e184edee1da115acc2a 100644 --- a/doc/ci/secure_files/_index.md +++ b/doc/ci/secure_files/_index.md @@ -111,8 +111,8 @@ is generated for each file when it is created and persisted in the database. The are stored in either local storage or object storage depending on the [GitLab instance configuration](../../administration/cicd/secure_files.md). Individual files can be retrieved with the [secure files download API](../../api/secure_files.md#download-secure-file). -Metadata can be retrieved with the [list](../../api/secure_files.md#list-project-secure-files) -or [show](../../api/secure_files.md#show-secure-file-details) API endpoints. Files can also be retrieved +Metadata can be retrieved with the list +or show API endpoints. Files can also be retrieved with the [`download-secure-files`](https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files) tool. This tool automatically verifies the checksum of each file as it is downloaded. diff --git a/doc/ci/testing/unit_test_reports.md b/doc/ci/testing/unit_test_reports.md index c57f083ebabcd1b03a3f2b0508e6708ac999290a..bb17959b9ca582a9e4952b999b8959b1ace53485 100644 --- a/doc/ci/testing/unit_test_reports.md +++ b/doc/ci/testing/unit_test_reports.md @@ -117,7 +117,7 @@ To configure unit test reports: [`artifacts:reports:junit`](../yaml/artifacts_reports.md#artifactsreportsjunit) to your test job. 1. Specify the path to your XML test report files. 1. Optional. To make report files browsable, include them with [`artifacts:paths`](../yaml/_index.md#artifactspaths). -1. Optional. To upload reports even when jobs fail, use [`artifacts:when:always`](../yaml/_index.md#artifactswhen). +1. Optional. To upload reports even when jobs fail, use `artifacts:when:always`. Example configuration for Ruby with RSpec: diff --git a/doc/dupe.py b/doc/dupe.py new file mode 100644 index 0000000000000000000000000000000000000000..a51e84b4b5a3e0761475d3ae5b706486a13b2457 --- /dev/null +++ b/doc/dupe.py @@ -0,0 +1,106 @@ +import os +import re + +DOC_ROOT = "/Users/sselhorn/dev/gitlab/gitlab/doc" +EXCLUDED_DIRS = {"development", "solutions"} +MAX_FILES_TO_MODIFY = 20 + +# Match markdown-style links to .md files +MARKDOWN_LINK_PATTERN = re.compile(r'\[([^\]]+)]\(([^)\s#]+\.md)(#[^\)]*)?\)') + +# Identify markdown alignment lines like |:---|---:| +TABLE_ALIGNMENT_PATTERN = re.compile(r'^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?\s*$') + +# Identify bulleted or numbered list lines +LIST_LINE_PATTERN = re.compile(r'^\s*([-*+]|\d+\.)\s+') + +def should_exclude(path): + parts = os.path.relpath(path, DOC_ROOT).split(os.sep) + return any(part in EXCLUDED_DIRS for part in parts) + +def is_table_block(lines): + pipe_lines = [line for line in lines if line.count('|') >= 2] + has_alignment = any(TABLE_ALIGNMENT_PATTERN.match(line) for line in lines) + return len(pipe_lines) >= 2 and has_alignment + +def is_list_block(lines): + return all(LIST_LINE_PATTERN.match(line.strip()) for line in lines if line.strip()) + +def deduplicate_links_in_paragraph(paragraph): + lines = paragraph.strip().splitlines() + + # Skip tables and bulleted/numbered lists + if is_table_block(lines) or is_list_block(lines): + return paragraph, False + + matches = list(MARKDOWN_LINK_PATTERN.finditer(paragraph)) + seen_paths = set() + result = paragraph + offset = 0 + changed = False + + for match in matches: + full_match = match.group(0) + text = match.group(1) + path = match.group(2) + start, end = match.span() + + if path in seen_paths: + result = result[:start - offset] + text + result[end - offset:] + offset += len(full_match) - len(text) + changed = True + else: + seen_paths.add(path) + + return result, changed + +def process_markdown_file(filepath, can_modify=True): + with open(filepath, 'r', encoding='utf-8') as f: + content = f.read() + + paragraphs = content.split('\n\n') + new_paragraphs = [] + modified = False + + for p in paragraphs: + new_p, changed = deduplicate_links_in_paragraph(p) + new_paragraphs.append(new_p) + if changed: + modified = True + + if modified and can_modify: + with open(filepath, 'w', encoding='utf-8') as f: + f.write('\n\n'.join(new_paragraphs)) + + return modified + +def main(): + modified_count = 0 + reviewed_count = 0 + + for root, dirs, files in os.walk(DOC_ROOT): + dirs[:] = [d for d in dirs if d not in EXCLUDED_DIRS] + + for file in files: + if not file.endswith('.md'): + continue + + filepath = os.path.join(root, file) + if should_exclude(filepath): + continue + + reviewed_count += 1 + can_modify = modified_count < MAX_FILES_TO_MODIFY + was_modified = process_markdown_file(filepath, can_modify) + + status = "MODIFIED" if was_modified and can_modify else "REVIEWED" + print(f"{status}: {filepath}") + + if was_modified and can_modify: + modified_count += 1 + + print(f"\nTotal reviewed: {reviewed_count}") + print(f"Total modified: {modified_count} (limit: {MAX_FILES_TO_MODIFY})") + +if __name__ == "__main__": + main() diff --git a/doc/install/aws/_index.md b/doc/install/aws/_index.md index f8c96762745ee0e83ce621b2a6a8b1979b5ff0e8..10b3b2d3f4a3eb1c5b4b439c349fc5f844098cce 100644 --- a/doc/install/aws/_index.md +++ b/doc/install/aws/_index.md @@ -913,8 +913,8 @@ Some important things to know: - The backup/restore tool **does not** store some configuration files, like secrets; you must [configure this yourself](../../administration/backup_restore/backup_gitlab.md#storing-configuration-files). - By default, the backup files are stored locally, but you can - [backup GitLab using S3](../../administration/backup_restore/backup_gitlab.md#using-amazon-s3). -- You can [exclude specific directories form the backup](../../administration/backup_restore/backup_gitlab.md#excluding-specific-data-from-the-backup). + backup GitLab using S3. +- You can exclude specific directories form the backup. ### Backing up GitLab @@ -996,6 +996,6 @@ If you see this page when trying to set a password via the web interface, make s ### Some job logs are not uploaded to object storage -When the GitLab deployment is scaled up to more than one node, some job logs may not be uploaded to [object storage](../../administration/object_storage.md) properly. [Incremental logging is required](../../administration/object_storage.md#alternatives-to-file-system-storage) for CI to use object storage. +When the GitLab deployment is scaled up to more than one node, some job logs may not be uploaded to [object storage](../../administration/object_storage.md) properly. Incremental logging is required for CI to use object storage. Enable [incremental logging](../../administration/cicd/job_logs.md#incremental-logging) if it has not already been enabled. diff --git a/doc/install/docker/upgrade.md b/doc/install/docker/upgrade.md index 3502b28f44a0c9e9c01e920e0818d885e193acf3..168008e9a745b76a4ffeb4b65dda9295573a1327 100644 --- a/doc/install/docker/upgrade.md +++ b/doc/install/docker/upgrade.md @@ -18,7 +18,7 @@ Upgrade a Docker-based installation to a later version of GitLab. To upgrade a GitLab instance that was [installed using Docker Engine](installation.md#install-gitlab-by-using-docker-engine): -1. Create a [backup](backup.md). As a minimum, back up [the database](backup.md#create-a-database-backup) and +1. Create a [backup](backup.md). As a minimum, back up the database and the GitLab secrets file. 1. Stop the running container: @@ -70,7 +70,7 @@ when upgrading to different versions. To upgrade a GitLab instance that was [installed using Docker Compose](installation.md#install-gitlab-by-using-docker-compose): -1. Take a [backup](backup.md). As a minimum, back up [the database](backup.md#create-a-database-backup) and +1. Take a [backup](backup.md). As a minimum, back up the database and the GitLab secrets file. 1. Edit `docker-compose.yml` and change the version to pull. 1. Download the newest release and upgrade your GitLab instance: diff --git a/doc/install/install_methods.md b/doc/install/install_methods.md index 1f7a002ff77007570ed7df46a0afd1dc957cf428..ad033b0bdf785fcd932691145ebc2c3f13272a63 100644 --- a/doc/install/install_methods.md +++ b/doc/install/install_methods.md @@ -27,7 +27,7 @@ For more information, see: - [Linux package](package/_index.md) - [Reference architectures](../administration/reference_architectures/_index.md) - [System requirements](requirements.md) -- [Supported Linux operating systems](package/_index.md#supported-platforms) +- Supported Linux operating systems ## Helm chart diff --git a/doc/install/package/_index.md b/doc/install/package/_index.md index 9ec032280b947338c0f00a582a70d9efa4fcb403..fba8df86ccf6884b3ef8100bd035475f4e2d3e21 100644 --- a/doc/install/package/_index.md +++ b/doc/install/package/_index.md @@ -67,21 +67,21 @@ and refer to the same architecture. | Operating system | First supported GitLab version | Architecture | Operating system EOL | Proposed last supported GitLab version | Upstream release notes | |------------------------------------------------------------------------------------|--------------------------------|-----------------------|----------------------|-------------------------------|---------------------------------------------------------------------------------------------------------------| | [AlmaLinux 8](almalinux.md) | GitLab CE / GitLab EE 14.5.0 | `x86_64`, `aarch64` 1 | Mar 2029 | GitLab CE / GitLab EE 21.10.0 | [AlmaLinux details](https://almalinux.org/) | -| [AlmaLinux 9](almalinux.md) | GitLab CE / GitLab EE 16.0.0 | `x86_64`, `aarch64` 1 | May 2032 | GitLab CE / GitLab EE 25.0.0 | [AlmaLinux details](https://almalinux.org/) | +| AlmaLinux 9 | GitLab CE / GitLab EE 16.0.0 | `x86_64`, `aarch64` 1 | May 2032 | GitLab CE / GitLab EE 25.0.0 | [AlmaLinux details](https://almalinux.org/) | | [Amazon Linux 2](amazonlinux_2.md) | GitLab CE / GitLab EE 14.9.0 | `amd64`, `arm64` 1 | June 2026 | GitLab CE / GitLab EE 19.1.0 | [Amazon Linux details](https://aws.amazon.com/amazon-linux-2/faqs/) | | [Amazon Linux 2023](amazonlinux_2023.md) | GitLab CE / GitLab EE 16.3.0 | `amd64`, `arm64` 1 | June 2029 | GitLab CE / GitLab EE 22.1.0 | [Amazon Linux details](https://docs.aws.amazon.com/linux/al2023/ug/release-cadence.html) | | [Debian 11](debian.md) | GitLab CE / GitLab EE 14.6.0 | `amd64`, `arm64` 1 | Aug 2026 | GitLab CE / GitLab EE 19.3.0 | [Debian Linux details](https://wiki.debian.org/LTS) | -| [Debian 12](debian.md) | GitLab CE / GitLab EE 16.1.0 | `amd64`, `arm64` 1 | June 2028 | GitLab CE / GitLab EE 19.3.0 | [Debian Linux details](https://wiki.debian.org/LTS) | +| Debian 12 | GitLab CE / GitLab EE 16.1.0 | `amd64`, `arm64` 1 | June 2028 | GitLab CE / GitLab EE 19.3.0 | [Debian Linux details](https://wiki.debian.org/LTS) | | [openSUSE Leap 15.6](suse.md) | GitLab CE / GitLab EE 17.6.0 | `x86_64`, `aarch64` 1 | Dec 2025 | TBD | [openSUSE details](https://en.opensuse.org/Lifetime) | -| [SUSE Linux Enterprise Server 12](suse.md) | GitLab EE 9.0.0 | `x86_64` | Oct 2027 | TBD | [SUSE Linux Enterprise Server details](https://www.suse.com/lifecycle/) | -| [SUSE Linux Enterprise Server 15](suse.md) | GitLab EE 14.8.0 | `x86_64` | Dec 2024 | TBD | [SUSE Linux Enterprise Server details](https://www.suse.com/lifecycle/) | -| [Oracle Linux 8](almalinux.md) | GitLab CE / GitLab EE 12.8.1 | `x86_64` | July 2029 | GitLab CE / GitLab EE 22.2.0 | [Oracle Linux details](https://www.oracle.com/a/ocom/docs/elsp-lifetime-069338.pdf) | -| [Oracle Linux 9](almalinux.md) | GitLab CE / GitLab EE 16.2.0 | `x86_64` | June 2032 | GitLab CE / GitLab EE 25.1.0 | [Oracle Linux details](https://www.oracle.com/a/ocom/docs/elsp-lifetime-069338.pdf) | -| [Red Hat Enterprise Linux 8](almalinux.md) | GitLab CE / GitLab EE 12.8.1 | `x86_64`, `arm64` 1 | May 2029 | GitLab CE / GitLab EE 22.0.0 | [Red Hat Enterprise Linux details](https://access.redhat.com/support/policy/updates/errata/#Life_Cycle_Dates) | -| [Red Hat Enterprise Linux 9](almalinux.md) | GitLab CE / GitLab EE 16.0.0 | `x86_64`, `arm64` 1 | May 2032 | GitLab CE / GitLab EE 25.0.0 | [Red Hat Enterprise Linux details](https://access.redhat.com/support/policy/updates/errata/#Life_Cycle_Dates) | +| SUSE Linux Enterprise Server 12 | GitLab EE 9.0.0 | `x86_64` | Oct 2027 | TBD | [SUSE Linux Enterprise Server details](https://www.suse.com/lifecycle/) | +| SUSE Linux Enterprise Server 15 | GitLab EE 14.8.0 | `x86_64` | Dec 2024 | TBD | [SUSE Linux Enterprise Server details](https://www.suse.com/lifecycle/) | +| Oracle Linux 8 | GitLab CE / GitLab EE 12.8.1 | `x86_64` | July 2029 | GitLab CE / GitLab EE 22.2.0 | [Oracle Linux details](https://www.oracle.com/a/ocom/docs/elsp-lifetime-069338.pdf) | +| Oracle Linux 9 | GitLab CE / GitLab EE 16.2.0 | `x86_64` | June 2032 | GitLab CE / GitLab EE 25.1.0 | [Oracle Linux details](https://www.oracle.com/a/ocom/docs/elsp-lifetime-069338.pdf) | +| Red Hat Enterprise Linux 8 | GitLab CE / GitLab EE 12.8.1 | `x86_64`, `arm64` 1 | May 2029 | GitLab CE / GitLab EE 22.0.0 | [Red Hat Enterprise Linux details](https://access.redhat.com/support/policy/updates/errata/#Life_Cycle_Dates) | +| Red Hat Enterprise Linux 9 | GitLab CE / GitLab EE 16.0.0 | `x86_64`, `arm64` 1 | May 2032 | GitLab CE / GitLab EE 25.0.0 | [Red Hat Enterprise Linux details](https://access.redhat.com/support/policy/updates/errata/#Life_Cycle_Dates) | | [Ubuntu 20.04](ubuntu.md) | GitLab CE / GitLab EE 13.2.0 | `amd64`, `arm64` 1 | April 2025 | GitLab CE / GitLab EE 18.8.0 | [Ubuntu details](https://wiki.ubuntu.com/Releases) | -| [Ubuntu 22.04](ubuntu.md) | GitLab CE / GitLab EE 15.5.0 | `amd64`, `arm64` 1 | April 2027 | GitLab CE / GitLab EE 19.11.0 | [Ubuntu details](https://wiki.ubuntu.com/Releases) | -| [Ubuntu 24.04](ubuntu.md) | GitLab CE / GitLab EE 17.1.0 | `amd64`, `arm64` 1 | April 2029 | GitLab CE / GitLab EE 21.11.0 | [Ubuntu details](https://wiki.ubuntu.com/Releases) | +| Ubuntu 22.04 | GitLab CE / GitLab EE 15.5.0 | `amd64`, `arm64` 1 | April 2027 | GitLab CE / GitLab EE 19.11.0 | [Ubuntu details](https://wiki.ubuntu.com/Releases) | +| Ubuntu 24.04 | GitLab CE / GitLab EE 17.1.0 | `amd64`, `arm64` 1 | April 2029 | GitLab CE / GitLab EE 21.11.0 | [Ubuntu details](https://wiki.ubuntu.com/Releases) | **Footnotes**: diff --git a/doc/security/hardening_application_recommendations.md b/doc/security/hardening_application_recommendations.md index ad818b45d4e5ba67bff1405bbd4c37b1afe340e2..7437740b692a80575ecd159f3d852e1e16765190 100644 --- a/doc/security/hardening_application_recommendations.md +++ b/doc/security/hardening_application_recommendations.md @@ -52,7 +52,7 @@ Public deploy keys at are used to give read or read/write access to projects. Public deploy keys should not be used in a hardened environment. If you must use deploy keys, use project deploy keys instead. For more information, refer to the documentation on [deploy keys](../user/project/deploy_keys/_index.md) and -[project deploy keys](../user/project/deploy_keys/_index.md#create-a-project-deploy-key). +project deploy keys. ## General diff --git a/doc/security/hardening_configuration_recommendations.md b/doc/security/hardening_configuration_recommendations.md index 2d392803afb399dd12244598cc9c29ab6aecdc5e..af6d580dab318578de66e82cd66f68e1c998198d 100644 --- a/doc/security/hardening_configuration_recommendations.md +++ b/doc/security/hardening_configuration_recommendations.md @@ -137,7 +137,7 @@ nodes that only allow the other node to access those particular ports. In the [instructions for configuring an external Sidekiq](../administration/sidekiq/_index.md) there are numerous references to configuring IP ranges. You must -[configure HTTPS](../administration/sidekiq/_index.md#enable-https), +configure HTTPS, and consider restricting those IP addresses to specific systems that Sidekiq talks to. You might have to adjust firewall rules at the operating system level as well. diff --git a/doc/security/hardening_nist_800_53.md b/doc/security/hardening_nist_800_53.md index 42be0146281c0376a7e03450baa042b705df25ba..f89a1d55cf5d627837e3b2822c81d27637842b3a 100644 --- a/doc/security/hardening_nist_800_53.md +++ b/doc/security/hardening_nist_800_53.md @@ -69,7 +69,7 @@ including but not limited to: - [Coverage-guided fuzz testing](../user/application_security/coverage_fuzzing/_index.md) Beyond the CI/CD pipeline, GitLab provides [detailed guidance on how to configure releases](../user/project/releases/_index.md). -Releases can be created with a CI/CD pipeline and take a snapshot of any branch of source code in a repository. Instructions for creating releases are included in [Create a Release](../user/project/releases/_index.md#create-a-release). +Releases can be created with a CI/CD pipeline and take a snapshot of any branch of source code in a repository. Instructions for creating releases are included in Create a Release. An important consideration for NIST 800-53 or FedRAMP compliance is that released code may need to be signed to verify authenticity of code and satisfy requirements in the System and Information Integrity (SI) control family. @@ -143,7 +143,7 @@ GitLab also supports the following user types for unique use cases: Service accounts do not use a seat under the license. **Admin** area - In the **Admin** area, administrators can [export permissions](../administration/admin_area.md#user-permission-export), -[review user identities](../administration/admin_area.md#user-identities), [administer groups](../administration/admin_area.md#administering-groups), +review user identities, administer groups, and much more. Functions that can be used to meet FedRAMP / NIST 800-53 requirements: @@ -181,7 +181,7 @@ requirements: - [Set customer password length limits](password_length_limits.md). FedRAMP defers to NIST 800-63B in IA-5 for establishing password length requirements. GitLab supports 8-128 character passwords, with - 8 characters set as the default. GitLab provides [instructions for updating the minimum password length](password_length_limits.md#modify-minimum-password-length) + 8 characters set as the default. GitLab provides instructions for updating the minimum password length with the GitLab UI, which organizations interested in enforcing longer passwords can use. Additionally, GitLab Self-Managed customers may [configure complexity requirements](../administration/settings/sign_up_restrictions.md#password-complexity-requirements) @@ -192,7 +192,7 @@ requirements: time period should be logged out. FedRAMP does not specify the time period, however, clarifies that for privileged users they should be logged out at the end of the standard work period. Administrators - can establish [default session durations](../administration/settings/account_and_limit_settings.md#customize-the-default-session-duration). + can establish default session durations. - [Provisioning New Users](../user/profile/account/create_accounts.md) - Administrators can create new users for their GitLab account with the @@ -232,7 +232,7 @@ as WebAuthn, must be used (IA-2). - GitLab [provides instructions](../user/ssh.md) on how to configure SSH keys to authenticate and communicate with Git. [Commits can be signed](../user/project/repository/signed_commits/ssh.md), providing additional verification for anyone with a public key. -- Keys should be configured to meet applicable strength and complexity requirements, such as using FIPS 140-2 and FIPS 140-3 validated ciphers. Administrators can [restrict minimum key technologies and key lengths](ssh_keys_restrictions.md). Additionally, administrators can [block or ban compromised keys](ssh_keys_restrictions.md#block-banned-or-compromised-keys). +- Keys should be configured to meet applicable strength and complexity requirements, such as using FIPS 140-2 and FIPS 140-3 validated ciphers. Administrators can [restrict minimum key technologies and key lengths](ssh_keys_restrictions.md). Additionally, administrators can block or ban compromised keys. **Personal access tokens** diff --git a/doc/security/rotate_integrations_secrets.md b/doc/security/rotate_integrations_secrets.md index 63f6445707a50de517d1fb6d590f11a8353e88d4..b26ff51f5f03d05333514d4ae9b536fc3910073c 100644 --- a/doc/security/rotate_integrations_secrets.md +++ b/doc/security/rotate_integrations_secrets.md @@ -20,4 +20,4 @@ You should rotate the secrets of all third-party integrations at least yearly. An incomplete list of such secrets: - [FortiAuthenticator](../user/profile/account/two_factor_authentication.md#enable-a-one-time-password-authenticator-using-fortiauthenticator) -- [FortiToken Cloud](../user/profile/account/two_factor_authentication.md#enable-a-one-time-password-authenticator-using-fortitoken-cloud) +- FortiToken Cloud diff --git a/doc/security/tokens/_index.md b/doc/security/tokens/_index.md index 68413a3fbe89b9bad198622b50f699d2984424bf..5df2e4c217b64ab3b3972fb14e83bb80a422d132 100644 --- a/doc/security/tokens/_index.md +++ b/doc/security/tokens/_index.md @@ -37,7 +37,7 @@ Do not: review how to [use external secrets in CI/CD](../../ci/secrets/_index.md) recommendations. - Include tokens when pasting code, console commands, or log outputs into an issue, MR description, comment, or any other free text inputs. - Log credentials in the console logs or artifacts. Consider [protecting](../../ci/variables/_index.md#protect-a-cicd-variable) and - [masking](../../ci/variables/_index.md#mask-a-cicd-variable) your credentials. + masking your credentials. ### Tokens in CI/CD @@ -52,7 +52,7 @@ Additional recommendations for [CI/CD variable security](../../ci/variables/_ind - Use [secrets storage](../../ci/pipeline_security/_index.md#secrets-storage) for any credentials. - CI/CD variable containing sensitive information should be [protected](../../ci/variables/_index.md#protect-a-cicd-variable), - [masked](../../ci/variables/_index.md#mask-a-cicd-variable), and [hidden](../../ci/variables/_index.md#hide-a-cicd-variable). + masked, and hidden. ## Personal access tokens @@ -111,7 +111,7 @@ Bot users for projects are service accounts and do not count as licensed seats. You can use the [project access tokens API](../../api/project_access_tokens.md) to programmatically take -action, such as [rotating a project access token](../../api/project_access_tokens.md#rotate-a-project-access-token). +action, such as rotating a project access token. Members of a project with at least the Maintainer role [receive an email](../../user/project/settings/project_access_tokens.md#project-access-token-expiry-emails) @@ -133,7 +133,7 @@ When you create a group access token, GitLab creates a Bot users for groups are service accounts and do not count as licensed seats. You can use the [group access tokens API](../../api/group_access_tokens.md) to programmatically take -action, such as [rotating a group access token](../../api/group_access_tokens.md#rotate-a-group-access-token). +action, such as rotating a group access token. Members of a group with the Owner role [receive an email](../../user/group/settings/group_access_tokens.md#group-access-token-expiry-emails) diff --git a/doc/security/tokens/token_troubleshooting.md b/doc/security/tokens/token_troubleshooting.md index 9a6855e7fad4daee412244134e43f65804a50544..1286a5d34450681886b35d4e60525b7dfd3d22f6 100644 --- a/doc/security/tokens/token_troubleshooting.md +++ b/doc/security/tokens/token_troubleshooting.md @@ -62,7 +62,7 @@ entry: `meta.auth_fail_token_id` indicates that an access token of ID 12 was used. To find more information about this token, use the [personal access token API](../../api/personal_access_tokens.md#get-details-on-a-personal-access-token). -You can also use the API to [rotate the token](../../api/personal_access_tokens.md#rotate-a-personal-access-token). +You can also use the API to rotate the token. ### Replace expired access tokens @@ -83,9 +83,9 @@ To replace the token: - For personal access tokens, [use the UI](../../user/profile/personal_access_tokens.md#create-a-personal-access-token) or [User tokens API](../../api/user_tokens.md#create-a-personal-access-token). - For a project access token, [use the UI](../../user/project/settings/project_access_tokens.md#create-a-project-access-token) - or [project access tokens API](../../api/project_access_tokens.md#create-a-project-access-token). + or project access tokens API. - For a group access token, [use the UI](../../user/group/settings/group_access_tokens.md#create-a-group-access-token) - or [group access tokens API](../../api/group_access_tokens.md#create-a-group-access-token). + or group access tokens API. 1. Replace the old access token with the new access token. This process varies depending on how you use the token, for example if configured as a secret or embedded in an application. Requests made from this token should no longer @@ -421,7 +421,7 @@ who have not yet upgraded to GitLab version 16.0 or later, the token `expires_at value is `NULL`, and can be used to identify tokens to add an expiration date to. You can use this script in either the [Rails console](../../administration/operations/rails_console.md) -or the [Rails Runner](../../administration/operations/rails_console.md#using-the-rails-runner): +or the Rails Runner: {{< tabs >}} diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index a747bb6b2414f1ec9ecda31f40658a3dc323461d..2961fd2882776ac99e13721230c489bcc9ca2257 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -272,7 +272,7 @@ By default this feature is not available. To make it available, an administrator {{< /alert >}} You can enforce 2FA for Git over SSH operations. However, you should use -[ED25519_SK](../user/ssh.md#ed25519_sk-ssh-keys) or [ECDSA_SK](../user/ssh.md#ecdsa_sk-ssh-keys) SSH keys instead. 2FA is enforced for Git operations only, and internal commands from GitLab Shell such as `personal_access_token` are excluded. +[ED25519_SK](../user/ssh.md#ed25519_sk-ssh-keys) or ECDSA_SK SSH keys instead. 2FA is enforced for Git operations only, and internal commands from GitLab Shell such as `personal_access_token` are excluded. To perform one-time password (OTP) verification, run: diff --git a/doc/update/background_migrations.md b/doc/update/background_migrations.md index 95c8198981c10ef4b76351ea3e69da4ff63c71ae..ea90ce4db9d89593049cfa577bcc52798d04c9be 100644 --- a/doc/update/background_migrations.md +++ b/doc/update/background_migrations.md @@ -514,7 +514,7 @@ sudo -u git -H bundle exec rails runner -e production 'puts Gitlab::Database::Ba {{< /details >}} This section is only applicable if you have enabled the [Elasticsearch integration](../integration/advanced_search/elasticsearch.md). -Major releases require all [advanced search migrations](../integration/advanced_search/elasticsearch.md#advanced-search-migrations) +Major releases require all advanced search migrations to be finished from the most recent minor release in your current version before the major version upgrade. You can find pending migrations by running the following command. @@ -543,7 +543,7 @@ sudo -u git -H bundle exec rake gitlab:elastic:list_pending_migrations If you're on a long upgrade path and have many pending migrations, you might want to configure `Requeue indexing workers` and `Number of shards for non-code indexing` to speed up indexing. Another option is to ignore the pending migrations and [reindex the instance](../integration/advanced_search/elasticsearch.md#index-the-instance) after you upgrade GitLab to the target version. -You can also disable advanced search during this process with the [`Search with Elasticsearch enabled`](../integration/advanced_search/elasticsearch.md#advanced-search-configuration) setting. +You can also disable advanced search during this process with the `Search with Elasticsearch enabled` setting. {{< alert type="warning" >}} diff --git a/doc/update/background_migrations_troubleshooting.md b/doc/update/background_migrations_troubleshooting.md index 183025c52e12d6869ae93ea4d2da19d37b02ad19..5df19a525999eab2e6efca9e4192b640497b0c17 100644 --- a/doc/update/background_migrations_troubleshooting.md +++ b/doc/update/background_migrations_troubleshooting.md @@ -48,7 +48,7 @@ To roll back and follow the required upgrade path: 1. Update to either 14.0.5 or 14.1 before updating to 14.2+. 1. [Check the status](background_migrations.md#check-the-status-of-batched-background-migrations) of the batched background migrations and make sure they are all marked as finished before attempting to upgrade again. If any remain - marked as active, [manually finish them](background_migrations.md#finish-a-failed-migration-manually). + marked as active, manually finish them. ### Roll forward and finish the migrations on the upgraded version @@ -59,7 +59,7 @@ The process for rolling forward depends on whether no downtime is required or no Running all batched background migrations can take a significant amount of time depending on the size of your GitLab installation. 1. [Check the status](background_migrations.md#check-the-status-of-batched-background-migrations) of the batched background migrations in the - database, and [manually run them](background_migrations.md#finish-a-failed-migration-manually) with the appropriate + database, and manually run them with the appropriate arguments until the status query returns no rows. 1. When the status of all of all them is marked as complete, re-run migrations for your installation. 1. [Complete the database migrations](../administration/raketasks/maintenance.md#run-incomplete-database-migrations) from your GitLab upgrade: @@ -85,7 +85,7 @@ version and wait for the batched background migrations to finish. background migration from the error message, and make sure it is listed as finished. If the migration is still active, either: - Wait until it is finished. - - [Manually finish it](background_migrations.md#finish-a-failed-migration-manually). + - Manually finish it. 1. Re-run migrations for your installation so the remaining post-deployment migrations finish. ## Background migrations remain in the Sidekiq queue diff --git a/doc/update/breaking_windows.md b/doc/update/breaking_windows.md index caa44473a2d906d2ae5b3e3ffbe31bd6eaaa47f3..62ba3f422067a826e0ea004e7727cc212e674e45 100644 --- a/doc/update/breaking_windows.md +++ b/doc/update/breaking_windows.md @@ -25,11 +25,11 @@ This window takes place on April 21 - 23, 2025 from 09:00 UTC to 22:00 UTC. | Deprecation | Impact | Stage | Scope | Check potential impact | |-------------|--------|-------|-------|------------------------| | [CI/CD job token - **Authorized groups and projects** allowlist enforcement](deprecations.md#cicd-job-token---authorized-groups-and-projects-allowlist-enforcement) | High | Software supply chain security | Project | Refer to the [Understanding this change](https://gitlab.com/gitlab-org/gitlab/-/issues/383084#understanding-this-change) section for details. | -| [Deprecation of `name` field in `ProjectMonthlyUsageType` GraphQL API](deprecations.md#deprecation-of-name-field-in-projectmonthlyusagetype-graphql-api) | Low | Fulfillment | Project | | -| [Deprecation of `STORAGE` enum in `NamespaceProjectSortEnum` GraphQL API](deprecations.md#deprecation-of-storage-enum-in-namespaceprojectsortenum-graphql-api) | Low | Fulfillment | Group | | -| [DAST `dast_devtools_api_timeout` will have a lower default value](deprecations.md#dast-dast_devtools_api_timeout-will-have-a-lower-default-value) | Low | Application security testing | Project | | -| [API Discovery will use branch pipelines by default](deprecations.md#api-discovery-will-use-branch-pipelines-by-default) | Low | Application_security_testing | Project | | -| [Application Security Testing analyzers major version update](deprecations.md#application-security-testing-analyzers-major-version-update) | Low | Application security testing | Project | | +| Deprecation of `name` field in `ProjectMonthlyUsageType` GraphQL API | Low | Fulfillment | Project | | +| Deprecation of `STORAGE` enum in `NamespaceProjectSortEnum` GraphQL API | Low | Fulfillment | Group | | +| DAST `dast_devtools_api_timeout` will have a lower default value | Low | Application security testing | Project | | +| API Discovery will use branch pipelines by default | Low | Application_security_testing | Project | | +| Application Security Testing analyzers major version update | Low | Application security testing | Project | | ## Window 2 @@ -38,8 +38,8 @@ This window takes place on April 28 - 30, 2025 from 09:00 UTC to 22:00 UTC. | Deprecation | Impact | Stage | Scope | Check potential impact | |-------------|--------|-------|-------|------------------------| | [Replace `add_on_purchase` GraphQL field with `add_on_purchases`](deprecations.md#replace-add_on_purchase-graphql-field-with-add_on_purchases) | Low | Fulfillment | Instance, group | | -| [Replace namespace `add_on_purchase` GraphQL field with `add_on_purchases`](deprecations.md#replace-namespace-add_on_purchase-graphql-field-with-add_on_purchases) | Low | Fulfillment | Instance, group | | -| [Limit number of scan execution policy actions allowed per policy](deprecations.md#limit-number-of-scan-execution-policy-actions-allowed-per-policy) | Low | Security risk management | Instance, group, project | | +| Replace namespace `add_on_purchase` GraphQL field with `add_on_purchases` | Low | Fulfillment | Instance, group | | +| Limit number of scan execution policy actions allowed per policy | Low | Security risk management | Instance, group, project | | ## Window 3 @@ -48,9 +48,9 @@ This window takes place on May 5 - 7, 2025 from 09:00 UTC to 22:00 UTC. | Deprecation | Impact | Stage | Scope | Check potential impact | |-------------|--------|-------|-------|------------------------| | [CI/CD job token - **Limit access from your project** setting removal](deprecations.md#cicd-job-token---limit-access-from-your-project-setting-removal) | High | Software supply chain security | Project | Refer to the [Understanding this change](https://gitlab.com/gitlab-org/gitlab/-/issues/395708#understanding-this-change) section for details. | -| [Deprecate Terraform CI/CD templates](deprecations.md#deprecate-terraform-cicd-templates) | Medium | Deploy | Project | | -| [Deprecate license metadata format V1](deprecations.md#deprecate-license-metadata-format-v1) | Low | Secure | Instance | | -| [The `direction` GraphQL argument for `ciJobTokenScopeRemoveProject` is deprecated](deprecations.md#the-direction-graphql-argument-for-cijobtokenscoperemoveproject-is-deprecated) | Low | Govern | Project | | -| [Behavior change for Upcoming and Started milestone filters](deprecations.md#behavior-change-for-upcoming-and-started-milestone-filters) | Low | Plan | Group, project | | -| [Dependency Proxy token scope enforcement](deprecations.md#dependency-proxy-token-scope-enforcement) | High | Package | Group | | -| [Remove duoProAssignedUsersCount GraphQL field](deprecations.md#remove-duoproassigneduserscount-graphql-field) | Low | Plan | Group, project | | +| Deprecate Terraform CI/CD templates | Medium | Deploy | Project | | +| Deprecate license metadata format V1 | Low | Secure | Instance | | +| The `direction` GraphQL argument for `ciJobTokenScopeRemoveProject` is deprecated | Low | Govern | Project | | +| Behavior change for Upcoming and Started milestone filters | Low | Plan | Group, project | | +| Dependency Proxy token scope enforcement | High | Package | Group | | +| Remove duoProAssignedUsersCount GraphQL field | Low | Plan | Group, project | | diff --git a/doc/update/convert_to_ee/docker.md b/doc/update/convert_to_ee/docker.md index dfafe03f57531083f19c012e74f902756a8cf37e..7168453051c7f2da72caf71e75cd54524ff8bcff 100644 --- a/doc/update/convert_to_ee/docker.md +++ b/doc/update/convert_to_ee/docker.md @@ -13,7 +13,7 @@ You should convert from the same version of CE to EE (for example, CE 18.1 to EE However, this is not required. Any standard upgrade (for example, CE 18.0 to EE 18.1) should work. The following steps assume that you are converting to the same version. -1. Take a [backup](../../install/docker/backup.md). At minimum, back up [the database](../../install/docker/backup.md#create-a-database-backup) and +1. Take a [backup](../../install/docker/backup.md). At minimum, back up the database and the GitLab secrets file. 1. Stop the current CE container, and remove or rename it. diff --git a/doc/update/package/_index.md b/doc/update/package/_index.md index 4caae63f39dd9045a605a87efe98da3f7e6b19b6..967a8687ac7a752da077633c9014eea786cdfbd6 100644 --- a/doc/update/package/_index.md +++ b/doc/update/package/_index.md @@ -219,7 +219,7 @@ For the GitLab Community Edition, replace `gitlab-ee` with `gitlab-ce`. ## Upgrade the product documentation (optional) If you [installed the product documentation](../../administration/docs_self_host.md), -see how to [upgrade to a later version](../../administration/docs_self_host.md#upgrade-using-docker). +see how to upgrade to a later version. ## Troubleshooting diff --git a/doc/update/plan_your_upgrade.md b/doc/update/plan_your_upgrade.md index db2dc117da8d548dddff8682c80aa0199c199874..37b877f43fa5c3cfe70dc436e34f9f0d765ac09e 100644 --- a/doc/update/plan_your_upgrade.md +++ b/doc/update/plan_your_upgrade.md @@ -69,7 +69,7 @@ To restore your GitLab backup: - Before restoring, make sure to read about the [prerequisites](../administration/backup_restore/_index.md#restore-gitlab), most importantly, the versions of the backed up and the new GitLab instance must be the same. -- [Restore GitLab](../administration/backup_restore/_index.md#restore-gitlab). +- Restore GitLab. Make sure to follow the instructions based on your installation method. Confirm that the [secrets and configuration files](../administration/backup_restore/backup_gitlab.md#storing-configuration-files) are also restored. - If restoring from a snapshot, know the steps to do this. diff --git a/doc/update/upgrade.md b/doc/update/upgrade.md index 7521e2265a6443345f3c35453f4f76805ed8e2f8..9614c3c25bef7700651833d7e88b69050e262861 100644 --- a/doc/update/upgrade.md +++ b/doc/update/upgrade.md @@ -29,16 +29,16 @@ Make sure to read the whole page as it contains information related to every upg To upgrade GitLab: 1. Create an [upgrade plan](plan_your_upgrade.md) to document your upgrade steps. -1. Familiarize yourself with the [maintenance policy documentation](../policy/maintenance.md) and the [currently maintained versions](../policy/maintenance.md#maintained-versions). +1. Familiarize yourself with the [maintenance policy documentation](../policy/maintenance.md) and the currently maintained versions. 1. Read the [release posts](https://about.gitlab.com/releases/categories/releases/) for versions you're passing over. In particular, deprecations, removals, and important notes on upgrading. -1. Using the [upgrade path tool](upgrade_paths.md#upgrade-path-tool), determine what [upgrade path](upgrade_paths.md) you should take. +1. Using the [upgrade path tool](upgrade_paths.md#upgrade-path-tool), determine what upgrade path you should take. If your upgrade path includes required upgrade stops, you might have to perform multiple upgrades to move from your current version to your target version. If relevant, check [OS compatibility with the target GitLab version](../administration/package_information/supported_os.md). 1. Check for [background migrations](background_migrations.md). All migrations must finish running before each upgrade. You must spread out upgrades between major and minor releases to allow time for background migrations to finish. -1. Test your upgrade in a test environment first, and have a [rollback plan](plan_your_upgrade.md#rollback-plan) +1. Test your upgrade in a test environment first, and have a rollback plan to reduce the risk of unplanned outages and extended downtime. 1. If available in your starting version, consider [turning on maintenance mode](../administration/maintenance_mode/_index.md) during the upgrade. @@ -58,7 +58,7 @@ To upgrade GitLab: 1. If your GitLab instance has any runners associated with it, upgrade them to match the current GitLab version. This step ensures [compatibility with GitLab versions](https://docs.gitlab.com/runner/#gitlab-runner-versions). 1. If you encounter problems with the upgrade, [get support](#getting-support). -1. [Disable maintenance mode](../administration/maintenance_mode/_index.md#disable-maintenance-mode) if you had enabled +1. Disable maintenance mode if you had enabled it. 1. Unpause [running CI/CD pipelines and jobs](#cicd-pipelines-and-jobs-during-upgrades). 1. Perform [post-upgrade checks](#pre-upgrade-and-post-upgrade-checks). diff --git a/doc/update/upgrade_paths.md b/doc/update/upgrade_paths.md index 515969400b52145725cde2e96d9ecb30058f77d5..b67fa6b3c2a2e64813bc30fa3fb106d749a73fa8 100644 --- a/doc/update/upgrade_paths.md +++ b/doc/update/upgrade_paths.md @@ -31,24 +31,24 @@ To determine your upgrade path: - GitLab 15 includes the following required upgrade stops: - [`15.0.5`](versions/gitlab_15_changes.md#1500). - - [`15.1.6`](versions/gitlab_15_changes.md#1510). GitLab instances with multiple web nodes. - - [`15.4.6`](versions/gitlab_15_changes.md#1540). - - [`15.11.13`](versions/gitlab_15_changes.md#15110). + - `15.1.6`. GitLab instances with multiple web nodes. + - `15.4.6`. + - `15.11.13`. - GitLab 16 includes the following required upgrade stops: - [`16.0.10`](versions/gitlab_16_changes.md#1600). Instances with - [lots of users](versions/gitlab_16_changes.md#long-running-user-type-data-change) or - [large pipeline variables history](versions/gitlab_16_changes.md#1610). - - [`16.1.8`](versions/gitlab_16_changes.md#1610). Instances with NPM packages in their package registry. - - [`16.2.11`](versions/gitlab_16_changes.md#1620). Instances with [large pipeline variables history](versions/gitlab_16_changes.md#1630). - - [`16.3.9`](versions/gitlab_16_changes.md#1630). - - [`16.7.10`](versions/gitlab_16_changes.md#1670). + lots of users or + large pipeline variables history. + - `16.1.8`. Instances with NPM packages in their package registry. + - `16.2.11`. Instances with large pipeline variables history. + - `16.3.9`. + - `16.7.10`. - [`16.11.10`](https://gitlab.com/gitlab-org/gitlab/-/releases). - GitLab 17 includes the following required upgrade stops: - [`17.1.8`](versions/gitlab_17_changes.md#long-running-pipeline-messages-data-change). Instances with large `ci_pipeline_messages` tables. - - [`17.3.7`](versions/gitlab_17_changes.md#1730). The latest GitLab 17.3 release. - - [`17.5.z`](versions/gitlab_17_changes.md#1750). The latest GitLab 17.5 release. - - [`17.8.z`](versions/gitlab_17_changes.md#1780). The latest GitLab 17.8 release. - - [`17.11.z`](versions/gitlab_17_changes.md#17110). The latest GitLab 17.11 release. + - `17.3.7`. The latest GitLab 17.3 release. + - `17.5.z`. The latest GitLab 17.5 release. + - `17.8.z`. The latest GitLab 17.8 release. + - `17.11.z`. The latest GitLab 17.11 release. 1. Consult the version-specific upgrade instructions: - [GitLab 18 changes](versions/gitlab_18_changes.md) diff --git a/doc/update/versions/gitlab_15_changes.md b/doc/update/versions/gitlab_15_changes.md index e14bd10855a64b17bb27a73d93bedfe6d9c42498..1902d60d7f0439e6e81a8d9e346e9441ddbb4708 100644 --- a/doc/update/versions/gitlab_15_changes.md +++ b/doc/update/versions/gitlab_15_changes.md @@ -170,7 +170,7 @@ if you can't upgrade to 15.11.12 and later. If you have configured `gitlab_rails['terraform_state_enabled'] = false` in your `gitlab.rb`, check if any projects are using the Terraform state feature. To check: 1. Read the [Rails console](../../administration/operations/rails_console.md) warning. - 1. Start a [Rails console session](../../administration/operations/rails_console.md#starting-a-rails-console-session). + 1. Start a Rails console session. 1. Run the command `Terraform::State.pluck(:project_id)`. This command returns an array of all projects IDs that have a Terraform state. 1. Navigate to each project and work with stakeholders as necessary to determine if the Terraform state feature is @@ -983,7 +983,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) {{< /details >}} -- [Geo proxying](../../administration/geo/secondary_proxy/_index.md) was [enabled by default for different URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in 15.1. This may be a breaking change. If needed, you may [disable Geo proxying](../../administration/geo/secondary_proxy/_index.md#disable-secondary-site-http-proxying). If you are using SAML with different URLs, you must modify your SAML configuration and your Identity Provider configuration. For more information, see the [Geo with Single Sign-On (SSO) documentation](../../administration/geo/replication/single_sign_on.md). +- [Geo proxying](../../administration/geo/secondary_proxy/_index.md) was [enabled by default for different URLs](https://gitlab.com/gitlab-org/gitlab/-/issues/346112) in 15.1. This may be a breaking change. If needed, you may disable Geo proxying. If you are using SAML with different URLs, you must modify your SAML configuration and your Identity Provider configuration. For more information, see the [Geo with Single Sign-On (SSO) documentation](../../administration/geo/replication/single_sign_on.md). - LFS transfers can redirect to the primary from secondary site mid-session. See [the details and workaround](#lfs-transfers-redirect-to-primary-from-secondary-site-mid-session). - Incorrect object storage LFS files deletion on Geo secondary sites. See @@ -992,7 +992,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) ## 15.0.0 -- Elasticsearch 6.8 [is no longer supported](../../integration/advanced_search/elasticsearch.md#version-requirements). Before you upgrade to GitLab 15.0, [update Elasticsearch to any 7.x version](../../integration/advanced_search/elasticsearch.md#upgrade-to-a-new-elasticsearch-major-version). +- Elasticsearch 6.8 [is no longer supported](../../integration/advanced_search/elasticsearch.md#version-requirements). Before you upgrade to GitLab 15.0, update Elasticsearch to any 7.x version. - If you run GitLab with external PostgreSQL, particularly AWS RDS, ensure you upgrade PostgreSQL to patch levels to a minimum of 12.7 or 13.3 before upgrading to GitLab 14.8 or later. @@ -1009,7 +1009,7 @@ A [license caching issue](https://gitlab.com/gitlab-org/gitlab/-/issues/376706) - The use of encrypted S3 buckets with storage-specific configuration is no longer supported after [removing support for using `background_upload`](../deprecations.md#background-upload-for-object-storage). - The [certificate-based Kubernetes integration (DEPRECATED)](../../user/infrastructure/clusters/_index.md#certificate-based-kubernetes-integration-deprecated) is disabled by default, but you can be re-enable it through the [`certificate_based_clusters` feature flag](../../administration/feature_flags/_index.md#how-to-enable-and-disable-features-behind-flags) until GitLab 16.0. - When you use the GitLab Helm Chart project with a custom `serviceAccount`, ensure it has `get` and `list` permissions for the `serviceAccount` and `secret` resources. -- The `FF_GITLAB_REGISTRY_HELPER_IMAGE` [feature flag](../../administration/feature_flags/_index.md#enable-or-disable-the-feature) is removed and helper images are always pulled from GitLab Registry. +- The `FF_GITLAB_REGISTRY_HELPER_IMAGE` feature flag is removed and helper images are always pulled from GitLab Registry. ### Linux package installations diff --git a/doc/update/versions/gitlab_16_changes.md b/doc/update/versions/gitlab_16_changes.md index 3704e18ba66f29feb63d7ef221ea66ce2b490c0c..47729b5504907ae9ebcc5b3e4446c7a573d623eb 100644 --- a/doc/update/versions/gitlab_16_changes.md +++ b/doc/update/versions/gitlab_16_changes.md @@ -197,7 +197,7 @@ To workaround the problem: Linux package installations for GitLab 16.10 include an upgrade to a new major version of Patroni, from version 2.1.0 to version 3.0.1. If you're using one of the [reference architectures](../../administration/reference_architectures/_index.md) -that enables [High Availability (HA)](../../administration/reference_architectures/_index.md#high-availability-ha) +that enables High Availability (HA) (3k users or more), you're using [PostgreSQL replication and failover for Linux package installations](../../administration/postgresql/replication_and_failover.md), which uses Patroni. @@ -780,7 +780,7 @@ Specific information applies to installations using Geo: - A new method of configuring paths for the GitLab secret and custom hooks is preferred in GitLab 16.4 and later: 1. Update your configuration `[gitlab] secret_file` to [configure the path](../../administration/gitaly/reference.md) to the GitLab secret token. - 1. If you have custom hooks, update your configuration `[hooks] custom_hooks_dir` to [configure the path](../../administration/gitaly/reference.md) to + 1. If you have custom hooks, update your configuration `[hooks] custom_hooks_dir` to configure the path to server-side custom hooks. 1. Remove the `[gitlab-shell] dir` configuration. @@ -1116,10 +1116,10 @@ Workaround: A possible workaround is to [disable proxying](../../administration/ [backfill `prepared_at` values on the `merge_requests` table](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111865). This migration may take multiple days to complete on larger GitLab instances. Make sure the migration has completed successfully before upgrading to 16.1.0. -- GitLab 16.1.0 includes a [batched background migration](../background_migrations.md#batched-background-migrations) `MarkDuplicateNpmPackagesForDestruction` to mark duplicate NPM packages for destruction. Make sure the migration has completed successfully before upgrading to 16.3.0 or later. +- GitLab 16.1.0 includes a batched background migration `MarkDuplicateNpmPackagesForDestruction` to mark duplicate NPM packages for destruction. Make sure the migration has completed successfully before upgrading to 16.3.0 or later. - A `BackfillCiPipelineVariablesForBigintConversion` background migration is finalized with the `EnsureBackfillBigintIdIsCompleted` post-deploy migration. - GitLab 16.0.0 introduced a [batched background migration](../background_migrations.md#batched-background-migrations) to + GitLab 16.0.0 introduced a batched background migration to [backfill `bigint` `id` values on the `ci_pipeline_variables` table](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118878). This migration may take a long time to complete on larger GitLab instances (4 hours to process 50 million rows reported in one case). To avoid a prolonged upgrade downtime, make sure the migration has completed successfully before upgrading to 16.1. @@ -1263,7 +1263,7 @@ date set at one year from the date of upgrade. Before this automatic expiry date is applied, you should do the following to minimize disruption: 1. [Identify any access tokens without an expiration date](../../security/tokens/token_troubleshooting.md#find-tokens-with-no-expiration-date). -1. [Give those tokens an expiration date](../../security/tokens/token_troubleshooting.md#extend-token-lifetime). +1. Give those tokens an expiration date. For more information, see the: diff --git a/doc/update/versions/gitlab_17_changes.md b/doc/update/versions/gitlab_17_changes.md index e89ca0872198db3f6ab0ba62a6949587de188c42..a95ec06acbc6bc239e67d38305dfac9f33994a93 100644 --- a/doc/update/versions/gitlab_17_changes.md +++ b/doc/update/versions/gitlab_17_changes.md @@ -126,7 +126,7 @@ date set at one year from the date of upgrade. Before this automatic expiry date is applied, you should do the following to minimize disruption: 1. [Identify any access tokens without an expiration date](../../security/tokens/token_troubleshooting.md#find-tokens-with-no-expiration-date). -1. [Give those tokens an expiration date](../../security/tokens/token_troubleshooting.md#extend-token-lifetime). +1. Give those tokens an expiration date. For more information, see the: diff --git a/doc/update/zero_downtime.md b/doc/update/zero_downtime.md index 462a86289167ff61133f082e5d1e716b9d9343de..6dc42b95c8628452f6aa8fe0bc96569424929579 100644 --- a/doc/update/zero_downtime.md +++ b/doc/update/zero_downtime.md @@ -57,9 +57,9 @@ In addition to the previous, be aware of the following considerations: - [GitLab 16 changes](versions/gitlab_16_changes.md) - [GitLab 15 changes](versions/gitlab_15_changes.md) - Some releases may include [background migrations](background_migrations.md). These migrations are performed in the background by Sidekiq and are often used for migrating data. Background migrations are only added in the monthly releases. - - Certain major or minor releases may require a set of background migrations to be finished. While this doesn't require downtime (if the previous conditions are met), it's required that you [wait for background migrations to complete](background_migrations.md) between each major or minor release upgrade. + - Certain major or minor releases may require a set of background migrations to be finished. While this doesn't require downtime (if the previous conditions are met), it's required that you wait for background migrations to complete between each major or minor release upgrade. - The time necessary to complete these migrations can be reduced by increasing the number of Sidekiq workers that can process jobs in the - `background_migration` queue. To see the size of this queue, [check for background migrations before upgrading](background_migrations.md). + `background_migration` queue. To see the size of this queue, check for background migrations before upgrading. - Zero downtime upgrades can be performed for [Gitaly](#gitaly) when it's set up in its Cluster or Sharded setups due to a graceful reload mechanism. For the [Gitaly Cluster (Praefect)](#gitaly-cluster-praefect) component it can also be directly upgraded without downtime, however the GitLab Linux package does not offer HA and subsequently Zero Downtime support for it's database - A third party database solution is required to avoid downtime. - [PostgreSQL major version upgrades](../administration/postgresql/replication_and_failover.md#near-zero-downtime-upgrade-of-postgresql-in-a-patroni-cluster) are a separate process and not covered by zero-downtime upgrades (smaller upgrades are covered). - Zero-downtime upgrades are supported for the noted GitLab components you've deployed with the GitLab Linux package. If you've deployed select components through a supported third party service, such as PostgreSQL in AWS RDS or Redis in GCP Memorystore, upgrades for those services need to be performed separately as per their standard processes.