diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/development/background_migrations.md | 2 | ||||
-rw-r--r-- | doc/development/pipelines.md | 236 | ||||
-rw-r--r-- | doc/install/aws/index.md | 2 | ||||
-rw-r--r-- | doc/system_hooks/system_hooks.md | 6 | ||||
-rw-r--r-- | doc/user/project/integrations/prometheus.md | 17 | ||||
-rw-r--r-- | doc/user/project/merge_requests/accessibility_testing.md | 53 | ||||
-rw-r--r-- | doc/user/project/merge_requests/index.md | 1 |
7 files changed, 129 insertions, 188 deletions
diff --git a/doc/development/background_migrations.md b/doc/development/background_migrations.md index 02d31976481..dfe2312c2fa 100644 --- a/doc/development/background_migrations.md +++ b/doc/development/background_migrations.md @@ -329,6 +329,6 @@ for more details. or ask someone to measure on production). [migrations-readme]: https://gitlab.com/gitlab-org/gitlab/blob/master/spec/migrations/README.md -[issue-rspec-hooks]: https://gitlab.com/gitlab-org/gitlab-foss/issues/35351 +[issue-rspec-hooks]: https://gitlab.com/gitlab-org/gitlab/issues/18839 [reliable-sidekiq]: https://gitlab.com/gitlab-org/gitlab-foss/issues/36791 [import-export]: ../user/project/settings/import_export.md diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index 29208c1bf76..e228845bc72 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -64,180 +64,62 @@ Most of the jobs [extend from a few CI definitions](../ci/yaml/README.md#extends that are scoped to a single [configuration parameter](../ci/yaml/README.md#configuration-parameters). -These common definitions are: - -- `.default-tags`: Ensures a job has the `gitlab-org` tag to ensure it's using - our dedicated runners. -- `.default-retry`: Allows a job to [retry](../ci/yaml/README.md#retry) upon `unknown_failure`, `api_failure`, - `runner_system_failure`, `job_execution_timeout`, or `stuck_or_timeout_failure`. -- `.default-before_script`: Allows a job to use a default `before_script` definition - suitable for Ruby/Rails tasks that may need a database running (e.g. tests). -- `.default-cache`: Allows a job to use a default `cache` definition suitable for - Ruby/Rails and frontend tasks. -- `.default-only`: Restricts the cases where a job is created. This currently - includes `master`, `/^[\d-]+-stable(-ee)?$/` (stable branches), - `/^\d+-\d+-auto-deploy-\d+$/` (auto-deploy branches), `/^security\//` (security branches), `merge_requests`, `tags`. - Note that jobs won't be created for branches with this default configuration. -- `.only:variables-canonical-dot-com`: Only creates a job if the project is - located under <https://gitlab.com/gitlab-org>. -- `.only:variables_refs-canonical-dot-com-schedules`: Same as - `.only:variables-canonical-dot-com` but add the condition that pipeline is scheduled. -- `.except:refs-deploy`: Don't create a job if the `ref` is an auto-deploy branch. -- `.except:refs-master-tags-stable-deploy`: Don't create a job if the `ref` is one of: - - `master` - - a tag - - a stable branch - - an auto-deploy branch -- `.only:kubernetes`: Only creates a job if a Kubernetes integration is enabled - on the project. -- `.only-review`: This extends from: - - `.only:variables-canonical-dot-com` - - `.only:kubernetes` - - `.except:refs-master-tags-stable-deploy` -- `.only-review-schedules`: This extends from: - - `.only:variables_refs-canonical-dot-com-schedules` - - `.only:kubernetes` - - `.except:refs-deploy` -- `.use-pg9`: Allows a job to use the `postgres:9.6` and `redis:alpine` services. -- `.use-pg10`: Allows a job to use the `postgres:10.9` and `redis:alpine` services. -- `.use-pg9-ee`: Same as `.use-pg9` but also use the - `docker.elastic.co/elasticsearch/elasticsearch:5.6.12` services. -- `.use-pg10-ee`: Same as `.use-pg10` but also use the - `docker.elastic.co/elasticsearch/elasticsearch:5.6.12` services. -- `.only-ee`: Only creates a job for the `gitlab` or `gitlab-ee` project. -- `.only-ee-as-if-foss`: Same as `.only-ee` but simulate the FOSS project by - setting the `FOSS_ONLY='1'` environment variable. - -## Changes detection - -If a job extends from `.default-only` (and most of the jobs should), it can restrict -the cases where it should be created -[based on the changes](../ci/yaml/README.md#onlychangesexceptchanges) -from a commit or MR by extending from the following CI definitions: - -- `.only:changes-code`: Allows a job to only be created upon code-related changes. -- `.only:changes-qa`: Allows a job to only be created upon QA-related changes. -- `.only:changes-docs`: Allows a job to only be created upon docs-related changes. -- `.only:changes-graphql`: Allows a job to only be created upon GraphQL-related changes. -- `.only:changes-code-backstage`: Allows a job to only be created upon code-related or backstage-related (e.g. Danger, RuboCop, specs) changes. -- `.only:changes-code-qa`: Allows a job to only be created upon code-related or QA-related changes. -- `.only:changes-code-backstage-qa`: Allows a job to only be created upon code-related, backstage-related (e.g. Danger, RuboCop, specs) or QA-related changes. - -**See <https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml> -for the list of exact patterns.** - -## Rules conditions and changes patterns - -We're making use of the [`rules` keyword](https://docs.gitlab.com/ee/ci/yaml/#rules) but we're currently -duplicating the `if` conditions and `changes` patterns lists since they cannot be shared across -`include`d files as we do with `extends`. - -**If you update an `if` condition or `changes` -patterns list, make sure to mass-update those across all the CI config files (i.e. `.gitlab/ci/*.yml`).** - -### Canonical/security namespace merge requests only - -This condition limits jobs creation to merge requests under the `gitlab-org/` top-level group -on GitLab.com only (i.e. this won't run for `master`, stable or auto-deploy branches). -This is similar to the `.only:variables-canonical-dot-com` + `only:refs: [merge_requests]` -CI definitions. - -The definition for `if-canonical-dot-com-gitlab-org-groups-merge-request` can be -seen in <https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml>. - -### Canonical/security namespace tags only - -This condition limits jobs creation to tags under the `gitlab-org/` top-level group -on GitLab.com only. -This is similar to the `.only:variables-canonical-dot-com` + `only:refs: [tags]` CI definition: - -The definition for `if-canonical-dot-com-gitlab-org-groups-tag` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/cng.gitlab-ci.yml>. - -### Canonical namespace `master` only - -This condition limits jobs creation to `master` pipelines for the `gitlab-org` top-level group -on GitLab.com only. -This is similar to the `.only:variables-canonical-dot-com` + `only:refs: [master]` CI definition: - -The definition for `if-canonical-dot-com-gitlab-org-group-master-refs` can be -seen in <https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/pages.gitlab-ci.yml>. - -### Canonical namespace schedules only - -This condition limits jobs creation to scheduled pipelines for the `gitlab-org` top-level group -on GitLab.com only. -This is similar to the `.only:variables-canonical-dot-com` + `only:refs: [schedules]` CI definition: - -The definition for `if-canonical-dot-com-gitlab-org-group-schedule` can be seen -in <https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/qa.gitlab-ci.yml>. - -### Not canonical/security namespace - -This condition matches if the project isn't in the canonical/security namespace. -Useful to **not** create a job if the project is a fork, or in other words, when -a job should only run in the canonical projects. - -The definition for `if-not-canonical-namespace` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml>. - -### Not EE - -This condition matches if the project isn't EE. Useful to **not** create a job if -the project is GitLab, or in other words, when a job should only run in the GitLab -FOSS project. - -The definition for `if-not-ee` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml>. - -### Default refs only - -This condition is the equivalent of `.default-only`. - -The definition for `if-default-refs` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml>. - -### `master` refs only - -This condition is the equivalent of `only:refs: [master]`. - -The definition for `if-master-refs` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml>. - -### Code changes patterns - -Similar patterns as for `.only:changes-code`: - -The definition for `code-patterns` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/qa.gitlab-ci.yml>. - -### QA changes patterns - -Similar patterns as for `.only:changes-qa`: - -The definition for `qa-patterns` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/qa.gitlab-ci.yml>. - -### Docs changes patterns - -Similar patterns as for `.only:changes-docs`: - -The definition for `docs-patterns` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/docs.gitlab-ci.yml>. - -### Code and QA changes patterns - -Similar patterns as for `.only:changes-code-qa`: - -The definition for `code-qa-patterns` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/review.gitlab-ci.yml>. - -### Code, backstage and QA changes patterns - -Similar patterns as for `.only:changes-code-backstage-qa`: - -The definition for `code-backstage-qa-patterns` can be seen in -<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/frontend.gitlab-ci.yml>. +| Job definitions | Description | +|------------------|-------------| +| `.default-tags` | Ensures a job has the `gitlab-org` tag to ensure it's using our dedicated runners. | +| `.default-retry` | Allows a job to [retry](../ci/yaml/README.md#retry) upon `unknown_failure`, `api_failure`, `runner_system_failure`, `job_execution_timeout`, or `stuck_or_timeout_failure`. | +| `.default-before_script` | Allows a job to use a default `before_script` definition suitable for Ruby/Rails tasks that may need a database running (e.g. tests). | +| `.default-cache` | Allows a job to use a default `cache` definition suitable for Ruby/Rails and frontend tasks. | +| `.use-pg9` | Allows a job to use the `postgres:9.6.17` and `redis:alpine` services. | +| `.use-pg10` | Allows a job to use the `postgres:10.12` and `redis:alpine` services. | +| `.use-pg9-ee` | Same as `.use-pg9` but also use the `docker.elastic.co/elasticsearch/elasticsearch:6.4.2` services. | +| `.use-pg10-ee` | Same as `.use-pg10` but also use the `docker.elastic.co/elasticsearch/elasticsearch:6.4.2` services. | +| `.as-if-foss` | Simulate the FOSS project by setting the `FOSS_ONLY='1'` environment variable. | + +## `rules`, `if:` conditions and `changes:` patterns + +We're using the [`rules` keyword](../ci/yaml/README.md#rules) extensively. + +All `rules` definitions are defined in +<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rules.gitlab-ci.yml>, +then included in individual jobs via [`extends`](../ci/yaml/README.md#extends). + +The `rules` definitions are composed of `if:` conditions and `changes:` patterns, +which are also defined in +<https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rules.gitlab-ci.yml> +and included in `rules` definitions via [YAML anchors](../ci/yaml/README.md#anchors) + +### `if:` conditions + +| `if:` conditions | Description | Notes | +|------------------|-------------|-------| +| `if-not-canonical-namespace` | Matches if the project isn't in the canonical (`gitlab-org/`) or security (`gitlab-org/security`) namespace. | Use to create a job for forks (by using `when: on_success\|manual`), or **not** create a job for forks (by using `when: never`). | +| `if-not-ee` | Matches if the project isn't EE (i.e. project name isn't `gitlab` or `gitlab-ee`). | Use to create a job only in the FOSS project (by using `when: on_success|manual`), or **not** create a job if the project is EE (by using `when: never`). | +| `if-not-foss` | Matches if the project isn't FOSS (i.e. project name isn't `gitlab-foss`, `gitlab-ce`, or `gitlabhq`). | Use to create a job only in the EE project (by using `when: on_success|manual`), or **not** create a job if the project is FOSS (by using `when: never`). | +| `if-default-refs` | Matches if the pipeline is for `master`, `/^[\d-]+-stable(-ee)?$/` (stable branches), `/^\d+-\d+-auto-deploy-\d+$/` (auto-deploy branches), `/^security\//` (security branches), merge requests, and tags. | Note that jobs won't be created for branches with this default configuration. | +| `if-master-refs` | Matches if the current branch is `master`. | | +| `if-master-or-tag` | Matches if the pipeline is for the `master` branch or for a tag. | | +| `if-merge-request` | Matches if the pipeline is for a merge request. | | +| `if-dot-com-gitlab-org-schedule` | Limits jobs creation to scheduled pipelines for the `gitlab-org` group on GitLab.com. | | +| `if-dot-com-gitlab-org-master` | Limits jobs creation to the `master` branch for the `gitlab-org` group on GitLab.com. | | +| `if-dot-com-gitlab-org-merge-request` | Limits jobs creation to merge requests for the `gitlab-org` group on GitLab.com. | | +| `if-dot-com-gitlab-org-and-security-tag` | Limits job creation to tags for the `gitlab-org` and `gitlab-org/security` groups on GitLab.com. | | +| `if-dot-com-gitlab-org-and-security-merge-request` | Limit jobs creation to merge requests for the `gitlab-org` and `gitlab-org/security` groups on GitLab.com. | | +| `if-dot-com-ee-schedule` | Limits jobs to scheduled pipelines for the `gitlab-org/gitlab` project on GitLab.com. | | +| `if-cache-credentials-schedule` | Limits jobs to scheduled pipelines with the `$CI_REPO_CACHE_CREDENTIALS` variable set. | | + +### `changes:` patterns + +| `changes:` patterns | Description | +|------------------------------|--------------------------------------------------------------------------| +| `yaml-patterns` | Only create job for YAML-related changes. | +| `docs-patterns` | Only create job for docs-related changes. | +| `backstage-patterns` | Only create job for backstage-related changes. | +| `code-patterns` | Only create job for code-related changes. | +| `qa-patterns` | Only create job for QA-related changes. | +| `code-backstage-patterns` | Combination of `code-patterns` and `backstage-patterns`. | +| `code-qa-patterns` | Combination of `code-patterns` and `qa-patterns`. | +| `code-backstage-qa-patterns` | Combination of `code-patterns`, `backstage-patterns`, and `qa-patterns`. | ## Directed acyclic graph @@ -254,11 +136,11 @@ graph RL; F[build-qa-image]; G[review-deploy]; I["karma, jest, webpack-dev-server, static-analysis"]; - I2["karma-foss, jest-foss<br/>(EE default refs only)"]; + I2["karma-as-if-foss, jest-as-if-foss<br/>(EE default refs only)"]; J["compile-assets pull-push-cache<br/>(master only)"]; - J2["compile-assets pull-push-cache foss<br/>(EE master only)"]; + J2["compile-assets pull-push-cache as-if-foss<br/>(EE master only)"]; K[compile-assets pull-cache]; - K2["compile-assets pull-cache foss<br/>(EE default refs only)"]; + K2["compile-assets pull-cache as-if-foss<br/>(EE default refs only)"]; M[coverage]; N["pages (master only)"]; Q[package-and-qa]; diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 096d724717e..aa94dc1a2a5 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -639,7 +639,7 @@ And the more complex the solution, the more work is involved in setting up and maintaining it. Have a read through these other resources and feel free to -[open an issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/new) +[open an issue](https://gitlab.com/gitlab-org/gitlab/issues/new) to request additional material: - [GitLab High Availability](../../administration/high_availability/README.md): diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 30d080eab29..c2121697ed4 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -296,7 +296,7 @@ If the user is blocked via LDAP, `state` will be `ldap_blocked`. } ``` -`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab-foss/issues/39675>. +`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab/issues/20011>. **Group removed:** @@ -313,7 +313,7 @@ If the user is blocked via LDAP, `state` will be `ldap_blocked`. } ``` -`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab-foss/issues/39675>. +`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab/issues/20011>. **Group renamed:** @@ -333,7 +333,7 @@ If the user is blocked via LDAP, `state` will be `ldap_blocked`. } ``` -`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab-foss/issues/39675>. +`owner_name` and `owner_email` are always `null`. Please see <https://gitlab.com/gitlab-org/gitlab/issues/20011>. **New Group Member:** diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 210ce4ffe56..e703f15b4d3 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -198,18 +198,23 @@ supported and will not be available in the UI. #### Duplicating a GitLab-defined dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/37238) in GitLab 12.7. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/37238) in GitLab 12.7. +> - From [GitLab 12.8 onwards](https://gitlab.com/gitlab-org/gitlab/issues/39505), custom metrics are also duplicated when you duplicate a dashboard. -You can save a copy of a GitLab defined dashboard that can be customized and adapted to your project. You can decide to save the dashboard new `.yml` file in the project's **default** branch or in a newly created branch with a name of your choosing. +You can save a complete copy of a GitLab defined dashboard along with all custom metrics added to it. +Resulting `.yml` file can be customized and adapted to your project. +You can decide to save the dashboard `.yml` file in the project's **default** branch or in a +new branch. -1. Click on the "Duplicate dashboard" in the dashboard dropdown. +1. Click **Duplicate dashboard** in the dashboard dropdown. NOTE: **Note:** - Only GitLab-defined dashboards can be duplicated. + You can duplicate only GitLab-defined dashboards. -1. Input the file name and other information, such as a new commit message, and click on "Duplicate". +1. Enter the file name and other information, such as the new commit's message, and click **Duplicate**. -If you select your **default** branch, the new dashboard will become immediately available. If you select another branch, this branch should be merged to your **default** branch first. +If you select your **default** branch, the new dashboard becomes immediately available. +If you select another branch, this branch should be merged to your **default** branch first. #### Dashboard YAML properties diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md new file mode 100644 index 00000000000..7fa758b8a51 --- /dev/null +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -0,0 +1,53 @@ +--- +type: reference, howto +--- + +# Accessibility Testing + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. + +If your application offers a web interface and you are using +[GitLab CI/CD](../../../ci/README.md), you can quickly determine the accessibility +impact of pending code changes. + +## Overview + +GitLab uses [pa11y](https://pa11y.org/), a free and open source tool for +measuring the accessibility of web sites, and has built a simple +[CI job template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml). +This job outputs accessibility violations, warnings, and notices for each page +analyzed to a file called `accessibility`. + +## Configure Accessibility Testing + +This example shows how to run [pa11y](https://pa11y.org/) +on your code with GitLab CI/CD using a node Docker image. + +For GitLab 12.8 and later, to define the `a11y` job, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) +included with your GitLab installation, as shown below. +For GitLab versions earlier than 12.8, you can copy and use the job as +defined in that template. + +Add the following to your `.gitlab-ci.yml` file: + +```yaml +include: + template: Verify/Accessibility.gitlab-ci.yml + +a11y: + variables: + a11y_urls: https://example.com https://example.com/another-page +``` + +The example above will create an `a11y` job in your CI/CD pipeline and will run +Pa11y against the webpage you defined in `a11y_urls` to build a report. + +The full HTML Pa11y report will be saved as an artifact that can be [viewed directly in your browser](../pipelines/job_artifacts.md#browsing-artifacts). + +NOTE: **Note:** +The job definition provided by the template does not support Kubernetes yet. + +It is not yet possible to pass configurations into Pa11y via CI configuration. To change anything, +copy the template to your CI file and make the desired edits. diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 0617e6bc74d..2c613a29b0d 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -91,6 +91,7 @@ or link to useful information directly in the merge request page: | Feature | Description | |--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests | | [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the performance impact of pending code changes. | | [Code Quality](code_quality.md) **(STARTER)** | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | | [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../pipelines/job_artifacts.md) in merge requests. | |