diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-21 03:09:28 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-21 03:09:28 +0300 |
commit | b1031060f00cdb201cf8d790c6ec6421860c30f3 (patch) | |
tree | 44b572f9df4a5696d4378bc7848f19ac79e02cbd /doc | |
parent | cfd505b1984183857fcfeab259c5a38791205914 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/merge_request_approvals.md | 18 | ||||
-rw-r--r-- | doc/api/resource_groups.md | 70 | ||||
-rw-r--r-- | doc/ci/environments/deployment_safety.md | 2 | ||||
-rw-r--r-- | doc/ci/resource_groups/index.md | 168 | ||||
-rw-r--r-- | doc/ci/yaml/index.md | 2 | ||||
-rw-r--r-- | doc/development/feature_categorization/index.md | 5 | ||||
-rw-r--r-- | doc/development/service_ping/metrics_dictionary.md | 4 | ||||
-rw-r--r-- | doc/development/testing_guide/frontend_testing.md | 2 | ||||
-rw-r--r-- | doc/user/application_security/container_scanning/index.md | 2 | ||||
-rw-r--r-- | doc/user/group/index.md | 25 | ||||
-rw-r--r-- | doc/user/markdown.md | 2 |
11 files changed, 294 insertions, 6 deletions
diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index b4403e1d9b9..998fb534b7b 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -294,6 +294,7 @@ POST /projects/:id/approval_rules | `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | +| `rule_type` | string | no | The type of rule. `any_approver` is a pre-configured default rule with `approvals_required` at `0`. Other rules are `regular`. | `user_ids` | Array | no | The ids of users as approvers | | `group_ids` | Array | no | The ids of groups as approvers | | `protected_branch_ids` | Array | no | **(PREMIUM)** The ids of protected branches to scope the rule by | @@ -379,6 +380,23 @@ POST /projects/:id/approval_rules } ``` +You can increase the default number of 0 required approvers like this: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header 'Content-Type: application/json' \ + --data '{"name": "Any name", "rule_type": "any_approver", "approvals_required": 2}' +``` + +Another example is creating an additional, user-specific rule: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header 'Content-Type: application/json' \ + --data '{"name": "Name of your rule", "approvals_required": 3, "user_ids": [123, 456, 789]}' \ + https://gitlab.example.com/api/v4/projects/<project_id>/approval_rules +``` + ### Update project-level rule > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md new file mode 100644 index 00000000000..ce4fa33d7f2 --- /dev/null +++ b/doc/api/resource_groups.md @@ -0,0 +1,70 @@ +--- +stage: Release +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: concepts, howto +--- + +# Resource Groups API + +You can read more about [controling the job concurrency with resource groups](../ci/resource_groups/index.md). + +## Get a specific resource group + +```plaintext +GET /projects/:id/resource_groups/:key +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The key of the resource group | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/resource_groups/production" +``` + +Example of response + +```json +{ + "id": 3, + "key": "production", + "process_mode": "unordered", + "created_at": "2021-09-01T08:04:59.650Z", + "updated_at": "2021-09-01T08:04:59.650Z" +} +``` + +## Edit an existing resource group + +Updates an existing resource group's properties. + +It returns `200` if the resource group was successfully updated. In case of an error, a status code `400` is returned. + +```plaintext +PUT /projects/:id/resource_groups/:key +``` + +| Attribute | Type | Required | Description | +| --------------- | ------- | --------------------------------- | ------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The key of the resource group | +| `process_mode` | string | no | The process mode of the resource group. One of `unordered`, `oldest_first` or `newest_first`. Read [process modes](../ci/resource_groups/index.md#process-modes) for more information. | + +```shell +curl --request PUT --data "process_mode=oldest_first" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/resource_groups/production" +``` + +Example response: + +```json +{ + "id": 3, + "key": "production", + "process_mode": "oldest_first", + "created_at": "2021-09-01T08:04:59.650Z", + "updated_at": "2021-09-01T08:13:38.679Z" +} +``` diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 1b34b520007..78f30b29e06 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -60,7 +60,7 @@ The improved pipeline flow **after** using the resource group: 1. `deploy` job in Pipeline-A finishes. 1. `deploy` job in Pipeline-B starts running. -For more information, see [`resource_group` keyword in `.gitlab-ci.yml`](../yaml/index.md#resource_group). +For more information, see [Resource Group documentation](../resource_groups/index.md). ## Skip outdated deployment jobs diff --git a/doc/ci/resource_groups/index.md b/doc/ci/resource_groups/index.md new file mode 100644 index 00000000000..e5ff919a70c --- /dev/null +++ b/doc/ci/resource_groups/index.md @@ -0,0 +1,168 @@ +--- +stage: Release +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +description: Control the job concurrency in GitLab CI/CD +--- + +# Resource Group **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7. + +By default, pipelines in GitLab CI/CD run in parallel. The parallelization is an important factor to improve +the feedback loop in merge requests, however, there are some situations that +you may want to limit the concurrency on deployment +jobs to run them one by one. +Resource Group allows you to strategically control +the concurrency of the jobs for optimizing your continuous deployments workflow with safety. + +## Add a resource group + +Provided that you have the following pipeline configuration (`.gitlab-ci.yml` file in your repository): + +```yaml +build: + stage: build + script: echo "Your build script" + +deploy: + stage: deploy + script: echo "Your deployment script" + environment: production +``` + +Every time you push a new commit to a branch, it runs a new pipeline that has +two jobs `build` and `deploy`. But if you push multiple commits in a short interval, multiple +pipelines start running simultaneously, for example: + +- The first pipeline runs the jobs `build` -> `deploy` +- The second pipeline runs the jobs `build` -> `deploy` + +In this case, the `deploy` jobs across different pipelines could run concurrently +to the `production` environment. Running multiple deployment scripts to the same +infrastructure could harm/confuse the instance and leave it in a corrupted state in the worst case. + +In order to ensure that a `deploy` job runs once at a time, you can specify +[`resource_group` keyword](../yaml/index.md#resource_group) to the concurrency sensitive job: + +```yaml +deploy: + ... + resource_group: production +``` + +With this configuration, the safety on the deployments is assured while you +can still run `build` jobs concurrently for maximizing the pipeline efficency. + +## Requirements + +- The basic knowledge of the [GitLab CI/CD pipelines](../pipelines/index.md) +- The basic knowledge of the [GitLab Environments and Deployments](../environments/index.md) +- [Developer role](../../user/permissions.md) (or above) in the project to configure CI/CD pipelines. + +### Limitations + +Only one resource can be attached to a resource group. + +## Process modes + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202186) in GitLab 14.3. + +FLAG: +On self-managed GitLab, by default this feature is not available. +To make it available, ask an administrator to [enable the `ci_resource_group_process_modes` flag](../../administration/feature_flags.md). +On GitLab.com, this feature is not available. +The feature is not ready for production use. + +You can choose a process mode to strategically control the job concurrency for your deployment preferences. +The following modes are supported: + +- **Unordered:** This is the default process mode that limits the concurrency on running jobs. + It's the easiest option to use and useful when you don't care about the execution order + of the jobs. It starts processing the jobs whenever a job ready to run. +- **Oldest first:** This process mode limits the concurrency of the jobs. When a resource is free, + it picks the first job from the list of upcoming jobs (`created`, `scheduled`, or `waiting_for_resource` state) + that are sorted by pipeline ID in ascending order. + + This mode is useful when you want to ensure that the jobs are executed from the oldest pipeline. + This is less efficient compared to the `unordered` mode in terms of the pipeline efficiency, + but safer for continuous deployments. + +- **Newest first:** This process mode limits the concurrency of the jobs. When a resource is free, + it picks the first job from the list of upcoming jobs (`created`, `scheduled` or `waiting_for_resource` state) + that are sorted by pipeline ID in descending order. + + This mode is useful when you want to ensure that the jobs are executed from the newest pipeline and + cancel all of the old deploy jobs with the [skip outdated deployment jobs](../environments/deployment_safety.md#skip-outdated-deployment-jobs) feature. + This is the most efficient option in terms of the pipeline efficiency, but you must ensure that each deployment job is idempotent. + +### Change the process mode + +To change the process mode of a resource group, you need to use the API and +send a request to [edit an existing resource group](../../api/resource_groups.md#edit-an-existing-resource-group) +by specifying the `process_mode`: + +- `unordered` +- `oldest_first` +- `newest_first` + +### An example of difference between the process modes + +Consider the following `.gitlab-ci.yml`, where we have two jobs `build` and `deploy` +each running in their own stage, and the `deploy` job has a resource group set to +`production`: + +```yaml +build: + stage: build + script: echo "Your build script" + +deploy: + stage: deploy + script: echo "Your deployment script" + environment: production + resource_group: production +``` + +If three commits are pushed to the project in a short interval, that means that three +pipelines run almost at the same time: + +- The first pipeline runs the jobs `build` -> `deploy`. Let's call this deployment job `deploy-1`. +- The second pipeline runs the jobs `build` -> `deploy`. Let's call this deployment job `deploy-2`. +- The third pipeline runs the jobs `build` -> `deploy`. Let's call this deployment job `deploy-3`. + +Depending on the process mode of the resource group: + +- If the process mode is set to `unordered`: + - `deploy-1`, `deploy-2`, and `deploy-3` do not run in parallel. + - There is no guarantee on the job execution order, for example, `deploy-1` could run before or after `deploy-3` runs. +- If the process mode is `oldest_first`: + - `deploy-1`, `deploy-2`, and `deploy-3` do not run in parallel. + - `deploy-1` runs first, `deploy-2` runs second, and `deploy-3` runs last. +- If the process mode is `newest_first`: + - `deploy-1`, `deploy-2`, and `deploy-3` do not run in parallel. + - `deploy-3` runs first, `deploy-2` runs second and `deploy-1` runs last. + +## Pipeline-level concurrency control with Cross-Project/Parent-Child pipelines + +See the how to [control the pipeline concurrency in cross-project pipelines](../yaml/index.md#pipeline-level-concurrency-control-with-cross-projectparent-child-pipelines). + +## API + +See the [API documentation](../../api/resource_groups.md). + +## Related features + +Read more how you can use GitLab for [safe deployments](../environments/deployment_safety.md). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index fb5748788f7..ab4891f8dd6 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -3859,7 +3859,7 @@ can be deployed to, but there can be only one deployment per device at any given The `resource_group` value can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces. It can't start or end with `/`. -For more information, see [Deployments Safety](../environments/deployment_safety.md). +For more information, see [Resource Group documentation](../resource_groups/index.md). #### Pipeline-level concurrency control with Cross-Project/Parent-Child pipelines diff --git a/doc/development/feature_categorization/index.md b/doc/development/feature_categorization/index.md index 2f0f8101b53..07d1a981855 100644 --- a/doc/development/feature_categorization/index.md +++ b/doc/development/feature_categorization/index.md @@ -72,6 +72,11 @@ class SomeCrossCuttingConcernWorker end ``` +Workers marked as not owned workers will, when possible, use the +category of their caller (worker or HTTP endpoint) in metrics and logs. +For instance, `ReactiveCachingWorker` can have multiple feature +categories in metrics and logs. + ## Rails controllers Specifying feature categories on controller actions can be done using diff --git a/doc/development/service_ping/metrics_dictionary.md b/doc/development/service_ping/metrics_dictionary.md index 8dc2d2255d1..a2eb0ddb821 100644 --- a/doc/development/service_ping/metrics_dictionary.md +++ b/doc/development/service_ping/metrics_dictionary.md @@ -6,7 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Metrics Dictionary Guide -This guide describes the [Metrics Dictionary](https://gitlab-org.gitlab.io/growth/product-intelligence/metric-dictionary) and how it's implemented. +[Service Ping](index.md) metrics are defined in the +[Metrics Dictionary](https://gitlab-org.gitlab.io/growth/product-intelligence/metric-dictionary). +This guide describes the dictionary and how it's implemented. ## Metrics Definition and validation diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 76687db3a3f..035d3ce385f 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -998,7 +998,7 @@ it like so: import Subject from '~/feature/the_subject.vue'; // Force Jest to transpile and cache -// eslint-disable-next-line import/order, no-unused-vars +// eslint-disable-next-line no-unused-vars import _Thing from '~/feature/path/to/thing.vue'; ``` diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 2b3d4dbfc0a..0e5399f9d56 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -397,7 +397,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc We recommend that you set up a [scheduled pipeline](../../../ci/pipelines/schedules.md) to fetch the latest vulnerabilities database on a preset schedule. Automating this with a pipeline means you do not have to do it manually each time. You can use the -following `.gitlab-yml.ci` example as a template. +following `.gitlab-ci.yml` example as a template. ```yaml variables: diff --git a/doc/user/group/index.md b/doc/user/group/index.md index caf874cfe28..1b1118aa2f3 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -732,6 +732,31 @@ The group's new subgroups have push rules set for them based on either: - The closest parent group with push rules defined. - Push rules set at the instance level, if no parent groups have push rules defined. +## Group approval rules **(ULTIMATE)** + +> Introduced in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +per group, ask an administrator to [enable the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md). +The feature is not ready for production use. + +Group approval rules are an in-development feature that provides an interface for managing +[project merge request approval rules](../project/merge_requests/approvals/index.md) at the +top-level group level. + +The feature is limited to the user interface but the following merge requests extend the UI to: + +- [Enforce group settings on projects](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69750). +- [Cascade group settings onto projects](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68476). + +To view the merge request approval rules UI for a group: + +1. Go to the top-level group's **Settings > General** page. +1. Expand the **Merge request approvals** section. +1. Select the settings you want. +1. Select **Save changes**. + ## Related topics - [Group wikis](../project/wiki/index.md) diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 5eab5fcb513..5e600b6e0d1 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -524,7 +524,7 @@ GitLab Flavored Markdown recognizes the following: | specific user | `@user_name` | | | | specific group | `@group_name` | | | | entire team | `@all` | | | -| project | `namespace/project` | | | +| project | `namespace/project>` | | | | issue | ``#123`` | `namespace/project#123` | `project#123` | | merge request | `!123` | `namespace/project!123` | `project!123` | | snippet | `$123` | `namespace/project$123` | `project$123` | |