diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-27 06:08:58 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-27 06:08:58 +0300 |
commit | 53e4185a6e266ac3ebb70663e9825c84b66f0b5e (patch) | |
tree | f26610b2991bc68bf6d2c4c1f75ae95ba1d23950 | |
parent | 7ace0e99be20db28a517b9d464cb3363d26766c9 (diff) |
Add latest changes from gitlab-org/gitlab@master
36 files changed, 282 insertions, 250 deletions
diff --git a/app/controllers/projects/badges_controller.rb b/app/controllers/projects/badges_controller.rb index 855965ca6e1..f75ab5cdbf2 100644 --- a/app/controllers/projects/badges_controller.rb +++ b/app/controllers/projects/badges_controller.rb @@ -9,7 +9,7 @@ class Projects::BadgesController < Projects::ApplicationController feature_category :continuous_integration def pipeline - pipeline_status = Gitlab::Badge::Pipeline::Status + pipeline_status = Gitlab::Ci::Badge::Pipeline::Status .new(project, params[:ref], opts: { ignore_skipped: params[:ignore_skipped], key_text: params[:key_text], @@ -20,7 +20,7 @@ class Projects::BadgesController < Projects::ApplicationController end def coverage - coverage_report = Gitlab::Badge::Coverage::Report + coverage_report = Gitlab::Ci::Badge::Coverage::Report .new(project, params[:ref], opts: { job: params[:job], key_text: params[:key_text], diff --git a/app/controllers/projects/settings/ci_cd_controller.rb b/app/controllers/projects/settings/ci_cd_controller.rb index 7586c74431a..768f7123b5d 100644 --- a/app/controllers/projects/settings/ci_cd_controller.rb +++ b/app/controllers/projects/settings/ci_cd_controller.rb @@ -145,8 +145,8 @@ module Projects def define_badges_variables @ref = params[:ref] || @project.default_branch || 'master' - @badges = [Gitlab::Badge::Pipeline::Status, - Gitlab::Badge::Coverage::Report] + @badges = [Gitlab::Ci::Badge::Pipeline::Status, + Gitlab::Ci::Badge::Coverage::Report] @badges.map! do |badge| badge.new(@project, @ref).metadata diff --git a/config/feature_flags/development/optimized_timebox_queries.yml b/config/feature_flags/development/optimized_timebox_queries.yml index 215242046c5..eea0b149079 100644 --- a/config/feature_flags/development/optimized_timebox_queries.yml +++ b/config/feature_flags/development/optimized_timebox_queries.yml @@ -1,8 +1,8 @@ --- name: optimized_timebox_queries -introduced_by_url: -rollout_issue_url: -milestone: +introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/32953 +rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34043 +milestone: '13.1' type: development -group: +group: group::project management default_enabled: true diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index ba15905f500..0281516d6a2 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -1019,9 +1019,8 @@ Praefect guarantees eventual consistency by replicating all writes to secondary after the write to the primary Gitaly node has happened. Praefect can instead provide strong consistency by creating a transaction and writing -changes to all Gitaly nodes at once. Strong consistency is currently in -[alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha-beta-ga) and not enabled by -default. If enabled, transactions are only available for a subset of RPCs. For more +changes to all Gitaly nodes at once. +If enabled, transactions are only available for a subset of RPCs. For more information, see the [strong consistency epic](https://gitlab.com/groups/gitlab-org/-/epics/1189). To enable strong consistency: diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 574d8bde329..548610fc87a 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -381,7 +381,7 @@ only. For example: } ``` -## `audit_json.log` **(STARTER)** +## `audit_json.log` **(PREMIUM)** This file lives in `/var/log/gitlab/gitlab-rails/audit_json.log` for Omnibus GitLab packages or in `/home/git/gitlab/log/audit_json.log` for @@ -779,7 +779,7 @@ It's stored at: - `/var/log/gitlab/gitlab-rails/database_load_balancing.log` for Omnibus GitLab packages. - `/home/git/gitlab/log/database_load_balancing.log` for installations from source. -## `elasticsearch.log` **(STARTER ONLY)** +## `elasticsearch.log` **(PREMIUM ONLY)** > Introduced in GitLab 12.6. diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index bd8236134a9..0882e3ae001 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -96,8 +96,8 @@ The following metrics are available: | `gitlab_transaction_db_count_total` | Counter | 13.1 | Counter for total number of SQL calls | `controller`, `action` | | `gitlab_transaction_db_write_count_total` | Counter | 13.1 | Counter for total number of write SQL calls | `controller`, `action` | | `gitlab_transaction_db_cached_count_total` | Counter | 13.1 | Counter for total number of cached SQL calls | `controller`, `action` | -| `http_elasticsearch_requests_duration_seconds` **(STARTER)** | Histogram | 13.1 | Elasticsearch requests duration during web transactions | `controller`, `action` | -| `http_elasticsearch_requests_total` **(STARTER)** | Counter | 13.1 | Elasticsearch requests count during web transactions | `controller`, `action` | +| `http_elasticsearch_requests_duration_seconds` **(PREMIUM)** | Histogram | 13.1 | Elasticsearch requests duration during web transactions | `controller`, `action` | +| `http_elasticsearch_requests_total` **(PREMIUM)** | Counter | 13.1 | Elasticsearch requests count during web transactions | `controller`, `action` | | `pipelines_created_total` | Counter | 9.4 | Counter of pipelines created | | | `rack_uncaught_errors_total` | Counter | 9.4 | Rack connections handling uncaught errors count | | | `user_session_logins_total` | Counter | 9.4 | Counter of how many users have logged in since GitLab was started or restarted | | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 073ad08caf1..61280a15585 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -5,7 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# GitLab CI/CD pipeline configuration reference +<!-- markdownlint-disable MD044 --> +# Keyword reference for the .gitlab-ci.yml file +<!-- markdownlint-enable MD044 --> This document lists the configuration options for your GitLab `.gitlab-ci.yml` file. @@ -26,7 +28,7 @@ The keywords available for jobs are: |:---------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`script`](#script) | Shell script that is executed by a runner. | | [`after_script`](#after_script) | Override a set of commands that are executed after job. | -| [`allow_failure`](#allow_failure) | Allow job to fail. A failed job does not cause the pipeline to fail. | +| [`allow_failure`](#allow_failure) | Allow job to fail. A failed job does not cause the pipeline to fail. | | [`artifacts`](#artifacts) | List of files and directories to attach to a job on success. Also available: `artifacts:paths`, `artifacts:exclude`, `artifacts:expose_as`, `artifacts:name`, `artifacts:untracked`, `artifacts:when`, `artifacts:expire_in`, and `artifacts:reports`. | | [`before_script`](#before_script) | Override a set of commands that are executed before job. | | [`cache`](#cache) | List of files that should be cached between subsequent runs. Also available: `cache:paths`, `cache:key`, `cache:untracked`, `cache:when`, and `cache:policy`. | @@ -44,7 +46,7 @@ The keywords available for jobs are: | [`release`](#release) | Instructs the runner to generate a [Release](../../user/project/releases/index.md) object. | | [`resource_group`](#resource_group) | Limit job concurrency. | | [`retry`](#retry) | When and how many times a job can be auto-retried in case of a failure. | -| [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. May not be used alongside `only`/`except`. | +| [`rules`](#rules) | List of conditions to evaluate and determine selected attributes of a job, and whether or not it's created. | | [`services`](#services) | Use Docker services images. Also available: `services:name`, `services:alias`, `services:entrypoint`, and `services:command`. | | [`stage`](#stage) | Defines a job stage (default: `test`). | | [`tags`](#tags) | List of tags that are used to select a runner. | @@ -55,8 +57,8 @@ The keywords available for jobs are: ### Unavailable names for jobs -Each job must have a unique name, but there are a few **reserved `keywords` that -can't be used as job names**: +Each job must have a unique name, but there are a few reserved `keywords` that +can't be used as job names: - `image` - `services` @@ -223,7 +225,7 @@ stages: If any job fails, the pipeline is marked as `failed` and jobs in later stages do not start. Jobs in the current stage are not stopped and continue to run. -If no `stages` are defined in `.gitlab-ci.yml`, then `build`, `test` and `deploy` +If no `stages` are defined in the `.gitlab-ci.yml` file, then `build`, `test` and `deploy` are the default pipeline stages. If a job does not specify a [`stage`](#stage), the job is assigned the `test` stage. @@ -342,7 +344,7 @@ include: > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4. Use the `include` keyword to include external YAML files in your CI/CD configuration. -You can break down one long `gitlab-ci.yml` into multiple files to increase readability, +You can break down one long `gitlab-ci.yml` file into multiple files to increase readability, or reduce duplication of the same configuration in multiple places. You can also store template files in a central repository and `include` them in projects. @@ -363,19 +365,19 @@ use the [`extends` keyword](#extends). | [`remote`](#includeremote) | Include a file from a remote URL. Must be publicly accessible. | | [`template`](#includetemplate) | Include templates that are provided by GitLab. | -`.gitlab-ci.yml` configuration included by all methods is evaluated at pipeline creation. +The `.gitlab-ci.yml` file configuration included by all methods is evaluated when the pipeline is created. The configuration is a snapshot in time and persisted in the database. Any changes to -referenced `.gitlab-ci.yml` configuration is not reflected in GitLab until the next pipeline is created. +the referenced `.gitlab-ci.yml` file configuration is not reflected in GitLab until the next pipeline is created. The files defined by `include` are: -- Deep merged with those in `.gitlab-ci.yml`. -- Always evaluated first and merged with the content of `.gitlab-ci.yml`, +- Deep merged with those in the `.gitlab-ci.yml` file. +- Always evaluated first and merged with the content of the `.gitlab-ci.yml` file, regardless of the position of the `include` keyword. NOTE: Use merging to customize and override included CI/CD configurations with local -configurations. Local configurations in `.gitlab-ci.yml` override included configurations. +configurations. Local configurations in the `.gitlab-ci.yml` file override included configurations. #### Variables with `include` **(CORE ONLY)** @@ -383,7 +385,7 @@ configurations. Local configurations in `.gitlab-ci.yml` override included confi > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/294294) in GitLab 13.9. You can [use some predefined variables in `include` sections](../variables/where_variables_can_be_used.md#gitlab-ciyml-file) -in your `.gitlab-ci.yml`: +in your `.gitlab-ci.yml` file: ```yaml include: @@ -396,12 +398,11 @@ see the following [CI variable demo](https://youtu.be/4XR8gw3Pkos). #### `include:local` -`include:local` includes a file from the same repository as `.gitlab-ci.yml`. +`include:local` includes a file that is in the same repository as the `.gitlab-ci.yml` file. It's referenced with full paths relative to the root directory (`/`). -You can only use files that are tracked by Git on the same branch -your configuration file is on. If you `include:local`, make -sure that both `.gitlab-ci.yml` and the local file are on the same branch. +If you use `include:local`, make sure that both the `.gitlab-ci.yml` file and the local file +are on the same branch. You can't include local files through Git submodules paths. @@ -415,14 +416,14 @@ include: - local: '/templates/.gitlab-ci-template.yml' ``` -Local includes can be used as a replacement for symbolic links that are not followed. - This can be defined as a short local include: ```yaml include: '.gitlab-ci-production.yml' ``` +Use local includes instead of symbolic links. + #### `include:file` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7. @@ -476,7 +477,7 @@ include: #### `include:remote` -`include:remote` can be used to include a file from a different location, +Use `include:remote` to include a file from a different location, using HTTP/HTTPS, referenced by the full URL. The remote file must be publicly accessible by a GET request, because authentication schemas in the remote URL are not supported. For example: @@ -493,7 +494,7 @@ so you can only `include` public projects or templates. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53445) in GitLab 11.7. -`include:template` can be used to include `.gitlab-ci.yml` templates that are +Use `include:template` to include `.gitlab-ci.yml` templates that are [shipped with GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/lib/gitlab/ci/templates). For example: @@ -652,7 +653,7 @@ job: #### `before_script` -`before_script` is used to define an array of commands that should run before each job, +Use `before_script` to define an array of commands that should run before each job, but after [artifacts](#artifacts) are restored. Scripts specified in `before_script` are concatenated with any scripts specified @@ -680,7 +681,7 @@ You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts). #### `after_script` -`after_script` is used to define an array of commands that run after each job, +Use `after_script` to define an array of commands that run after each job, including failed jobs. If a job times out or is cancelled, the `after_script` commands are not executed. @@ -786,7 +787,7 @@ User-defined stages are executed after `.pre` and before `.post`. A pipeline is not created if all jobs are in `.pre` or `.post` stages. -The order of `.pre` and `.post` can't be changed, even if defined out of order in `.gitlab-ci.yml`. +The order of `.pre` and `.post` can't be changed, even if defined out of order in the `.gitlab-ci.yml` file. For example, the following are equivalent configuration: - Configured in order: @@ -954,12 +955,10 @@ rspec: Note that in the example above: -- `variables` sections have been merged but that `URL: "http://my-url.internal"` -has been overwritten by `URL: "http://docker-url.internal"`. -- `tags: ['production']` has been overwritten by `tags: ['docker']`. -- `script` has not been merged but rather `script: ['echo "Hello world!"']` has - been overwritten by `script: ['rake rspec']`. Arrays can be - merged using [YAML anchors](#anchors). +- The `variables` sections merge, but `URL: "http://docker-url.internal"` overwrites `URL: "http://my-url.internal"`. +- `tags: ['docker']` overwrites `tags: ['production']`. +- `script` does not merge, but `script: ['rake rspec']` overwrites + `script: ['echo "Hello world!"']`. You can use [YAML anchors](#anchors) to merge arrays. #### Using `extends` and `include` together @@ -973,7 +972,7 @@ For example, if you have a local `included.yml` file: - echo Hello! ``` -Then, in `.gitlab-ci.yml`: +Then, in the `.gitlab-ci.yml` file: ```yaml include: included.yml @@ -990,15 +989,15 @@ the `.template` job, and uses the `alpine` Docker image as defined in the local > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3. -The `rules` keyword can be used to include or exclude jobs in pipelines. +Use the `rules` keyword to include or exclude jobs in pipelines. Rules are evaluated *in order* until the first match. When matched, the job is either included or excluded from the pipeline, depending on the configuration. If included, the job also has [certain attributes](#rules-attributes) added to it. -`rules` replaces [`only/except`](#onlyexcept-basic) and can't be used in conjunction with it. -If you attempt to use both keywords in the same job, the linter returns a +`rules` replaces [`only/except`](#onlyexcept-basic) and they can't be used together +in the same job. If you configure one job to use both keywords, the linter returns a `key may not be used with rules` error. #### Rules attributes @@ -1375,7 +1374,7 @@ docker build: - $DOCKERFILES_DIR/* ``` -The `$` character can be used for both variables and paths. For example, if the +You can use The `$` character for both variables and paths. For example, if the `$DOCKERFILES_DIR` variable exists, its value is used. If it does not exist, the `$` is interpreted as being part of a path. @@ -1605,7 +1604,7 @@ job: - schedules ``` -The repository path can be used to have jobs executed only for the parent +Use the repository path to have jobs executed only for the parent repository and not forks: ```yaml @@ -1623,17 +1622,13 @@ except `master` and those with names prefixed with `release/`. If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by default. If it does not have an `except` rule, it's empty. -For example, +For example, `job1` and `job2` are essentially the same: ```yaml -job: +job1: script: echo 'test' -``` -is translated to: - -```yaml -job: +job2: script: echo 'test' only: ['branches', 'tags'] ``` @@ -1703,7 +1698,7 @@ the pipeline if the following is true: In the example below, the `test` job is `only` created when **all** of the following are true: -- The pipeline has been [scheduled](../pipelines/schedules.md) **or** runs for `master`. +- The pipeline is [scheduled](../pipelines/schedules.md) **or** runs for `master`. - The `variables` keyword matches. - The `kubernetes` service is active on the project. @@ -2319,10 +2314,10 @@ test_job_2: ### `when` -`when` is used to implement jobs that are run in case of failure or despite the +Use `when` to implement jobs that run in case of failure or despite the failure. -`when` can be set to one of the following values: +The valid values of `when` are: 1. `on_success` (default) - Execute job only when all jobs in earlier stages succeed, or are considered successful because they have `allow_failure: true`. @@ -2469,13 +2464,13 @@ provided. `start_in` must be less than or equal to one week. Examples of valid v - `1 day` - `1 week` -When there is a delayed job in a stage, the pipeline doesn't progress until the delayed job has finished. -This keyword can also be used for inserting delays between different stages. +When a stage includes a delayed job, the pipeline doesn't progress until the delayed job finishes. +You can use this keyword to insert delays between different stages. -The timer of a delayed job starts immediately after the previous stage has completed. -Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passed. +The timer of a delayed job starts immediately after the previous stage completes. +Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passes. -The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed: +The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage completes: ```yaml timed rollout 10%: @@ -2485,7 +2480,7 @@ timed rollout 10%: start_in: 30 minutes ``` -You can stop the active timer of a delayed job by clicking the **{time-out}** (**Unschedule**) button. +To stop the active timer of a delayed job, click the **{time-out}** (**Unschedule**) button. This job can no longer be scheduled to run automatically. You can, however, execute the job manually. To start a delayed job immediately, click the **Play** button. @@ -2511,8 +2506,8 @@ deployment to the `production` environment. #### `environment:name` -The `environment: name` keyword can use any of the defined CI variables, -including predefined, secure, or `.gitlab-ci.yml` [`variables`](#variables). +The `environment: name` keyword can use any of the defined CI/CD [variables](#variables), +including predefined, secure, or variables defined in the `.gitlab-ci.yml` file. You can't use variables defined in a `script` section. @@ -2545,8 +2540,8 @@ deploy to production: #### `environment:url` -The `url` keyword can use any of the defined CI variables, -including predefined, secure, or `.gitlab-ci.yml` [`variables`](#variables). +The `environment:url` keyword can use any of the defined CI/CD [variables](#variables), +including predefined, secure, or variables defined in the `.gitlab-ci.yml` file. You can't use variables defined in a `script` section. @@ -2582,7 +2577,7 @@ Read the `environment:action` section for an example. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22191) in GitLab 8.13. -The `action` keyword can be used to specify jobs that prepare, start, or stop environments. +Use the `action` keyword to specify jobs that prepare, start, or stop environments. | **Value** | **Description** | |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -2668,7 +2663,7 @@ For more information, see > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. -The `kubernetes` block is used to configure deployments to a +Use the `kubernetes` keyword to configure deployments to a [Kubernetes cluster](../../user/project/clusters/index.md) that is associated with your project. For example: @@ -2724,10 +2719,10 @@ as Review Apps. You can see an example that uses Review Apps at ### `cache` -`cache` is used to specify a list of files and directories that should be -cached between jobs. You can only use paths that are in the local working copy. +Use the `cache` keyword to specify a list of files and directories to +cache between jobs. You can only use paths that are in the local working copy. -If `cache` is defined outside the scope of jobs, it means it's set +If `cache` is defined outside the scope of jobs, it's set globally and all jobs use that configuration. Caching is shared between pipelines and jobs. Caches are restored before [artifacts](#artifacts). @@ -2739,7 +2734,7 @@ Read how caching works and find out some good practices in the Use the `paths` directive to choose which files or directories to cache. Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly link outside it. -Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming)) +You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and: - In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, @@ -2850,7 +2845,7 @@ runs. When you include `cache:key:files`, you must also list the project files that are used to generate the key, up to a maximum of two files. The cache `key` is a SHA checksum computed from the most recent commits (up to two, if two files are listed) -that changed the given files. If neither file was changed in any commits, +that changed the given files. If neither file is changed in any commits, the fallback key is `default`. ```yaml @@ -2877,7 +2872,7 @@ use the new cache, instead of rebuilding the dependencies. When you want to combine a prefix with the SHA computed for `cache:key:files`, use the `prefix` keyword with `key:files`. For example, if you add a `prefix` of `test`, the resulting key is: `test-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5`. -If neither file was changed in any commits, the prefix is added to `default`, so the +If neither file is changed in any commits, the prefix is added to `default`, so the key in the example would be `test-default`. Like `cache:key`, `prefix` can use any of the [predefined variables](../variables/README.md), @@ -2989,8 +2984,8 @@ rspec: - bundle exec rspec ... ``` -The `pull` policy speeds up job execution and reduces load on the cache server. It -can be used when you have many jobs that use caches executing in parallel. +Use the `pull` policy when you have many jobs executing in parallel that use caches. This +policy speeds up job execution and reduces load on the cache server. If you have a job that unconditionally recreates the cache without referring to its previous contents, you can skip the download step. @@ -2998,7 +2993,7 @@ To do so, add `policy: push` to the job. ### `artifacts` -`artifacts` is used to specify a list of files and directories that are +Use the `artifacts` keyword to specify a list of files and directories that are attached to the job when it [succeeds, fails, or always](#artifactswhen). The artifacts are sent to GitLab after the job finishes. They are @@ -3013,7 +3008,7 @@ artifacts are restored after [caches](#cache). #### `artifacts:paths` Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't directly -link outside it. Wildcards can be used that follow the [glob](https://en.wikipedia.org/wiki/Glob_(programming)) +link outside it. You can use Wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and: - In [GitLab Runner 13.0](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2620) and later, @@ -3079,7 +3074,7 @@ job: > - It's enabled on GitLab.com. > - It's recommended for production use. -`artifacts:public` is used to determine whether the job artifacts should be +Use `artifacts:public` to determine whether the job artifacts should be publicly available. The default for `artifacts:public` is `true` which means that the artifacts in @@ -3107,9 +3102,9 @@ artifacts: archive. Similar to [`artifacts:paths`](#artifactspaths), `exclude` paths are relative -to the project directory. Wildcards can be used that follow the -[glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns and -[`filepath.Match`](https://golang.org/pkg/path/filepath/#Match). +to the project directory. You can use Wildcards that use +[glob](https://en.wikipedia.org/wiki/Glob_(programming)) or +[`filepath.Match`](https://golang.org/pkg/path/filepath/#Match) patterns. For example, to store all files in `binaries/`, but not `*.o` files located in subdirectories of `binaries/`: @@ -3129,7 +3124,7 @@ Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded us > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15018) in GitLab 12.5. -The `expose_as` keyword can be used to expose [job artifacts](../pipelines/job_artifacts.md) +Use the `expose_as` keyword to expose [job artifacts](../pipelines/job_artifacts.md) in the [merge request](../../user/project/merge_requests/index.md) UI. For example, to match a single file: @@ -3246,8 +3241,8 @@ job: #### `artifacts:untracked` -`artifacts:untracked` is used to add all Git untracked files as artifacts (along -to the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration +Use `artifacts:untracked` to add all Git untracked files as artifacts (along +with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores configuration in the repository's `.gitignore` file. Send all Git untracked files: @@ -3277,7 +3272,7 @@ artifacts: #### `artifacts:when` -`artifacts:when` is used to upload artifacts on job failure or despite the +Use `artifacts:when` to upload artifacts on job failure or despite the failure. `artifacts:when` can be set to one of the following values: @@ -3341,8 +3336,8 @@ in GitLab 13.4. In [GitLab 13.8 and later](https://gitlab.com/gitlab-org/gitlab/ #### `artifacts:reports` -The [`artifacts:reports` keyword](../pipelines/job_artifacts.md#artifactsreports) -is used for collecting test reports, code quality reports, and security reports from jobs. +Use [`artifacts:reports`](../pipelines/job_artifacts.md#artifactsreports) +to collect test reports, code quality reports, and security reports from jobs. It also exposes these reports in the GitLab UI (merge requests, pipeline views, and security dashboards). These are the available report types: @@ -3379,7 +3374,7 @@ An error occurs if you define jobs from the current or an upcoming stage. To prevent a job from downloading artifacts, define an empty array. When you use `dependencies`, the status of the previous job is not considered. -If a job fails or it's a manual job that was not run, no error occurs. +If a job fails or it's a manual job that isn't triggered, no error occurs. The following example defines two jobs with artifacts: `build:osx` and `build:linux`. When the `test:osx` is executed, the artifacts from `build:osx` @@ -3425,7 +3420,7 @@ deploy: > Introduced in GitLab 10.3. -If the artifacts of the job that is set as a dependency have been +If the artifacts of the job that is set as a dependency are [expired](#artifactsexpire_in) or [erased](../pipelines/job_artifacts.md#erasing-artifacts), then the dependent job fails. @@ -3530,15 +3525,15 @@ Possible values for `when` are: - `script_failure`: Retry when the script failed. - `api_failure`: Retry on API failure. - `stuck_or_timeout_failure`: Retry when the job got stuck or timed out. -- `runner_system_failure`: Retry if there was a runner system failure (for example, job setup failed). -- `missing_dependency_failure`: Retry if a dependency was missing. -- `runner_unsupported`: Retry if the runner was unsupported. +- `runner_system_failure`: Retry if there is a runner system failure (for example, job setup failed). +- `missing_dependency_failure`: Retry if a dependency is missing. +- `runner_unsupported`: Retry if the runner is unsupported. - `stale_schedule`: Retry if a delayed job could not be executed. - `job_execution_timeout`: Retry if the script exceeded the maximum execution time set for the job. - `archived_failure`: Retry if the job is archived and can't be run. - `unmet_prerequisites`: Retry if the job failed to complete prerequisite tasks. - `scheduler_failure`: Retry if the scheduler failed to assign the job to a runner. -- `data_integrity_failure`: Retry if there was a structural integrity problem detected. +- `data_integrity_failure`: Retry if there is a structural integrity problem detected. You can specify the number of [retry attempts for certain stages of job execution](../runners/README.md#job-stages-attempts) using variables. @@ -3753,7 +3748,7 @@ upstream_bridge: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16094) in GitLab 12.7. To create a [child pipeline](../parent_child_pipelines.md), specify the path to the -YAML file containing the CI config of the child pipeline: +YAML file that contains the configuration of the child pipeline: ```yaml trigger_job: @@ -3847,7 +3842,7 @@ The trigger token is different than the [`trigger`](#trigger) keyword. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32022) in GitLab 12.3. -`interruptible` is used to indicate that a running job should be canceled if made redundant by a newer pipeline run. +Use `interruptible` to indicate that a running job should be canceled if made redundant by a newer pipeline run. Defaults to `false` (uninterruptible). Jobs that have not started yet (pending) are considered interruptible and safe to be cancelled. This value is used only if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines) @@ -3900,11 +3895,11 @@ When an uninterruptible job is running, the pipeline cannot be canceled, regardl Sometimes running multiple jobs or pipelines at the same time in an environment can lead to errors during the deployment. -To avoid these errors, the `resource_group` attribute can be used to ensure that +To avoid these errors, use the `resource_group` attribute to make sure that the runner doesn't run certain jobs simultaneously. Resource groups behave similar to semaphores in other programming languages. -When the `resource_group` keyword is defined for a job in `.gitlab-ci.yml`, +When the `resource_group` keyword is defined for a job in the `.gitlab-ci.yml` file, job executions are mutually exclusive across different pipelines for the same project. If multiple jobs belonging to the same resource group are enqueued simultaneously, only one of the jobs is picked by the runner. The other jobs wait until the @@ -3959,7 +3954,7 @@ image: registry.gitlab.com/gitlab-org/release-cli:latest #### Script All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release` -job can use the output from script commands, but a placeholder script can be used if +job can use the output from script commands, but you can use a placeholder script if the script is not needed: ```yaml @@ -4031,7 +4026,7 @@ description. You can specify a file in `$CI_PROJECT_DIR` that contains the description. The file must be relative to the project directory (`$CI_PROJECT_DIR`), and if the file is a symbolic link it can't reside -outside of `$CI_PROJECT_DIR`. The `./path/to/file` and file name can't contain spaces. +outside of `$CI_PROJECT_DIR`. The `./path/to/file` and filename can't contain spaces. ```yaml job: @@ -4062,7 +4057,7 @@ released_at: '2021-03-15T08:00:00Z' Combining the individual examples given above for `release` results in the following code snippets. There are two options, depending on how you generate the -tags. These options cannot be used together, so choose one: +tags. You can't use these options together, so choose one: - To create a release when you push a Git tag, or when you add a Git tag in the UI by going to **Repository > Tags**: @@ -4202,8 +4197,8 @@ job: ### `pages` -`pages` is a special job that is used to upload static content to GitLab that -can be used to serve your website. It has a special syntax, so the two +`pages` is a special job that uploads static content to GitLab that +is then published as a website. It has a special syntax, so the two requirements below must be met: - Any static content must be placed under a `public/` directory. @@ -4273,7 +4268,7 @@ meaning it applies to all jobs. If you define a variable in a job, it's availabl to that job only. If a variable of the same name is defined globally and for a specific job, the -[job-specific variable is used](../variables/README.md#priority-of-environment-variables). +[job-specific variable overrides the global variable](../variables/README.md#priority-of-environment-variables). All YAML-defined variables are also set to any linked [Docker service containers](../docker/using_docker_images.md#what-is-a-service). @@ -4299,13 +4294,14 @@ You can also use variables to configure how many times a runner It's possible to use special YAML features like anchors (`&`), aliases (`*`) and map merging (`<<`). Use these features to reduce the complexity -of `.gitlab-ci.yml`. +of the code in the `.gitlab-ci.yml` file. Read more about the various [YAML features](https://learnxinyminutes.com/docs/yaml/). In most cases, the [`extends` keyword](#extends) is more user friendly and should -be used over these special YAML features. YAML anchors may still -need to be used to merge arrays. +be used over these special YAML features. + +You can use YAML anchors to merge YAML arrays. ### Anchors @@ -4441,7 +4437,7 @@ test:mysql: ``` You can see that the hidden jobs are conveniently used as templates, and -`tags: [dev]` has been overwritten by `tags: [postgres]`. +`tags: [postgres]` overwrites `tags: [dev]`. #### YAML anchors for scripts @@ -4480,8 +4476,8 @@ job2: #### YAML anchors for variables -[YAML anchors](#anchors) can be used with `variables`, to repeat assignment -of variables across multiple jobs. Use can also use YAML anchors when a job +Use [YAML anchors](#anchors) with `variables` to repeat assignment +of variables across multiple jobs. You can also use YAML anchors when a job requires a specific `variables` block that would otherwise override the global variables. In the example below, we override the `GIT_STRATEGY` variable without affecting diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index 7617f63b715..fe364cef189 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_rules.md @@ -44,8 +44,8 @@ erDiagram ### `Project` and `MergeRequest` `Project` and `MergeRequest` models are defined in `ee/app/models/ee/project.rb` -and `ee/app/models/ee/merge_request.rb`. They extend the non-EE versions since -approval rules is an EE only feature. Associations and other related stuff to +and `ee/app/models/ee/merge_request.rb`. They extend the non-EE versions, because +approval rules are an EE-only feature. Associations and other related stuff to merge request approvals are defined here. ### `ApprovalState` @@ -265,8 +265,8 @@ graph LR ApprovalWrappedRule --> Approval ``` -This flow gets initiated by the frontend component. The data returned will -then be used to display information on the MR widget. +This flow gets initiated by the frontend component. The data returned is +used to display information on the MR widget. ### Approving a merge request @@ -282,5 +282,5 @@ is executed instead. ## TODO -1. Add information related to other rule types (e.g. `code_owner` and `report_approver`). +1. Add information related to other rule types, such as `code_owner` and `report_approver`. 1. Add information about side effects of approving/unapproving merge request. diff --git a/doc/development/fe_guide/editor_lite.md b/doc/development/fe_guide/editor_lite.md index 3655f86c07c..b27aef788b1 100644 --- a/doc/development/fe_guide/editor_lite.md +++ b/doc/development/fe_guide/editor_lite.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Background -**Editor Lite** is a technological product driving [Web Editor](../../user/project/repository/web_editor.md), [Snippets](../../user/snippets.md), [CI Linter](../../ci/lint.md), etc. Editor Lite is the driving technology for any single-file editing experience across the product. +**Editor Lite** is a technological product driving features like [Web Editor](../../user/project/repository/web_editor.md), [Snippets](../../user/snippets.md), and [CI Linter](../../ci/lint.md). Editor Lite is the driving technology for any single-file editing experience across the product. Editor Lite is a thin wrapper around [the Monaco editor](https://microsoft.github.io/monaco-editor/index.html) that provides the necessary helpers and abstractions and extends Monaco using extensions. diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index e21257bc9e8..98649f08dea 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -12,9 +12,10 @@ Workhorse and GitLab Shell. ## Deep Dive -In May 2019, Bob Van Landuyt hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) -on the [Gitaly project](https://gitlab.com/gitlab-org/gitaly) and how to contribute to it as a -Ruby developer, to share his domain specific knowledge with anyone who may work in this part of the +In May 2019, <!-- vale gitlab.Spelling = NO --> Bob Van Landuyt <!-- vale gitlab.Spelling = YES --> +hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) +on the [Gitaly project](https://gitlab.com/gitlab-org/gitaly). It included how to contribute to it as a +Ruby developer, and shared domain-specific knowledge with anyone who may work in this part of the codebase in the future. You can find the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [recording on YouTube](https://www.youtube.com/watch?v=BmlEWFS8ORo), and the slides @@ -22,7 +23,7 @@ on [Google Slides](https://docs.google.com/presentation/d/1VgRbiYih9ODhcPnL8dS0W and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/a4fdb1026278bda5c1c5bb574379cf80/Create_Deep_Dive__Gitaly_for_Create_Ruby_Devs.pdf). Everything covered in this deep dive was accurate as of GitLab 11.11, and while specific details may -have changed since then, it should still serve as a good introduction. +have changed, it should still serve as a good introduction. ## Beginner's guide @@ -43,7 +44,7 @@ needs direct access to the Git repository *must* be implemented in Gitaly, and exposed via an RPC. It's often easier to develop a new feature in Gitaly if you make the changes to -GitLab that will use the new feature in a separate merge request, to be merged +GitLab that intends to use the new feature in a separate merge request, to be merged immediately after the Gitaly one. This allows you to test your changes before they are merged. @@ -107,9 +108,9 @@ bundle exec rake gitlab:features:disable_rugged Most of this code exists in the `lib/gitlab/git/rugged_impl` directory. 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 does +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 does NOT work on GitLab.com or other GitLab instances that do not use NFS. ## `TooManyInvocationsError` errors @@ -129,7 +130,7 @@ Isolate the source of the n+1 problem. This is normally a loop that results in G 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. -Once the source has been found, wrap it in an `allow_n_plus_1_calls` block, as follows: +After the source has been found, wrap it in an `allow_n_plus_1_calls` block, as follows: ```ruby # n+1: link to n+1 issue @@ -139,7 +140,7 @@ Gitlab::GitalyClient.allow_n_plus_1_calls do end ``` -Once the code is wrapped in this block, this code path is excluded from n+1 detection. +After the code is wrapped in this block, this code path is excluded from n+1 detection. ## Request counts @@ -164,13 +165,13 @@ end Normally, GitLab CE/EE tests use a local clone of Gitaly in `tmp/tests/gitaly` pinned at the version specified in `GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports also -branches and SHA to use a custom commit in <https://gitlab.com/gitlab-org/gitaly>. +branches and SHA to use a custom commit in [the repository](https://gitlab.com/gitlab-org/gitaly). 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 evaluates the file content as a Git -reference (branch or SHA). Only if it matches a semver does it prepend a `v`. +reference (branch or SHA). Only if it matches a semantic version 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 @@ -195,7 +196,7 @@ 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 section. -To use a different Gitaly repository, e.g., if your changes are present +To use a different Gitaly repository, such as if your changes are present on a fork, you can specify a `GITALY_REPO_URL` environment variable when running tests: @@ -218,7 +219,7 @@ as a [CI environment variable](../ci/variables/README.md#gitlab-cicd-environment If you are making changes to the RPC client, such as adding a new endpoint or adding a new parameter to an existing endpoint, follow the guide for -[Gitaly proto](https://gitlab.com/gitlab-org/gitaly/blob/master/proto/README.md). After pushing +[Gitaly protobuf specifications](https://gitlab.com/gitlab-org/gitaly/blob/master/proto/README.md). After pushing the branch with the changes (`new-feature-branch`, for example): 1. Change the `gitaly` line in the Rails' `Gemfile` to: @@ -328,15 +329,15 @@ the integration by using GDK: 1. Uncomment `prometheus_listen_addr` in the configuration file and run `gdk restart gitaly`. 1. Make sure that the flag is not enabled yet: - 1. Perform whatever action is required to trigger your changes (project creation, - submitting commit, observing history, etc.). + 1. Perform whatever action is required to trigger your changes, such as project creation, + submitting commit, or observing history. 1. Check that the list of current metrics has the new counter for the feature flag: ```shell curl --silent "http://localhost:9236/metrics" | grep go_find_all_tags ``` -1. Once you observe the metrics for the new feature flag and it increments, you +1. After you observe the metrics for the new feature flag and it increments, you can enable the new feature: 1. Navigate to GDK's root directory. 1. Start a Rails console: @@ -359,7 +360,7 @@ the integration by using GDK: ``` 1. Exit the Rails console and perform whatever action is required to trigger - your changes (project creation, submitting commit, observing history, etc.). + your changes, such as project creation, submitting commit, or observing history. 1. Verify the feature is on by observing the metrics for it: ```shell diff --git a/doc/development/integrations/jenkins.md b/doc/development/integrations/jenkins.md index a9a1026f1a8..16aba023fab 100644 --- a/doc/development/integrations/jenkins.md +++ b/doc/development/integrations/jenkins.md @@ -21,7 +21,7 @@ brew services start jenkins GitLab does not allow requests to localhost or the local network by default. When running Jenkins on your local machine, you need to enable local access. -1. Log into your GitLab instance as an admin. +1. Log into your GitLab instance as an administrator. 1. Go to **Admin Area > Settings > Network**. 1. Expand **Outbound requests** and check the following checkboxes: @@ -32,7 +32,7 @@ GitLab does not allow requests to localhost or the local network by default. Whe Jenkins uses the GitLab API and needs an access token. -1. Log in to your GitLab instance. +1. Sign in to your GitLab instance. 1. Click on your profile picture, then click **Settings**. 1. Click **Access Tokens**. 1. Create a new Access Token with the **API** scope enabled. Note the value of the token. diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index 48beb526774..bfe523ee390 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -19,10 +19,12 @@ The following are required to install and test the app: - [GDK with Gitpod](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/gitpod.md) documentation. - You **must not** use tunneling tools such as Serveo or `ngrok`. These are + You **must not** use tunneling tools such as + <!-- vale gitlab.Spelling = NO --> Serveo <!-- vale gitlab.Spelling = YES --> + or `ngrok`. These are security risks, and must not be run on developer laptops. - Jira requires all connections to the app host to be over SSL, so if you set up + Jira requires all connections to the app host to be over SSL. If you set up your own environment, remember to enable SSL and an appropriate certificate. ## Install the app in Jira diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index 1d5b7f8e0bd..f89c92c32b0 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -51,7 +51,7 @@ POST /internal/allowed | `key_id` | string | no | ID of the SSH-key used to connect to GitLab Shell | | `username` | string | no | Username from the certificate used to connect to GitLab Shell | | `project` | string | no (if `gl_repository` is passed) | Path to the project | -| `gl_repository` | string | no (if `project` is passed) | Repository identifier (e.g. `project-7`) | +| `gl_repository` | string | no (if `project` is passed) | Repository identifier, such as `project-7` | | `protocol` | string | yes | SSH when called from GitLab Shell, HTTP or SSH when called from Gitaly | | `action` | string | yes | Git command being run (`git-upload-pack`, `git-receive-pack`, `git-upload-archive`) | | `changes` | string | yes | `<oldrev> <newrev> <refname>` when called from Gitaly, the magic string `_any` when called from GitLab Shell | @@ -413,7 +413,7 @@ connection for the requested project. GitLab `kas` uses this to configure the agent to fetch Kubernetes resources from the project repository to sync. -Only public projects are currently supported. For private projects, the ability for the +Only public projects are supported. For private projects, the ability for the agent to be authorized is [not yet implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). | Attribute | Type | Required | Description | @@ -456,7 +456,7 @@ Cluster. | Attribute | Type | Required | Description | |:----------|:-------|:---------|:------------| -| `alert` | Hash | yes | Alerts detail. Currently same format as [3rd party alert](../operations/incident_management/alert_integrations.md#customize-the-alert-payload-outside-of-gitlab). | +| `alert` | Hash | yes | Alerts detail. Same format as [3rd party alert](../operations/incident_management/alert_integrations.md#customize-the-alert-payload-outside-of-gitlab). | ```plaintext POST internal/kubernetes/modules/cilium_alert diff --git a/doc/development/lfs.md b/doc/development/lfs.md index d102d50df27..eeeebd52ecb 100644 --- a/doc/development/lfs.md +++ b/doc/development/lfs.md @@ -9,13 +9,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Deep Dive In April 2019, Francisco Javier López hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`) -on the GitLab [Git LFS](../topics/git/lfs/index.md) implementation to share his domain -specific knowledge with anyone who may work in this part of the codebase in the future. +on the GitLab [Git LFS](../topics/git/lfs/index.md) implementation to share domain-specific +knowledge with anyone who may work in this part of the codebase in the future. You can find the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [recording on YouTube](https://www.youtube.com/watch?v=Yyxwcksr0Qc), and the slides on [Google Slides](https://docs.google.com/presentation/d/1E-aw6-z0rYd0346YhIWE7E9A65zISL9iIMAOq2zaw9E/edit) and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/07a89257a140db067bdfb484aecd35e1/Git_LFS_Deep_Dive__Create_.pdf). -Everything covered in this deep dive was accurate as of GitLab 11.10, and while specific -details may have changed since then, it should still serve as a good introduction. +This deep dive was accurate as of GitLab 11.10, and while specific +details may have changed, it should still serve as a good introduction. ## Including LFS blobs in project archives @@ -52,7 +52,7 @@ JSON payload prefaced with `git-archive`. This payload includes the archive already exists in the archive cache, Workhorse sends that file. Otherwise, Workhorse sends the `SendArchiveRequest` to the appropriate Gitaly server. -1. The Gitaly server will call `git archive <ref>` to begin generating +1. The Gitaly server calls `git archive <ref>` to begin generating the Git archive on-the-fly. If the `include_lfs_blobs` flag is enabled, Gitaly enables a custom LFS smudge filter via the `-c filter.lfs.smudge=/path/to/gitaly-lfs-smudge` Git option. @@ -76,7 +76,7 @@ process, which writes the contents to the standard output. 1. The archive data is sent back to the client. In step 7, the `gitaly-lfs-smudge` filter must talk to Workhorse, not to -Rails, or an invalid LFS blob will be saved. To support this, GitLab +Rails, or an invalid LFS blob is saved. To support this, GitLab 13.5 [changed the default Omnibus configuration to have Gitaly talk to the Workhorse](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4592) instead of Rails. @@ -84,6 +84,6 @@ instead of Rails. One side effect of this change: the correlation ID of the original request is not preserved for the internal API requests made by Gitaly (or `gitaly-lfs-smudge`), such as the one made in step 8. The -correlation IDs for those API requests will be random values until [this +correlation IDs for those API requests are random values until [this Workhorse issue](https://gitlab.com/gitlab-org/gitlab-workhorse/-/issues/309) is resolved. diff --git a/doc/development/new_fe_guide/modules/widget_extensions.md b/doc/development/new_fe_guide/modules/widget_extensions.md index ffcd736511a..375baea0444 100644 --- a/doc/development/new_fe_guide/modules/widget_extensions.md +++ b/doc/development/new_fe_guide/modules/widget_extensions.md @@ -10,13 +10,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w ## Summary -Extensions in the merge request widget allow for others team to quickly and easily add new features -into the widget that will match the existing design and interaction as other extensions. +Extensions in the merge request widget enable you to add new features +into the widget that match the existing design and interaction as other extensions. ## Usage -To use extensions you need to first create a new extension object that will be used to fetch the -data that will be rendered in the extension. See the example file in +To use extensions you need to first create a new extension object to fetch the +data to render in the extension. See the example file in `app/assets/javascripts/vue_merge_request_widget/extensions/issues.js` for a working example. The basic object structure is as below: @@ -36,8 +36,8 @@ export default { }; ``` -Following the same data structure allows each extension to follow the same registering structure -but allows for each extension to manage where it gets its own data from. +By following the same data structure, each extension can follow the same registering structure, +but each extension can manage its data sources. After creating this structure you need to register it. Registering the extension can happen at any point _after_ the widget has been created. diff --git a/doc/development/wikis.md b/doc/development/wikis.md index a2da4843eac..1984e77866d 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -12,8 +12,8 @@ description: "GitLab's development guidelines for Wikis" ## Overview -The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/), -which is used in [Gitaly's](gitaly.md) Ruby service and accessed from the Rails app through Gitaly RPC calls. +The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/). +It's used in [Gitaly's](gitaly.md) Ruby service, and accessed from the Rails app through Gitaly RPC calls. Wikis use Git repositories as storage backend, and can be accessed through: @@ -43,7 +43,7 @@ When rendering wiki pages, we don't use Gollum at all and instead go through a [custom Banzai pipeline](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/pipeline/wiki_pipeline.rb). This adds some [wiki-specific markup](../user/markdown.md#wiki-specific-markdown), such as Gollum's `[[link]]` syntax. -Since we do not make use of most of Gollum's features, we plan to move away from it entirely at some point. +Because we do not make use of most of Gollum's features, we plan to move away from it entirely at some point. [See this epic](https://gitlab.com/groups/gitlab-org/-/epics/2381) for reference. ## Model classes diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index effdb4d7b75..910994cc0dd 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -177,7 +177,7 @@ The jobs are separated into stages: - The `test` job runs unit and integration tests by detecting the language and framework ([Auto Test](stages.md#auto-test)) - The `code_quality` job checks the code quality and is allowed to fail - ([Auto Code Quality](stages.md#auto-code-quality)) **(STARTER)** + ([Auto Code Quality](stages.md#auto-code-quality)) - The `container_scanning` job checks the Docker container if it has any vulnerabilities and is allowed to fail ([Auto Container Scanning](stages.md#auto-container-scanning)) - The `dependency_scanning` job checks if the application has any dependencies diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 23ba6ad3356..9b363f353ca 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -135,7 +135,7 @@ might want to use a [custom buildpack](customize.md#custom-buildpacks). ## Auto Code Quality -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in [GitLab](https://about.gitlab.com/pricing/) 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in GitLab 13.2. Auto Code Quality uses the diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index d2a42c0535e..6f1a9bbafcd 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -4,61 +4,65 @@ group: Ecosystem info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Creating a username and password for Jira Server +# Create Jira Server username and password -We need to create a user in Jira to have access to all projects that need to integrate with GitLab. +We need to create a user account in Jira to have access to all projects that +need to integrate with GitLab. -As an example, we create a user named `gitlab` and add it to a new group -named `gitlab-developers`. +The Jira user account created for the integration must have write access to +your Jira projects. -NOTE: -It is important that the Jira user created for the integration is given 'write' -access to your Jira projects. This is covered in the process below. +As an example, the following process creates a user named `gitlab` and that's a +member of a new group named `gitlab-developers`: -1. Log in to your Jira instance as an administrator and under **Jira Administration** - go to **User Management** to create a new user. +1. Sign in to your Jira instance as an administrator, and + then go to the gear icon and select **User Management**. ![Jira user management link](img/jira_user_management_link.png) -1. The next step is to create a new user (e.g., `gitlab`) who has write access - to projects in Jira. Enter the user's name and a _valid_ e-mail address - since Jira sends a verification e-mail to set up the password. +1. Create a new user account (for example, `gitlab`) with write access to + projects in Jira. Enter the user account's name and a valid e-mail address, + because Jira sends a verification email to set up the password. - Jira creates the username automatically by using the e-mail - prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You - need to create an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password. + Jira creates the username by using the email prefix. You can change the + username later, if needed. The GitLab integration doesn't support SSO (such + as SAML). You need to create an HTTP basic authentication password. You can + do this by visiting the user profile, looking up the username, and setting a + password. ![Jira create new user](img/jira_create_new_user.png) -1. Create a `gitlab-developers` group (we give this group write access to Jira - projects in a later step.) Go to the **Groups** tab on the left, and select **Add group**. +1. From the sidebar, select **Groups**. ![Jira create new user](img/jira_create_new_group.png) - Give it a name and click **Add group**. +1. In the **Add group** section, enter a **Name** for the group (for example, + `gitlab-developers`), and then select **Add group**. -1. Add the `gitlab` user to the `gitlab-developers` group by clicking **Edit members**. - The `gitlab-developers` group should be listed in the leftmost box as a selected group. - Under **Add members to selected group(s)**, enter `gitlab`. +1. Add the `gitlab` user to the `gitlab-developers` group by selecting **Edit members**. + The `gitlab-developers` group should be listed in the leftmost box as a + selected group. In the **Add members to selected group(s)** area, enter `gitlab`. ![Jira add user to group](img/jira_add_user_to_group.png) - Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box. - This membership is saved automatically. + Select **Add selected users**, and `gitlab` should appear in the **Group member(s)** + area. This membership is saved automatically. ![Jira added user to group](img/jira_added_user_to_group.png) -1. To give the newly-created group 'write' access, you need to create a **Permission Scheme**. - To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. - Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. +1. To give the newly-created group 'write' access, you must create a permission + scheme. To do this, in the admin menu, go to the gear icon and select **Issues**. -1. Once your permission scheme is created, you are taken back to the permissions scheme list. - Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, - click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` - from the dropdown. +1. From the sidebar, select **Permission Schemes**. + +1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a + **Description**, and then select **Add**. + +1. In the permissions scheme list, locate your new permissions scheme, and + select **Permissions**. Next to **Administer Projects**, select **Edit**. In + the **Group** list, select `gitlab-developers`. ![Jira group access](img/jira_group_access.png) The Jira configuration is complete. Write down the new Jira username and its -password as they are needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). +password, as you'll need them when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/lib/gitlab/badge/base.rb b/lib/gitlab/ci/badge/base.rb index fb55b9e2f1f..c65f120753d 100644 --- a/lib/gitlab/badge/base.rb +++ b/lib/gitlab/ci/badge/base.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -module Gitlab +module Gitlab::Ci module Badge class Base def entity diff --git a/lib/gitlab/badge/coverage/metadata.rb b/lib/gitlab/ci/badge/coverage/metadata.rb index 9181ba2d4b0..7654b6d6fc5 100644 --- a/lib/gitlab/badge/coverage/metadata.rb +++ b/lib/gitlab/ci/badge/coverage/metadata.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -module Gitlab +module Gitlab::Ci module Badge module Coverage ## diff --git a/lib/gitlab/badge/coverage/report.rb b/lib/gitlab/ci/badge/coverage/report.rb index 390da014a5a..28863a0703b 100644 --- a/lib/gitlab/badge/coverage/report.rb +++ b/lib/gitlab/ci/badge/coverage/report.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -module Gitlab +module Gitlab::Ci module Badge module Coverage ## diff --git a/lib/gitlab/badge/coverage/template.rb b/lib/gitlab/ci/badge/coverage/template.rb index 1b985f83b22..7589fa5ff8b 100644 --- a/lib/gitlab/badge/coverage/template.rb +++ b/lib/gitlab/ci/badge/coverage/template.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -module Gitlab +module Gitlab::Ci module Badge module Coverage ## diff --git a/lib/gitlab/badge/metadata.rb b/lib/gitlab/ci/badge/metadata.rb index b9ae68134b0..eec9fedfaa9 100644 --- a/lib/gitlab/badge/metadata.rb +++ b/lib/gitlab/ci/badge/metadata.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -module Gitlab +module Gitlab::Ci module Badge ## # Abstract class for badge metadata diff --git a/lib/gitlab/badge/pipeline/metadata.rb b/lib/gitlab/ci/badge/pipeline/metadata.rb index d4d789558c9..2aa08476336 100644 --- a/lib/gitlab/badge/pipeline/metadata.rb +++ b/lib/gitlab/ci/badge/pipeline/metadata.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -module Gitlab +module Gitlab::Ci module Badge module Pipeline ## diff --git a/lib/gitlab/badge/pipeline/status.rb b/lib/gitlab/ci/badge/pipeline/status.rb index f061ba22688..a2ee2642872 100644 --- a/lib/gitlab/badge/pipeline/status.rb +++ b/lib/gitlab/ci/badge/pipeline/status.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -module Gitlab +module Gitlab::Ci module Badge module Pipeline ## diff --git a/lib/gitlab/badge/pipeline/template.rb b/lib/gitlab/ci/badge/pipeline/template.rb index af8e318395b..8430b01fc9a 100644 --- a/lib/gitlab/badge/pipeline/template.rb +++ b/lib/gitlab/ci/badge/pipeline/template.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -module Gitlab +module Gitlab::Ci module Badge module Pipeline ## diff --git a/lib/gitlab/badge/template.rb b/lib/gitlab/ci/badge/template.rb index 9ac8f1c17f2..0580dad72ba 100644 --- a/lib/gitlab/badge/template.rb +++ b/lib/gitlab/ci/badge/template.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -module Gitlab +module Gitlab::Ci module Badge ## # Abstract template class for badges diff --git a/scripts/security-harness b/scripts/security-harness index b9492e16066..0c1ade06587 100755 --- a/scripts/security-harness +++ b/scripts/security-harness @@ -17,6 +17,7 @@ else SHELL_CLEAR = "\e[0m" end +LEFTHOOK_GLOBAL_CONFIG_PATH = File.expand_path("../lefthook.yml", __dir__) HOOK_PATH = File.expand_path("../.git/hooks/pre-push", __dir__) HOOK_DATA = <<~HOOK #!/usr/bin/env bash @@ -24,42 +25,65 @@ HOOK_DATA = <<~HOOK set -e url="$2" - harness=`dirname "$0"`/../security_harness - if [ -e "$harness" ] + if [[ "$url" != *"gitlab-org/security/"* ]] then - if [[ "$url" != *"gitlab-org/security/"* ]] - then - echo "Pushing to remotes other than gitlab.com/gitlab-org/security has been disabled!" - echo "Run scripts/security-harness to disable this check." - echo - - exit 1 - fi + echo "Pushing to remotes other than gitlab.com/gitlab-org/security has been disabled!" + echo "Run scripts/security-harness to disable this check." + echo + + exit 1 fi HOOK +def hook_exist? + File.exist?(HOOK_PATH) +end + +def lefthook_hook_in_place? + hook_exist? && File.foreach(HOOK_PATH).grep(/lefthook/i).any? +end + +def lefthook_available? + system('bundle exec lefthook run prepare-commit-msg &>/dev/null') # rubocop:disable GitlabSecurity/SystemCommandInjection +end + +def uninstall_lefthook + return unless lefthook_available? + + system('bundle exec lefthook uninstall') # rubocop:disable GitlabSecurity/SystemCommandInjection + # `bundle exec lefthook uninstall` removes the `lefthook.yml` file so we checkout it again + system("git checkout -- #{LEFTHOOK_GLOBAL_CONFIG_PATH}") # rubocop:disable GitlabSecurity/SystemCommandInjection + puts "#{SHELL_YELLOW}Lefthook was uninstalled to let the security harness work properly.#{SHELL_CLEAR}" +end + +def install_lefthook + return unless lefthook_available? + + system('bundle exec lefthook install') # rubocop:disable GitlabSecurity/SystemCommandInjection + puts "#{SHELL_GREEN}Lefthook was re-installed.#{SHELL_CLEAR}" +end + def write_hook FileUtils.mkdir_p(File.dirname(HOOK_PATH)) File.open(HOOK_PATH, 'w') do |file| file.write(HOOK_DATA) end File.chmod(0755, HOOK_PATH) + puts "#{SHELL_GREEN}Security harness installed -- you will only be able to push to gitlab.com/gitlab-org/security!#{SHELL_CLEAR}" end -# Toggle the harness on or off -def toggle - harness_path = File.expand_path('../.git/security_harness', __dir__) - - if File.exist?(harness_path) - FileUtils.rm(harness_path) +def delete_hook + FileUtils.rm(HOOK_PATH) + puts "#{SHELL_YELLOW}Security harness removed -- you can now push to all remotes.#{SHELL_CLEAR}" +end - puts "#{SHELL_YELLOW}Security harness removed -- you can now push to all remotes.#{SHELL_CLEAR}" - else - FileUtils.touch(harness_path) +def hook_file_sum + Digest::SHA256.file(HOOK_PATH).hexdigest +end - puts "#{SHELL_GREEN}Security harness installed -- you will only be able to push to gitlab.com/gitlab-org/security!#{SHELL_CLEAR}" - end +def hook_data_sum + Digest::SHA256.hexdigest(HOOK_DATA) end # If we were to change the script and then check for a pre-existing hook before @@ -67,33 +91,39 @@ end # the old hook. Checking previous version hashes allows us to safely overwrite a # script that differs from the current version, as long as it's an old one and # not custom. -def previous_version?(dest_sum) - # SHA256 hashes of previous iterations of the script contained in `DATA` +def upgrade_available? + # SHA256 hashes of previous iterations of the script contained in `HOOK_DATA` %w[ 010bf0363a911ebab2bd5728d80795ed02388da51815f0b2530d08ae8ac574f0 - ].include?(dest_sum) + d9866fc672f373d631eed9cd8dc9c920fa3d36ff26d956fb96a4082a0931b371 + ].include?(hook_file_sum) end -if !File.exist?(HOOK_PATH) - write_hook - toggle -else - # Deal with a pre-existing hook - source_sum = Digest::SHA256.hexdigest(HOOK_DATA) - dest_sum = Digest::SHA256.file(HOOK_PATH).hexdigest +def current_version? + hook_data_sum == hook_file_sum +end - if previous_version?(dest_sum) +# Uninstall Lefthook if it's in place +uninstall_lefthook if lefthook_hook_in_place? + +if hook_exist? + # Deal with a pre-existing hook + if upgrade_available? # Upgrading from a previous version, update in-place write_hook - toggle - elsif source_sum != dest_sum + elsif current_version? + # Delete the hook if we're already using the current version + delete_hook + + # Re-install Lefthook pre-push hook + install_lefthook + else # Pre-existing hook we didn't create; do nothing puts "#{SHELL_RED}#{HOOK_PATH} exists and is different from our hook!" puts "Remove it and re-run this script to continue.#{SHELL_CLEAR}" exit 1 - else - # No hook update needed, just toggle - toggle end +else + write_hook end diff --git a/spec/lib/gitlab/badge/coverage/metadata_spec.rb b/spec/lib/gitlab/ci/badge/coverage/metadata_spec.rb index 725ae03ad74..6d272f060ab 100644 --- a/spec/lib/gitlab/badge/coverage/metadata_spec.rb +++ b/spec/lib/gitlab/ci/badge/coverage/metadata_spec.rb @@ -1,9 +1,9 @@ # frozen_string_literal: true require 'spec_helper' -require 'lib/gitlab/badge/shared/metadata' +require 'lib/gitlab/ci/badge/shared/metadata' -RSpec.describe Gitlab::Badge::Coverage::Metadata do +RSpec.describe Gitlab::Ci::Badge::Coverage::Metadata do let(:badge) do double(project: create(:project), ref: 'feature', job: 'test') end diff --git a/spec/lib/gitlab/badge/coverage/report_spec.rb b/spec/lib/gitlab/ci/badge/coverage/report_spec.rb index 3b5ea3291e4..13696d815aa 100644 --- a/spec/lib/gitlab/badge/coverage/report_spec.rb +++ b/spec/lib/gitlab/ci/badge/coverage/report_spec.rb @@ -2,7 +2,7 @@ require 'spec_helper' -RSpec.describe Gitlab::Badge::Coverage::Report do +RSpec.describe Gitlab::Ci::Badge::Coverage::Report do let_it_be(:project) { create(:project) } let_it_be(:success_pipeline) { create(:ci_pipeline, :success, project: project) } let_it_be(:running_pipeline) { create(:ci_pipeline, :running, project: project) } diff --git a/spec/lib/gitlab/badge/coverage/template_spec.rb b/spec/lib/gitlab/ci/badge/coverage/template_spec.rb index ba5c1b2ce6e..f010d1bce50 100644 --- a/spec/lib/gitlab/badge/coverage/template_spec.rb +++ b/spec/lib/gitlab/ci/badge/coverage/template_spec.rb @@ -2,7 +2,7 @@ require 'spec_helper' -RSpec.describe Gitlab::Badge::Coverage::Template do +RSpec.describe Gitlab::Ci::Badge::Coverage::Template do let(:badge) { double(entity: 'coverage', status: 90.00, customization: {}) } let(:template) { described_class.new(badge) } diff --git a/spec/lib/gitlab/badge/pipeline/metadata_spec.rb b/spec/lib/gitlab/ci/badge/pipeline/metadata_spec.rb index c8ed0c8ea29..2f677237fad 100644 --- a/spec/lib/gitlab/badge/pipeline/metadata_spec.rb +++ b/spec/lib/gitlab/ci/badge/pipeline/metadata_spec.rb @@ -1,9 +1,9 @@ # frozen_string_literal: true require 'spec_helper' -require 'lib/gitlab/badge/shared/metadata' +require 'lib/gitlab/ci/badge/shared/metadata' -RSpec.describe Gitlab::Badge::Pipeline::Metadata do +RSpec.describe Gitlab::Ci::Badge::Pipeline::Metadata do let(:badge) { double(project: create(:project), ref: 'feature') } let(:metadata) { described_class.new(badge) } diff --git a/spec/lib/gitlab/badge/pipeline/status_spec.rb b/spec/lib/gitlab/ci/badge/pipeline/status_spec.rb index b5dabca0477..45d0d781090 100644 --- a/spec/lib/gitlab/badge/pipeline/status_spec.rb +++ b/spec/lib/gitlab/ci/badge/pipeline/status_spec.rb @@ -2,7 +2,7 @@ require 'spec_helper' -RSpec.describe Gitlab::Badge::Pipeline::Status do +RSpec.describe Gitlab::Ci::Badge::Pipeline::Status do let(:project) { create(:project, :repository) } let(:sha) { project.commit.sha } let(:branch) { 'master' } diff --git a/spec/lib/gitlab/badge/pipeline/template_spec.rb b/spec/lib/gitlab/ci/badge/pipeline/template_spec.rb index c78e95852f3..696bb62b4d6 100644 --- a/spec/lib/gitlab/badge/pipeline/template_spec.rb +++ b/spec/lib/gitlab/ci/badge/pipeline/template_spec.rb @@ -2,7 +2,7 @@ require 'spec_helper' -RSpec.describe Gitlab::Badge::Pipeline::Template do +RSpec.describe Gitlab::Ci::Badge::Pipeline::Template do let(:badge) { double(entity: 'pipeline', status: 'success', customization: {}) } let(:template) { described_class.new(badge) } diff --git a/spec/lib/gitlab/badge/shared/metadata.rb b/spec/lib/gitlab/ci/badge/shared/metadata.rb index c99a65bb2f4..c99a65bb2f4 100644 --- a/spec/lib/gitlab/badge/shared/metadata.rb +++ b/spec/lib/gitlab/ci/badge/shared/metadata.rb |