diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-04-12 18:15:44 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-04-12 18:15:44 +0300 |
| commit | c1a7bcdf1bfef9455bc58b1737f52530bf681a90 (patch) | |
| tree | fb683b37e3ef58bb7bd7698629796ed9c5bfbeae /doc | |
| parent | e0d7577e29dcab90623e1f38cf11b351c665ee23 (diff) | |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
34 files changed, 389 insertions, 435 deletions
diff --git a/doc/administration/auth/ldap/ldap_synchronization.md b/doc/administration/auth/ldap/ldap_synchronization.md index f54b0b02d7f..243f76f770d 100644 --- a/doc/administration/auth/ldap/ldap_synchronization.md +++ b/doc/administration/auth/ldap/ldap_synchronization.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w If you have [configured LDAP to work with GitLab](index.md), GitLab can automatically synchronize users and groups. -LDAP synchronization updates existing GitLab user and group information. It does not create new GitLab users through LDAP. +LDAP synchronization updates user and group information for existing GitLab users that have an LDAP identity assigned. It does not create new GitLab users through LDAP. You can change when synchronization occurs. diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md index 19734371915..9c69ac29194 100644 --- a/doc/administration/geo/replication/datatypes.md +++ b/doc/administration/geo/replication/datatypes.md @@ -47,8 +47,8 @@ verification methods: | Blobs | Container registry _(object storage)_ | Geo with API/Managed/Docker API (*2*) | _SHA256 checksum_ | | Blobs | Package registry _(file system)_ | Geo with API | SHA256 checksum | | Blobs | Package registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | -| Blobs | Infrastructure registry _(file system)_ | Geo with API | SHA256 checksum | -| Blobs | Infrastructure registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Terraform Module Registry _(file system)_ | Geo with API | SHA256 checksum | +| Blobs | Terraform Module Registry _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | Versioned Terraform State _(file system)_ | Geo with API | SHA256 checksum | | Blobs | Versioned Terraform State _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | | Blobs | External Merge Request Diffs _(file system)_ | Geo with API | SHA256 checksum | @@ -202,7 +202,7 @@ successfully, you must replicate their data using some other means. |[CI Pipeline Artifacts](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/pipeline_artifact.rb) | [**Yes** (13.11)](https://gitlab.com/gitlab-org/gitlab/-/issues/238464) | [**Yes** (13.11)](https://gitlab.com/gitlab-org/gitlab/-/issues/238464) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Persists additional artifacts after a pipeline completes. | |[CI Secure Files](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/ci/secure_file.rb) | [**Yes** (15.3)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91430) | [**Yes** (15.3)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91430) | [**Yes** (15.3)](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91430) | [No](object_storage.md#verification-of-files-in-object-storage) | Verification is behind the feature flag `geo_ci_secure_file_replication`, enabled by default in 15.3. | |[Container Registry](../../packages/container_registry.md) | **Yes** (12.3)* | **Yes** (15.10) | **Yes** (12.3)* | **Yes** (15.10) | See [instructions](container_registry.md) to set up the Container Registry replication. | -|[Infrastructure Registry](../../../user/packages/infrastructure_registry/index.md) | **Yes** (14.0) | **Yes** (14.0) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_package_file_replication`, enabled by default. | +|[Terraform Module Registry](../../../user/packages/terraform_module_registry/index.md) | **Yes** (14.0) | **Yes** (14.0) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Project designs repository](../../../user/project/issues/design_management.md) | **Yes** (12.7) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/32467) | N/A | N/A | Designs also require replication of LFS objects and Uploads. | |[Package Registry](../../../user/packages/package_registry/index.md) | **Yes** (13.2) | **Yes** (13.10) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_package_file_replication`, enabled by default. | |[Versioned Terraform State](../../terraform_state.md) | **Yes** (13.5) | **Yes** (13.12) | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Replication is behind the feature flag `geo_terraform_state_version_replication`, enabled by default. Verification was behind the feature flag `geo_terraform_state_version_verification`, which was removed in 14.0. | diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index c18bb5b6351..8031e2f4896 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -959,7 +959,7 @@ This behavior affects only the following data types through GitLab 14.6: | Package Registry | 13.10 | | CI Pipeline Artifacts | 13.11 | | Terraform State Versions | 13.12 | -| Infrastructure Registry | 14.0 | +| Infrastructure Registry (renamed to Terraform Module Registry in GitLab 15.11) | 14.0 | | External MR diffs | 14.6 | | LFS Objects | 14.6 | | Pages Deployments | 14.6 | diff --git a/doc/api/packages/terraform-modules.md b/doc/api/packages/terraform-modules.md index dd62dc6c09e..ff6ac24495e 100644 --- a/doc/api/packages/terraform-modules.md +++ b/doc/api/packages/terraform-modules.md @@ -4,16 +4,16 @@ group: Package Registry info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Terraform Registry API **(FREE)** +# Terraform Module Registry API **(FREE)** -This is the API documentation for [Terraform Modules](../../user/packages/terraform_module_registry/index.md). +This is the API documentation for the [Terraform Module Registry](../../user/packages/terraform_module_registry/index.md). WARNING: This API is used by the [Terraform CLI](https://www.terraform.io/) and is generally not meant for manual consumption. Undocumented authentication methods might be removed in the future. For instructions on how to upload and install Terraform modules from the GitLab -infrastructure registry, see the [Terraform modules registry documentation](../../user/packages/terraform_module_registry/index.md). +Terraform Module Registry, see the [Terraform Module Registry documentation](../../user/packages/terraform_module_registry/index.md). ## List available versions for a specific module @@ -35,7 +35,7 @@ curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.ex Example response: -```shell +```json { "modules": [ { @@ -93,9 +93,9 @@ curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.ex Example response: -```shell +```json { - "name": "hellow-world/local", + "name": "hello-world/local", "provider": "local", "providers": [ "local" @@ -132,9 +132,9 @@ curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.ex Example response: -```shell +```json { - "name": "hellow-world/local", + "name": "hello-world/local", "provider": "local", "providers": [ "local" @@ -171,7 +171,7 @@ curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.ex Example response: -```shell +```plaintext HTTP/1.1 204 No Content Content-Length: 0 X-Terraform-Get: /api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/file?token=&archive=tgz @@ -200,7 +200,7 @@ curl --header "Authorization: Bearer <personal_access_token>" "https://gitlab.ex Example response: -```shell +```plaintext HTTP/1.1 204 No Content Content-Length: 0 X-Terraform-Get: /api/v4/packages/terraform/modules/v1/group/hello-world/local/1.0.0/file?token=&archive=tgz diff --git a/doc/architecture/blueprints/cells/index.md b/doc/architecture/blueprints/cells/index.md index 516860cd6d6..3b88e2f731c 100644 --- a/doc/architecture/blueprints/cells/index.md +++ b/doc/architecture/blueprints/cells/index.md @@ -240,87 +240,6 @@ We can't ship the entire Cells architecture in one go - it is too large. Instead 1. Migrate existing organizations from `cell` to `cell` 1. Add additional Cell capabilities (DR, Regions) -### Iteration 0: Introduce organizations - -In the first iteration, we introduce the concept of an organization -as a way to group top-level namespaces together. Support for organizations **does not require any Cells work** but having them will make all subsequent iterations of Cells simpler. This is mainly because we can group top-level namespaces for a single organization onto a Cell. Within an organization all interactions work as normal but we eliminate any cross-organizational interactions except in well defined cases (e.g. forking). - -This means that we don't have a large number of cross-cell interactions. - -Introducing organizations allows GitLab to move towards a multi-tenant system that is similar to Discord's with a single user account but many different "servers" - our organizations - that allow users to switch context. This model harmonizes the UX across self-managed and our SaaS Platforms and is a good fit for Cells. - -Organizations solve the following problems: - -1. We can group top-level namespaces by organization. It is very similar to the initial concept of "instance groups". For example these two top-level namespaces would belong to the organization `GitLab`: - 1. `https://gitlab.com/gitlab-org/` - 1. `https://gitlab.com/gitlab-com/` -1. We can isolate organizations from each other. Top-level namespaces of the same organization can interact within organizations but are not allowed to interact with other namespaces in other organizations. This is useful for customers because it means an organization provides clear boundaries - similar to a self-managed instance. This means we don't have to aggregate user dashboards across everything and can locally scope them to organizations. -1. We don't need to define hierarchies inside an organization. It is a container that could be filled with whatever hierarchy / entity set makes sense (organization, top-level namespaces etc.) -1. Self-managed instances would set a default organization. -1. Organizations can control user-profiles in a central way. This could be achieved by having an organization specific user-profile. Such a profile makes it possible for the organization administrators to control the user role in a company, enforce user emails, or show a graphical indicator of a user being part of the organization. An example would be a "GitLab Employee stamp" on comments. - - - -#### Why would customers opt-in to Organizations? - -By introducing organizations and Cells we can improve the reliability, performance and availability of our SaaS Platforms. - -The first iteration of organizations would also have some benefits by providing more isolation. A simple example would be that `@` mentions could be scoped to an organization. - -Future iterations would create additional value but are beyond the scope of this blueprint. - -Organizations will likely be required in the future as well. - -#### Initial user experience - -1. We create a default `GitLab.com public` organization and assign all public top-level namespaces to it. This allows existing users to access all the data on GitLab.com, exactly as it does now. -1. Any user wanting to opt-in to the benefits of organizations will need to set a single default organization. Any attempts for these users to load a global page like `/dashboard` will end up redirecting to `/-/organizations/<DEFAULT_ORGANIZATION>/dashboard`. -1. New users that opted in to organizations will only ever see data that is related to a single organization. Upon login, data is shown for the default organization. It will be clear to the user how they can switch to a different organization. Users can still navigate to the `GitLab.com` organization but they won't see TODOs from their new organizations in any such views. Instead they'd need to navigate directly to `/organizations/my-company/-/dashboard`. - -### Migrating to Organizations - -Existing customers could also opt-in to migrate their existing top-level paid namespaces to become part of an organization. In most cases this will be a 1-to-1 mapping. But in some cases it may allow a customer to move multiple top-level namespaces into one organization (for example GitLab). - -Migrating to Organizations would be optional. We could even recruit a few beta testers early on to see if this works for them. GitLab itself could dogfood organizations and we'd surface a lot of issues restricting interactions with other namespaces. - -## Iteration 1 - Introduce Cell US 0 - -### GitLab.com as Cell US0 - -GitLab.com will be treated as the first cell `Cell US 0`. It will be unique and much larger compared to newly created cells. All existing top-level namespaces and organizations will remain on `Cell US 0` in the first iteration. - -### Users are globally available - -Users are globally available and the same for all cells. This means that user data needs to be handled separately, for example via decomposition, see [!95941](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95941). - -### Cell groundwork - -In this iteration, we'll lay all the groundwork to support a second Cell for new organizations. This will be transparent to customers. - -## Iteration 2 - Introduce Cell US 1 - -### Add new organizations to Cell US 1 - -After we are ready to support a second Cell, newly created organizations are located by default on `Cell US 1`. The user experience for organizations is already well established. - -### Migrate existing organizations from Cell US 0 to Cell US 1 - -We know that we'll have to move organizations from `Cell US 0` to other cells to reduce its size and ultimately retire the existing GitLab.com architecture. - -By introducing organizations early, we should be able to draw strong "boundaries" across organizations and support migrating existing organizations to a new Cell. - -This is likely going to be GitLab itself - if we can dogfood this, we are likely going to be successful with other organizations as well. - -## Iteration 3 - Introduce Regions - -We can now leverage the Cells architecture to introduce Regions. - -## Iteration 4 - Introduce cross-organizational interactions as needed - -Based on user research, we may want to change certain features to work across organizations. Examples include: - -- Specific features allow for cross-organization interactions, for example forking, search. - ## Technical Proposals The Cells architecture do have long lasting implications to data processing, location, scalability and the GitLab architecture. diff --git a/doc/architecture/blueprints/ci_pipeline_components/index.md b/doc/architecture/blueprints/ci_pipeline_components/index.md index 390690c0f35..82ff00ff4ee 100644 --- a/doc/architecture/blueprints/ci_pipeline_components/index.md +++ b/doc/architecture/blueprints/ci_pipeline_components/index.md @@ -228,7 +228,8 @@ The version of the component can be (in order of highest priority first): 1. A commit SHA - For example: `gitlab.com/gitlab-org/dast@e3262fdd0914fa823210cdb79a8c421e2cef79d8` 1. A tag - For example: `gitlab.com/gitlab-org/dast@1.0` -1. A special moving target version that points to the most recent released tag - For example: `gitlab.com/gitlab-org/dast@~latest` +1. A special moving target version that points to the most recent released tag. The target project must be +explicitly marked as a [catalog resource](#catalog-resource) - For example: `gitlab.com/gitlab-org/dast@~latest` 1. A branch name - For example: `gitlab.com/gitlab-org/dast@master` If a tag and branch exist with the same name, the tag takes precedence over the branch. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index 1d7877a7b2f..3e9e6c50f64 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -208,119 +208,7 @@ Jobs that exceed the timeout are marked as failed. You can override this value [for individual runners](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). -## Merge request test coverage results - -If you use test coverage in your code, you can use a regular expression to -find coverage results in the job log. You can then include these results -in the merge request in GitLab. - -If the pipeline succeeds, the coverage is shown in the merge request widget and -in the jobs table. If multiple jobs in the pipeline have coverage reports, they are -averaged. - - - - - -### Add test coverage results using `coverage` keyword - -To add test coverage results to a merge request using the project's `.gitlab-ci.yml` file, provide a regular expression -using the [`coverage`](../yaml/index.md#coverage) keyword. - -### Test coverage examples - -Use this regex for commonly used test tools. - -<!-- vale gitlab.Spelling = NO --> - -- Simplecov (Ruby). Example: `/\(\d+.\d+\%\) covered/`. -- pytest-cov (Python). Example: `/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/`. -- Scoverage (Scala). Example: `/Statement coverage[A-Za-z\.*]\s*:\s*([^%]+)/`. -- `pest --coverage --colors=never` (PHP). Example: `/^\s*Cov:\s*\d+\.\d+?%$/`. -- `phpunit --coverage-text --colors=never` (PHP). Example: `/^\s*Lines:\s*\d+.\d+\%/`. -- gcovr (C/C++). Example: `/^TOTAL.*\s+(\d+\%)$/`. -- `tap --coverage-report=text-summary` (NodeJS). Example: `/^Statements\s*:\s*([^%]+)/`. -- `nyc npm test` (NodeJS). Example: `/All files[^|]*\|[^|]*\s+([\d\.]+)/`. -- `jest --ci --coverage` (NodeJS). Example: `/All files[^|]*\|[^|]*\s+([\d\.]+)/`. -- excoveralls (Elixir). Example: `/\[TOTAL\]\s+(\d+\.\d+)%/`. -- `mix test --cover` (Elixir). Example: `/\d+.\d+\%\s+\|\s+Total/`. -- JaCoCo (Java/Kotlin). Example: `/Total.*?([0-9]{1,3})%/`. -- `go test -cover` (Go). Example: `/coverage: \d+.\d+% of statements/`. -- .NET (OpenCover). Example: `/(Visited Points).*\((.*)\)/`. -- .NET (`dotnet test` line coverage). Example: `/Total\s*\|\s*(\d+(?:\.\d+)?)/`. -- tarpaulin (Rust). Example: `/^\d+.\d+% coverage/`. -- Pester (PowerShell). Example: `/Covered (\d+\.\d+%)/`. - -<!-- vale gitlab.Spelling = YES --> - -### View code coverage history - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209121) the ability to download a `.csv` in GitLab 12.10. -> - Graph [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1. - -To see the evolution of your project code coverage over time, -you can view a graph or download a CSV file with this data. - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Repository**. - -The historic data for each job is listed in the dropdown list above the graph. - -To view a CSV file of the data, select **Download raw data (`.csv`)**. - - - -Code coverage data is also [available at the group level](../../user/group/repositories_analytics/index.md). - -### Coverage check approval rule **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15765) in GitLab 14.0. -> - [Made configurable in Project Settings](https://gitlab.com/gitlab-org/gitlab/-/issues/331001) in GitLab 14.1. - -You can implement merge request approvals to require approval by selected users or a group -when merging a merge request would cause the project's test coverage to decline. - -Follow these steps to enable the `Coverage-Check` MR approval rule: - -1. Set up a [`coverage`](../yaml/index.md#coverage) regular expression for all jobs you want to include in the overall coverage value. -1. Go to your project and select **Settings > Merge requests**. -1. Under **Merge request approvals**, select **Enable** next to the `Coverage-Check` approval rule. -1. Select the **Target branch**. -1. Set the number of **Approvals required** to greater than zero. -1. Select the users or groups to provide approval. -1. Select **Add approval rule**. - - - -### Remove color codes from code coverage - -Some test coverage tools output with ANSI color codes that aren't -parsed correctly by the regular expression. This causes coverage -parsing to fail. - -Some coverage tools don't provide an option to disable color -codes in the output. If so, pipe the output of the coverage tool through a -small one line script that strips the color codes off. - -For example: - -```shell -lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g' -``` - ## Pipeline badges You can use [pipeline badges](../../user/project/badges.md) to indicate the pipeline status and test coverage of your projects. These badges are determined by the latest successful pipeline. - -<!-- ## 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, for example `### 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/testing/code_coverage.md b/doc/ci/testing/code_coverage.md new file mode 100644 index 00000000000..bd1246d2f78 --- /dev/null +++ b/doc/ci/testing/code_coverage.md @@ -0,0 +1,129 @@ +--- +stage: Verify +group: Pipeline Execution +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Code coverage **(FREE)** + +Use code coverage to provide insights on what source code is being validated by a test suite. Code coverage is one of many test metrics that can determine software performance and quality. + +## View Code Coverage results + +Code Coverage results are shown in: + +- Merge request widget +- Project repository analytics +- Group repository analytics +- Repository badge + +For more information on test coverage visualization in the file diff of the MR, see [Test Coverage Visualization](test_coverage_visualization.md). + +### View code coverage results in the MR + +If you use test coverage in your code, you can use a regular expression to +find coverage results in the job log. You can then include these results +in the merge request in GitLab. + +If the pipeline succeeds, the coverage is shown in the merge request widget and +in the jobs table. If multiple jobs in the pipeline have coverage reports, they are +averaged. + + + + + +#### Add test coverage results using `coverage` keyword + +To add test coverage results to a merge request using the project's `.gitlab-ci.yml` file, provide a regular expression +using the [`coverage`](../yaml/index.md#coverage) keyword. + +#### Test coverage examples + +Use this regex for commonly used test tools. + +<!-- vale gitlab.Spelling = NO --> + +- Simplecov (Ruby). Example: `/\(\d+.\d+\%\) covered/`. +- pytest-cov (Python). Example: `/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/`. +- Scoverage (Scala). Example: `/Statement coverage[A-Za-z\.*]\s*:\s*([^%]+)/`. +- `pest --coverage --colors=never` (PHP). Example: `/^\s*Cov:\s*\d+\.\d+?%$/`. +- `phpunit --coverage-text --colors=never` (PHP). Example: `/^\s*Lines:\s*\d+.\d+\%/`. +- gcovr (C/C++). Example: `/^TOTAL.*\s+(\d+\%)$/`. +- `tap --coverage-report=text-summary` (NodeJS). Example: `/^Statements\s*:\s*([^%]+)/`. +- `nyc npm test` (NodeJS). Example: `/All files[^|]*\|[^|]*\s+([\d\.]+)/`. +- `jest --ci --coverage` (NodeJS). Example: `/All files[^|]*\|[^|]*\s+([\d\.]+)/`. +- excoveralls (Elixir). Example: `/\[TOTAL\]\s+(\d+\.\d+)%/`. +- `mix test --cover` (Elixir). Example: `/\d+.\d+\%\s+\|\s+Total/`. +- JaCoCo (Java/Kotlin). Example: `/Total.*?([0-9]{1,3})%/`. +- `go test -cover` (Go). Example: `/coverage: \d+.\d+% of statements/`. +- .NET (OpenCover). Example: `/(Visited Points).*\((.*)\)/`. +- .NET (`dotnet test` line coverage). Example: `/Total\s*\|\s*(\d+(?:\.\d+)?)/`. +- tarpaulin (Rust). Example: `/^\d+.\d+% coverage/`. +- Pester (PowerShell). Example: `/Covered (\d+\.\d+%)/`. + +<!-- vale gitlab.Spelling = YES --> + +### View history of project code coverage + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209121) the ability to download a `.csv` in GitLab 12.10. +> - Graph [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1. + +To see the evolution of your project code coverage over time, +you can view a graph or download a CSV file with this data. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Repository**. + +The historic data for each job is listed in the dropdown list above the graph. + +To view a CSV file of the data, select **Download raw data (`.csv`)**. + + + +### View history of group code coverage **(PREMIUM)** + +To see the all the project's code coverage under a group over time, you can find view [group repository analytics](../../user/group/repositories_analytics/index.md). + + + +### Pipeline badges + +You can use [pipeline badges](../../user/project/badges.md#test-coverage-report-badges) to indicate the pipeline status and +test coverage of your projects. These badges are determined by the latest successful pipeline. + +## Coverage check approval rule **(PREMIUM)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15765) in GitLab 14.0. +> - [Made configurable in Project Settings](https://gitlab.com/gitlab-org/gitlab/-/issues/331001) in GitLab 14.1. + +When merging a request that would cause the project's test coverage to decline, you can stipulate that such merge requests require approval by selected users or a group. + +Follow these steps to enable the `Coverage-Check` MR approval rule: + +1. Set up a [`coverage`](../yaml/index.md#coverage) regular expression for all jobs you want to include in the overall coverage value. +1. Go to your project and select **Settings > Merge requests**. +1. Under **Merge request approvals**, select **Enable** next to the `Coverage-Check` approval rule. +1. Select the **Target branch**. +1. Set the number of **Approvals required** to greater than zero. +1. Select the users or groups to provide approval. +1. Select **Add approval rule**. + + + +## Troubleshooting + +### Remove color codes from code coverage + +Some test coverage tools output with ANSI color codes that aren't +parsed correctly by the regular expression. This causes coverage +parsing to fail. + +Some coverage tools do not provide an option to disable color +codes in the output. If so, pipe the output of the coverage tool through a one-line script that strips the color codes. + +For example: + +```shell +lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g' +``` diff --git a/doc/ci/pipelines/img/code_coverage_graph_v13_1.png b/doc/ci/testing/img/code_coverage_graph_v13_1.png Binary files differindex da92a1b4a86..da92a1b4a86 100644 --- a/doc/ci/pipelines/img/code_coverage_graph_v13_1.png +++ b/doc/ci/testing/img/code_coverage_graph_v13_1.png diff --git a/doc/ci/testing/img/code_coverage_group_report.png b/doc/ci/testing/img/code_coverage_group_report.png Binary files differnew file mode 100644 index 00000000000..df8ca613f8c --- /dev/null +++ b/doc/ci/testing/img/code_coverage_group_report.png diff --git a/doc/ci/pipelines/img/coverage_check_approval_rule_14_1.png b/doc/ci/testing/img/coverage_check_approval_rule_14_1.png Binary files differindex 8c1d005e074..8c1d005e074 100644 --- a/doc/ci/pipelines/img/coverage_check_approval_rule_14_1.png +++ b/doc/ci/testing/img/coverage_check_approval_rule_14_1.png diff --git a/doc/ci/pipelines/img/pipelines_test_coverage_build.png b/doc/ci/testing/img/pipelines_test_coverage_build.png Binary files differindex 7eaba1a256f..7eaba1a256f 100644 --- a/doc/ci/pipelines/img/pipelines_test_coverage_build.png +++ b/doc/ci/testing/img/pipelines_test_coverage_build.png diff --git a/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png b/doc/ci/testing/img/pipelines_test_coverage_mr_widget.png Binary files differindex fbcd612f3f2..fbcd612f3f2 100644 --- a/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png +++ b/doc/ci/testing/img/pipelines_test_coverage_mr_widget.png diff --git a/doc/ci/testing/index.md b/doc/ci/testing/index.md index d97c58b21e8..a8fb6d688d7 100644 --- a/doc/ci/testing/index.md +++ b/doc/ci/testing/index.md @@ -14,6 +14,7 @@ display reports or link to important information directly from [merge requests]( | [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests. | | [Browser Performance Testing](browser_performance_testing.md) | Quickly determine the browser performance impact of pending code changes. | | [Load Performance Testing](load_performance_testing.md) | Quickly determine the server performance impact of pending code changes. | +| [Code Coverage](code_coverage.md) | See code coverage results in the MR, project or group. | | [Code Quality](code_quality.md) | 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](../yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../jobs/job_artifacts.md) in merge requests. | | [Unit test reports](unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. | diff --git a/doc/ci/testing/test_coverage_visualization.md b/doc/ci/testing/test_coverage_visualization.md index 52cdde88538..94ee4d2dce2 100644 --- a/doc/ci/testing/test_coverage_visualization.md +++ b/doc/ci/testing/test_coverage_visualization.md @@ -54,8 +54,8 @@ of times the line was checked by tests. Uploading a test coverage report does not enable: -- [Test coverage results in merge requests](../pipelines/settings.md#merge-request-test-coverage-results). -- [Code coverage history](../pipelines/settings.md#view-code-coverage-history). +- [Test coverage results in merge requests](code_coverage.md#view-code-coverage-results-in-the-mr). +- [Code coverage history](code_coverage.md#view-history-of-project-code-coverage). You must configure these separately. diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 06f574906c5..fc903144a87 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -1512,6 +1512,7 @@ In this example: **Additional details**: +- You can find parse examples in [Code Coverage](../testing/code_coverage.md#test-coverage-examples). - If there is more than one matched line in the job output, the last line is used (the first result of reverse search). - If there are multiple matches in a single line, the last match is searched diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 8cf66c68935..9a7bf616c46 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -1329,6 +1329,13 @@ Use lowercase for **terminal**. For example: - Open a terminal. - From a terminal, run the `docker login` command. +## Terraform Module Registry + +Use title case for the GitLab Terraform Module Registry, but use lowercase `m` when +talking about non-specific modules. For example: + +- You can publish a Terraform module to your project's Terraform Module Registry. + ## text box Use **text box** instead of **field** or **box** when referring to the UI element. diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 6403cff549f..ef506f260f7 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -11,7 +11,7 @@ across the GitLab frontend team. ## Overview -GitLab is built on top of [Ruby on Rails](https://rubyonrails.org). It uses [Haml](https://haml.info/) and a JavaScript-based frontend with [Vue.js](https://vuejs.org). +GitLab is built on top of [Ruby on Rails](https://rubyonrails.org). It uses [Haml](https://haml.info/) and a JavaScript-based frontend with [Vue.js](https://vuejs.org). If you are not sure when to use Vue on top of Haml-page, please read [this explanation](vue.md#when-to-add-vue-application). <!-- vale gitlab.Spelling = NO --> diff --git a/doc/development/fe_guide/registry_architecture.md b/doc/development/fe_guide/registry_architecture.md index d86f8416db6..cf267e80619 100644 --- a/doc/development/fe_guide/registry_architecture.md +++ b/doc/development/fe_guide/registry_architecture.md @@ -14,7 +14,7 @@ Existing registries: - Package Registry - Container Registry -- Infrastructure Registry +- Terraform Module Registry - Dependency Proxy ## Frontend architecture diff --git a/doc/development/fe_guide/source_editor.md b/doc/development/fe_guide/source_editor.md index 6fb4767c0a1..2c115effcf9 100644 --- a/doc/development/fe_guide/source_editor.md +++ b/doc/development/fe_guide/source_editor.md @@ -17,6 +17,14 @@ GitLab features use it, including: - [Web Editor](../../user/project/repository/web_editor.md) - [Security Policies](../../user/application_security/policies/index.md) +## When to use Source Editor + +Use Source Editor only when users need to edit the file content. +If you only need to display source code, consider using the [`BlobContent`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/blob/components/blob_content.vue) component. + +If the page you're working on is already loading the Source Editor, +displaying read-only content in the Source Editor is still a valid option. + ## How to use Source Editor Source Editor is framework-agnostic and can be used in any application, including both diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 80b8a755773..65ceb9f0220 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -16,11 +16,23 @@ What is described in the following sections can be found in these examples: - [Security products](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/app/assets/javascripts/vue_shared/security_reports) - [Registry](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/registry/stores) +## When to add Vue application + +Sometimes, HAML page is enough to satisfy requirements. This statement is correct primarily for the static pages or pages that have very little logic. How do we know it's worth adding a Vue application to the page? The answer is "when we need to maintain application state and synchronize the rendered page with it". + +To better explain this, let's imagine the page that has one toggle, and toggling it sends an API request. This case does not involve any state we want to maintain, we send the request and switch the toggle. However, if we add ont more toggle that should always be the opposite to the first one, we need a _state_: one toggle should be "aware" about the state of another one. When written in plain JavaScript, this logic usually involves listening to DOM event and reacting with modifying DOM. Cases like this are much easier to handle with Vue.js so we should create a Vue application here. + +### What are some flags signaling that you might need Vue application? + +- when you need to define complex conditionals based on multiple factors and update them on user interaction; +- when you have to maintain any form of application state and share it between tags/elements; +- when you expect complex logic to be added in the future - it's easier to start with basic Vue application than having to rewrite JS/HAML to Vue on the next step. + ## Vue architecture All new features built with Vue.js must follow a [Flux architecture](https://facebookarchive.github.io/flux/). The main goal we are trying to achieve is to have only one data flow, and only one data entry. -To achieve this goal we use [Vuex](#vuex). +To achieve this goal we use [Vuex](#vuex) or [Apollo Client](graphql.md#libraries) You can also read about this architecture in Vue documentation about [state management](https://v2.vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch) diff --git a/doc/development/pipelines/index.md b/doc/development/pipelines/index.md index 87c7345491d..5d2db9c20ec 100644 --- a/doc/development/pipelines/index.md +++ b/doc/development/pipelines/index.md @@ -176,6 +176,20 @@ graph LR A --"artifact: list of test files"--> B & C ``` +## Merge Trains + +### Why do we need to have a “stable” master branch to enable merge trains? + +If the master branch is unstable (i.e. CI/CD pipelines for the master branch are failing frequently), all of the merge requests pipelines that were added AFTER a faulty merge request pipeline would have to be **cancelled** and **added back to the train**, which would create a lot of delays if the merge train is long. + +### How stable does the master branch have to be for us to enable merge trains? + +We don't have a specific number, but we need to have better numbers for flaky tests failures and infrastructure failures (see the [Master Broken Incidents RCA Dashboard](https://app.periscopedata.com/app/gitlab/1082465/Master-Broken-Incidents-Root-Cause-Analysis)). + +### Could we gradually move to merge trains in our CI/CD configuration? + +There was a proposal from a contributor, but the approach is not without some downsides: [see the original proposal and discussion](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/issues/195#note_1117151994). + ## Faster feedback for some merge requests ### Broken Master Fixes diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md index 70ad92fd962..88cc824b6b2 100644 --- a/doc/user/clusters/agent/gitops/flux_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -1,19 +1,21 @@ --- stage: Deploy group: Environments -info: A tutorial using Flux with Project Access Tokens +info: A tutorial using Flux --- # Tutorial: Set up Flux for GitOps **(FREE)** This tutorial teaches you how to set up Flux for GitOps. You'll set up a sample project, complete a bootstrap Flux installation, and authenticate your installation with a -[project access token](../../../project/settings/project_access_tokens.md). +[project deploy token](../../../project/deploy_tokens/index.md). -You can find the fully configured tutorial project [in this GitLab repository](https://gitlab.com/gitlab-org/configure/examples/flux/flux-config). It works in conjunction with [this repository](https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests/-/tree/main), which contains the example Kubernetes manifests. +You can find the fully configured tutorial project [in this GitLab repository](https://gitlab.com/gitlab-org/configure/examples/flux/flux-config). +It works in conjunction with [this repository](https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests/-/tree/main), which contains the example Kubernetes manifests. -To set up Flux with a project access token: +To set up Flux for GitOps: +1. [Create a personal access token](#create-a-personal-access-token) 1. [Create the Flux repository](#create-the-flux-repository) 1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository) 1. [Configure Flux to sync your manifests](#configure-flux-to-sync-your-manifests) @@ -21,27 +23,31 @@ To set up Flux with a project access token: Prerequisites: -- On GitLab SaaS, you must have the Premium or Ultimate tier to use a project access token. - On self-managed instances, you can have any tier. -- Not recommended. You can authenticate with a [personal or group access token](flux.md#bootstrap-installation) in all tiers. - You must have a Kubernetes cluster running. -## Create the Flux repository +## Create a personal access token -To start, create a Git repository, install Flux, and authenticate Flux with your repo: +To authenticate with the Flux CLI, you must create a personal access token +with the `api` scope: -1. Make sure your `kubectl` is configured to access your cluster. -1. [Install the Flux CLI](https://fluxcd.io/flux/installation/#install-the-flux-cli). -1. In GitLab, create a new empty project called `flux-config`. -1. In the `flux-config` project, create a [project access token](../../../project/settings/project_access_tokens.md#create-a-project-access-token) with the following settings: +1. In the upper-right corner, select your avatar. +1. Select **Edit profile**. +1. On the left sidebar, select **Access Tokens**. +1. Enter a name and optional expiry date for the token. +1. Select the `api` scope. +1. Select **Create personal access token**. - - From the **Select a role** dropdown list, select **Maintainer**. - - Under **Select scopes**, select the **API** and **write_repository** checkboxes. +You can also use a [project](../../../project/settings/project_access_tokens.md) or [group access token](../../../group/settings/group_access_tokens.md) with the `api` scope. - Name the project token `flux-project-access-token`. +## Create the Flux repository -1. From your shell, export a `GITLAB_TOKEN` environment variable with the value of your project access token. - For example, `export GITLAB_TOKEN=<flux-project-access-token>`. +Create a Git repository, install Flux, and authenticate Flux with your repo: + +1. Make sure your `kubectl` is configured to access your cluster. +1. [Install the Flux CLI](https://fluxcd.io/flux/installation/#install-the-flux-cli). You must install Flux v2 or higher. +1. In GitLab, create a new empty project called `flux-config`. +1. From your shell, export a `GITLAB_TOKEN` environment variable with the value of your personal access token. + For example, `export GITLAB_TOKEN=<personal-access-token>`. 1. Run the `bootstrap` command. The exact command depends on whether you are creating the Flux repository under a GitLab user, group, or subgroup. For more information, see the [Flux bootstrap documentation](https://fluxcd.io/flux/installation/#gitlab-and-gitlab-enterprise). @@ -54,11 +60,13 @@ To start, create a Git repository, install Flux, and authenticate Flux with your --repository=flux-config \ --branch=main \ --path=clusters/my-cluster + --deploy-token-auth ``` This command installs Flux on the Kubernetes cluster and configures it to manage itself from the repository `flux-config`. + The command also automatically creates the project deploy token required to access the `flux-config` repository. -Great work! You now have a repository, a project access token, and a Flux bootstrap installation authenticated to your repo. Any updates to your repo are automatically synced to the cluster. +Great work! You now have a repository bootstrapped with a Flux configuration. Any updates to your repository are automatically synced to the cluster. ## Create the Kubernetes manifest repository @@ -93,7 +101,7 @@ Next, create a repository for your Kubernetes manifests: - containerPort: 80 ``` -1. In the new repository, [create a deploy token](../../../project/deploy_tokens/index.md#create-a-deploy-token) with only the **read_repository** scope. +1. In the new repository, [create a deploy token](../../../project/deploy_tokens/index.md#create-a-deploy-token) with only the `read_repository` scope. 1. Store your deploy token username and password somewhere safe. 1. In Flux CLI, create a secret with your deploy token and point the secret to the new repository. For example: diff --git a/doc/user/compliance/compliance_report/index.md b/doc/user/compliance/compliance_report/index.md index 3dc27c10908..1962dfefdf5 100644 --- a/doc/user/compliance/compliance_report/index.md +++ b/doc/user/compliance/compliance_report/index.md @@ -85,10 +85,10 @@ The following are unavailable compliance violations that are tracked in [epic 52 |:-------------------------------------|:---------------|:---------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------| | Pipeline failed | Medium | [Pipeline results](../../../ci/pipelines/index.md) | Merge requests pipeline failed and was merged. | | Pipeline passed with warnings | Info | [Pipeline results](../../../ci/pipelines/index.md) | Merge request pipeline passed with warnings and was merged. | -| Code coverage down more than 10% | High | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | Code coverage report for the merge request indicates a reduction in coverage of more than 10%. | -| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | Code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | -| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | Code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | -| Code coverage down less than 1% | Info | [Code coverage](../../../ci/pipelines/settings.md#merge-request-test-coverage-results) | Code coverage report for the merge request indicates a reduction in coverage of less than 1%. | +| Code coverage down more than 10% | High | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of more than 10%. | +| Code coverage down between 5% to 10% | Medium | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 5% to 10%. | +| Code coverage down between 1% to 5% | Low | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of between 1% to 5%. | +| Code coverage down less than 1% | Info | [Code coverage](../../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) | Code coverage report for the merge request indicates a reduction in coverage of less than 1%. | <!-- vale gitlab.SubstitutionWarning = YES --> diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md index edb3e1b5079..c2a4d8175b3 100644 --- a/doc/user/group/repositories_analytics/index.md +++ b/doc/user/group/repositories_analytics/index.md @@ -42,7 +42,7 @@ To see the latest code coverage for each project in your group: 1. In the **Latest test coverage results** section, from the **Select projects** dropdown list, choose the projects you want to check. You can download code coverage data for specific projects using -[code coverage history](../../../ci/pipelines/settings.md#view-code-coverage-history). +[code coverage history](../../../ci/testing/code_coverage.md#view-history-of-project-code-coverage). ## Download historic test coverage data diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index c263f0c1519..d4fc345f494 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -100,7 +100,7 @@ For GitLab-curated template recipes, see [Terraform template recipes](terraform_ ## Related topics - View [the images that contain the `gitlab-terraform` shell script](https://gitlab.com/gitlab-org/terraform-images). -- Use GitLab as a [Terraform module registry](../../packages/terraform_module_registry/index.md). +- Use GitLab as a [Terraform Module Registry](../../packages/terraform_module_registry/index.md). - To store state files in local storage or in a remote store, use the [GitLab-managed Terraform state](terraform_state.md). - To collaborate on Terraform code changes and Infrastructure-as-Code workflows, use the [Terraform integration in merge requests](mr_integration.md). diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index 7418977e0d1..2084de58bdb 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -14,15 +14,9 @@ packages, which can be easily consumed as a dependency in downstream projects. The GitLab [Container Registry](container_registry/index.md) is a secure and private registry for container images. It's built on open source software and completely integrated within GitLab. Use GitLab CI/CD to create and publish images. Use the GitLab [API](../../api/container_registry.md) to manage the registry across groups and projects. -## Infrastructure Registry +## Terraform Module Registry -The GitLab [Infrastructure Registry](infrastructure_registry/index.md) is a secure and private registry for infrastructure packages. You can use GitLab CI/CD to create and publish infrastructure packages. - -The Infrastructure Registry supports the following formats: - -| Package type | GitLab version | -| ------------ | -------------- | -| [Terraform Module](terraform_module_registry/index.md) | 14.0+ | +The GitLab [Terraform Module Registry](terraform_module_registry/index.md) is a secure and private registry for Terraform modules. You can use GitLab CI/CD to create and publish modules. ## Dependency Proxy diff --git a/doc/user/packages/infrastructure_registry/index.md b/doc/user/packages/infrastructure_registry/index.md index d06c5e7fb1e..8c1e8a2ad8a 100644 --- a/doc/user/packages/infrastructure_registry/index.md +++ b/doc/user/packages/infrastructure_registry/index.md @@ -1,102 +1,11 @@ --- -stage: Package -group: Package Registry -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +redirect_to: '../terraform_module_registry/index.md' +remove_date: '2023-06-13' --- -# Infrastructure Registry **(FREE)** +This document was moved to [another location](../terraform_module_registry/index.md). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. - -With the GitLab Infrastructure Registry, you can use GitLab projects as a -private registry for infrastructure packages. You can create and publish -packages with GitLab CI/CD, which can then be consumed from other private -projects. - -## View packages - -To view packages within your project: - -1. Go to the project. -1. Go to **Packages and registries > Infrastructure Registry**. - -You can search, sort, and filter packages on this page. - -For information on how to create and upload a package, view the GitLab -documentation for your package type: - -- [Terraform modules](../terraform_module_registry/index.md) - -## Use GitLab CI/CD to build packages - -To use [GitLab CI/CD](../../../ci/index.md) to build packages, you can -authenticate with the [`CI_JOB_TOKEN` predefined variable](../../../ci/variables/predefined_variables.md). - -CI/CD templates, which you can use to get started, are in [this repository](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates). - -For more information about using CI/CD to build Terraform modules, -see [Publish a Terraform module by using CI/CD](../terraform_module_registry/index.md#publish-a-terraform-module-by-using-cicd). - -If you use CI/CD to build a package, you can find extended activity information -when you view the package details: - - - -You can see the pipeline that published the package as well as the commit and the user who triggered it. However, the history is limited to five updates per package. - -## Download a package - -To download a package: - -1. Go to **Packages and registries > Infrastructure Registry**. -1. Select the name of the package you want to download. -1. In the **Activity** section, select the name of the package you want to download. - -## Delete a package - -You cannot edit a package after you publish it in the Infrastructure Registry. Instead, you -must delete and recreate it. - -To delete a package, you must have suitable [permissions](../../permissions.md). - -You can delete packages by using [the API](../../../api/packages.md#delete-a-project-package) or the UI. - -To delete a package in the UI, from your project: - -1. Go to **Packages and registries > Infrastructure Registry**. -1. Find the name of the package you want to delete. -1. Select **Delete**. - -The package is permanently deleted. - -## Disable the Infrastructure Registry - -The Infrastructure Registry is automatically enabled. - -For self-managed instances, a GitLab administrator can -[disable](../../../administration/packages/index.md) **Packages and registries**, -which removes this menu item from the sidebar. - -You can also remove the Infrastructure Registry for a specific project: - -1. In your project, go to **Settings > General**. -1. Expand the **Visibility, project features, permissions** section and toggle **Packages** off (in gray). -1. Select **Save changes**. - -To enable it back, follow the same steps above and toggle it on (in blue). - -## How module resolution works - -When you upload a new module, GitLab generates a path for the module, for example, `https://gitlab.example.com/parent-group/my-infra-package`. - -- This path conforms with [the Terraform spec](https://www.terraform.io/internals/module-registry-protocol). -- The name of the path must be unique within the namespace. - -For projects in subgroups, GitLab checks that the module name does not already exist anywhere in the namespace, including all subgroups and the parent group. - -For example, if: - -- The project is `gitlab.example.com/parent-group/sub-group/my-project`. -- The infrastructure package is `my-infra-package`. - -The project name must be unique in all projects in all groups under `parent-group`. +<!-- This redirect file can be deleted after <2023-06-13>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/packages/terraform_module_registry/index.md b/doc/user/packages/terraform_module_registry/index.md index 038eaabf6d4..d7f33dd9e79 100644 --- a/doc/user/packages/terraform_module_registry/index.md +++ b/doc/user/packages/terraform_module_registry/index.md @@ -4,32 +4,53 @@ group: Package Registry info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Terraform module registry **(FREE)** +# Terraform Module Registry **(FREE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3221) in GitLab 14.0. +> - Infrastructure registry and Terraform Module Registry [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/404075) into a single Terraform Module Registry feature in GitLab 15.11. -Publish Terraform modules in your project's Infrastructure Registry, then reference them using GitLab -as a Terraform module registry. +With the Terraform Module Registry, you can use GitLab projects as a +private registry for terraform modules. You can create and publish +modules with GitLab CI/CD, which can then be consumed from other private +projects. -## Authenticate to the Terraform module registry +## View Terraform modules -To authenticate to the Terraform module registry, you need either: +To view Terraform modules in your project: + +1. Go to the project. +1. On the left sidebar, select **Packages and registries > Terraform modules**. + +You can search, sort, and filter modules on this page. + +For information on how to create and upload a package, view the GitLab +documentation for your package type: + +- [Terraform modules](../terraform_module_registry/index.md) + +## Authenticate to the Terraform Module Registry + +To authenticate to the Terraform Module Registry, you need either: - A [personal access token](../../../api/rest/index.md#personalprojectgroup-access-tokens) with at least `read_api` rights. - A [CI/CD job token](../../../ci/jobs/ci_job_token.md). Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future. -## Publish a Terraform Module +## Publish a Terraform module -When you publish a Terraform Module, if it does not exist, it is created. +When you publish a Terraform module, if it does not exist, it is created. + +### Using the API + +You can publish Terraform modules by using the [Terraform Module Registry API](../../../api/packages/terraform-modules.md). Prerequisites: -- The package name and version [must be unique in the top-level namespace](../infrastructure_registry/index.md#how-module-resolution-works). +- The package name and version [must be unique in the top-level namespace](#how-module-resolution-works). - Your project and group names must not include a dot (`.`). For example, `source = "gitlab.example.com/my.group/project.name"`. - You must [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a deploy token, it must be configured with the `write_package_registry` scope. -- The name of a module [must be unique within the scope of its group](../infrastructure_registry/index.md#how-module-resolution-works), otherwise an +- The name of a module [must be unique in the scope of its group](#how-module-resolution-works), otherwise an [error occurs](#troubleshooting). ```plaintext @@ -39,9 +60,9 @@ PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module | Attribute | Type | Required | Description | | -------------------| --------------- | ---------| -------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../../api/rest/index.md#namespaced-path-encoding). | -| `module-name` | string | yes | The package name. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The package name can't exceed 64 characters. -| `module-system` | string | yes | The package system. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The package system can't exceed 64 characters. More information can be found in the [Terraform Module Registry Protocol documentation](https://www.terraform.io/internals/module-registry-protocol). -| `module-version` | string | yes | The package version. It must be valid according to the [Semantic Versioning Specification](https://semver.org/). +| `module-name` | string | yes | The module name. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The module name can't exceed 64 characters. +| `module-system` | string | yes | The module system. **Supported syntax**: One to 64 ASCII characters, including lowercase letters (a-z) and digits (0-9). The module system can't exceed 64 characters. More information can be found in the [Terraform Module Registry protocol documentation](https://www.terraform.io/internals/module-registry-protocol). +| `module-version` | string | yes | The module version. It must be valid according to the [semantic versioning specification](https://semver.org/). Provide the file content in the request body. @@ -57,14 +78,6 @@ curl --fail-with-body --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file" ``` -Example response: - -```json -{ - "message":"201 Created" -} -``` - Example request using a deploy token: ```shell @@ -81,41 +94,13 @@ Example response: } ``` -## Reference a Terraform Module - -Prerequisites: - -- You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. - -Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: - -```plaintext -credentials "gitlab.com" { - token = "<TOKEN>" -} -``` - -Where `gitlab.com` can be replaced with the hostname of your self-managed GitLab instance. +### Using a CI/CD template (recommended) -You can then refer to your Terraform Module from a downstream Terraform project: - -```plaintext -module "<module>" { - source = "gitlab.com/<namespace>/<module-name>/<module-system>" -} -``` - -Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the Terraform module registry. - -## Publish a Terraform module by using CI/CD - -> CI/CD template [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110493) in GitLab 15.9. - -### Use a CI/CD template (recommended) +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110493) in GitLab 15.9. You can use the [`Terraform-Module.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform-Module.gitlab-ci.yml) or the advanced [`Terraform/Module-Base.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Module-Base.gitlab-ci.yml) -CI/CD template to publish a Terraform module to the GitLab Terraform Registry: +CI/CD template to publish a Terraform module to the GitLab terraform registry: ```yaml include: @@ -126,7 +111,7 @@ The pipeline contains the following jobs: - `fmt` - Validate the formatting of the Terraform module. - `kics-iac-sast` - Test the Terraform module for security issues. -- `deploy` - For tag pipelines only. Deploy the Terraform module to the GitLab Terraform Registry. +- `deploy` - For tag pipelines only. Deploy the Terraform module to the Terraform Module Registry. #### Pipeline variables @@ -139,7 +124,7 @@ You can configure the pipeline with the following variables: | `TERRAFORM_MODULE_SYSTEM` | `local` | The system or provider of your Terraform module targets. For example, `local`, `aws`, `google`. | | `TERRAFORM_MODULE_VERSION` | `${CI_COMMIT_TAG}` | The Terraform module version. You should follow the semantic versioning specification. | -### Deploy manually via CI/CD +### Using CI/CD manually To work with Terraform modules in [GitLab CI/CD](../../../ci/index.md), you can use `CI_JOB_TOKEN` in place of the personal access token in your commands. @@ -168,14 +153,97 @@ upload: - if: $CI_COMMIT_TAG ``` -To trigger this upload job, add a Git tag to your commit. Ensure the tag follows the [Semantic Versioning Specification](https://semver.org/) that Terraform requires. The `rules:if: $CI_COMMIT_TAG` ensures that only tagged commits to your repository trigger the module upload job. +To trigger this upload job, add a Git tag to your commit. Ensure the tag follows the [Semantic versioning specification](https://semver.org/) that Terraform requires. The `rules:if: $CI_COMMIT_TAG` ensures that only tagged commits to your repository trigger the module upload job. For other ways to control jobs in your CI/CD pipeline, refer to the [`.gitlab-ci.yml`](../../../ci/yaml/index.md) keyword reference. +## Reference a Terraform module + +Prerequisites: + +- You need to [authenticate with the API](../../../api/rest/index.md#authentication). If authenticating with a personal access token, it must be configured with the `read_api` scope. + +Authentication tokens (Job Token or Personal Access Token) can be provided for `terraform` in your `~/.terraformrc` file: + +```terraform +credentials "gitlab.com" { + token = "<TOKEN>" +} +``` + +Where `gitlab.com` can be replaced with the hostname of your self-managed GitLab instance. + +You can then refer to your Terraform module from a downstream Terraform project: + +```terraform +module "<module>" { + source = "gitlab.com/<namespace>/<module-name>/<module-system>" +} +``` + +Where `<namespace>` is the [namespace](../../../user/namespace/index.md) of the Terraform Module Registry. + +## Download a Terraform module + +To download a Terraform module: + +1. On the left sidebar, select **Packages and registries > Terraform modules**. +1. Select the name of the module you want to download. +1. In the **Activity** section, select the name of the module you want to download. + +## How module resolution works + +When you upload a new module, GitLab generates a path for the module, for example, `https://gitlab.example.com/parent-group/my-infra-package`. + +- This path conforms with [the Terraform spec](https://www.terraform.io/internals/module-registry-protocol). +- The name of the path must be unique in the namespace. + +For projects in subgroups, GitLab checks that the module name does not already exist anywhere in the namespace, including all subgroups and the parent group. + +For example, if: + +- The project is `gitlab.example.com/parent-group/sub-group/my-project`. +- The Terraform module is `my-infra-package`. + +The project name must be unique in all projects in all groups under `parent-group`. + +## Delete a Terraform module + +You cannot edit a Terraform module after you publish it in the Terraform Module Registry. Instead, you +must delete and recreate it. + +To delete a module, you must have suitable [permissions](../../permissions.md). + +You can delete modules by using [the packages API](../../../api/packages.md#delete-a-project-package) or the UI. + +To delete a module in the UI, from your project: + +1. On the left sidebar, select **Packages and registries > Terraform modules**. +1. Find the name of the package you want to delete. +1. Select **Delete**. + +The package is permanently deleted. + +## Disable the Terraform Module Registry + +The Terraform Module Registry is automatically enabled. + +For self-managed instances, a GitLab administrator can +[disable](../../../administration/packages/index.md) **Packages and registries**, +which removes this menu item from the sidebar. + +You can also remove the Terraform Module Registry for a specific project: + +1. In your project, go to **Settings > General**. +1. Expand the **Visibility, project features, permissions** section and toggle **Packages** off (in gray). +1. Select **Save changes**. + +To enable it back, follow the same steps above and toggle it on (in blue). + ## Example projects -For examples of the Terraform module registry, check the projects below: +For examples of the Terraform Module Registry, check the projects below: -- The [_GitLab local file_ project](https://gitlab.com/mattkasa/gitlab-local-file) creates a minimal Terraform module and uploads it into the Terraform module registry using GitLab CI/CD. +- The [_GitLab local file_ project](https://gitlab.com/mattkasa/gitlab-local-file) creates a minimal Terraform module and uploads it into the Terraform Module Registry using GitLab CI/CD. - The [_Terraform module test_ project](https://gitlab.com/mattkasa/terraform-module-test) uses the module from the previous example. ## Troubleshooting diff --git a/doc/user/project/badges.md b/doc/user/project/badges.md index bd3fba57b3f..76933255820 100644 --- a/doc/user/project/badges.md +++ b/doc/user/project/badges.md @@ -62,7 +62,7 @@ You can access a test coverage report badge image by using the following link: https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg ``` -You can define the regular expression for the [coverage report](../../ci/pipelines/settings.md#merge-request-test-coverage-results) +You can define the regular expression for the [coverage report](../../ci/testing/code_coverage.md#view-code-coverage-results-in-the-mr) that each job log is matched against. This means that each job in the pipeline can have the test coverage percentage value defined. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 3d455178938..a4272731407 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -101,7 +101,7 @@ Without the approvals, the work cannot merge. Required approvals enable multiple database, for all proposed code changes. - Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), to determine who should review the work. -- Require an [approval before merging code that causes test coverage to decline](../../../../ci/pipelines/settings.md#coverage-check-approval-rule) +- Require an [approval before merging code that causes test coverage to decline](../../../../ci/testing/code_coverage.md#coverage-check-approval-rule) - Users on GitLab Ultimate can also [require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 786897c18c9..5c0282dd9e0 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -244,6 +244,28 @@ approval rule for certain branches: 1. To enable this configuration, read [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). +## Code coverage check approval + +You can require specific approvals in the case that a merge request would reduce code test +coverage. + +For more information, see [Coverage check approval rule](../../../../ci/testing/code_coverage.md#coverage-check-approval-rule). + +## Security Approvals **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. + +You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. +Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. + +The security approval rules are applied to all merge requests until the pipeline is complete. The application of the +security approval rules prevents users from merging in code before the security scans run. After the pipeline is +complete, the security approval rules are checked to determine if the security approvals are still required. + + + +These policies are both created and edited in the [security policy editor](../../../application_security/policies/index.md#policy-editor). + ## Troubleshooting ### Approval rule name can't be blank @@ -265,18 +287,3 @@ isn't recognized as a valid Code Owner for the project, nor does it display in t project's **Approvals** list. To fix this problem, add the approval group as a shared group high enough in the shared hierarchy so the project requiring review inherits this group of users. - -## Security Approvals **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/357021) in GitLab 15.0. - -You can use [scan result policies](../../../application_security/policies/scan-result-policies.md#scan-result-policy-editor) to define security approvals based on the status of vulnerabilities in the merge request and the default branch. -Details for each security policy is shown in the Security Approvals section of your Merge Request configuration. - -The security approval rules are applied to all merge requests until the pipeline is complete. The application of the -security approval rules prevents users from merging in code before the security scans run. Once the pipeline is -complete, the security approval rules are checked to determine if the security approvals are still required. - - - -These policies are both created and edited in the [security policy editor](../../../application_security/policies/index.md#policy-editor). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index c13aaa132c9..154be8a83bb 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -153,13 +153,6 @@ To do this: select **Remove approvals by Code Owners if their files changed**. 1. Select **Save changes**. -## Code coverage check approvals - -You can require specific approvals if a merge request would result in a decline in code test -coverage. - -For more information, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). - ## Settings cascading > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285410) in GitLab 14.4. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../../../administration/feature_flags.md), disabled by default. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index c4fcdc5733e..cdfbaa0fe92 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -499,15 +499,10 @@ In GitLab 15.9 and earlier, uploads to a comment are sent as links in the email. #### Special HTML formatting in HTML emails -<!-- When the feature flag is removed, delete this topic and add as a line in version history under one of the topics above this one.--> +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/109811) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116809) in GitLab 15.11. Feature flag `service_desk_html_to_text_email_handler` removed. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372301) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `service_desk_html_to_text_email_handler`. -On GitLab.com, this feature is not available. - -When this feature is enabled, HTML emails correctly show additional HTML formatting, such as: +HTML emails show special HTML formatting such as: - Tables - Blockquotes |
