diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api/graphql/reference/index.md | 30 | ||||
| -rw-r--r-- | doc/architecture/blueprints/cells/index.md | 15 | ||||
| -rw-r--r-- | doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md | 63 | ||||
| -rw-r--r-- | doc/architecture/blueprints/modular_monolith/bounded_contexts.md | 27 | ||||
| -rw-r--r-- | doc/architecture/blueprints/modular_monolith/hexagonal_monolith/index.md | 98 | ||||
| -rw-r--r-- | doc/architecture/blueprints/modular_monolith/index.md | 21 | ||||
| -rw-r--r-- | doc/ci/yaml/signing_examples.md | 16 | ||||
| -rw-r--r-- | doc/development/testing_guide/frontend_testing.md | 4 | ||||
| -rw-r--r-- | doc/user/packages/yarn_repository/index.md | 2 | ||||
| -rw-r--r-- | doc/user/search/index.md | 74 |
10 files changed, 247 insertions, 103 deletions
diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index c9fc446303f..f9937c0941c 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -3750,6 +3750,7 @@ Input type: `GoogleCloudLoggingConfigurationCreateInput` | <a id="mutationgooglecloudloggingconfigurationcreategoogleprojectidname"></a>`googleProjectIdName` | [`String!`](#string) | Unique identifier of the Google Cloud project to which the logging configuration belongs. | | <a id="mutationgooglecloudloggingconfigurationcreategrouppath"></a>`groupPath` | [`ID!`](#id) | Group path. | | <a id="mutationgooglecloudloggingconfigurationcreatelogidname"></a>`logIdName` | [`String`](#string) | Unique identifier used to distinguish and manage different logs within the same Google Cloud project.(defaults to `audit_events`). | +| <a id="mutationgooglecloudloggingconfigurationcreatename"></a>`name` | [`String`](#string) | Destination name. | | <a id="mutationgooglecloudloggingconfigurationcreateprivatekey"></a>`privateKey` | [`String!`](#string) | Private Key associated with the service account. This key is used to authenticate the service account and authorize it to interact with the Google Cloud Logging service. | #### Fields @@ -3791,6 +3792,7 @@ Input type: `GoogleCloudLoggingConfigurationUpdateInput` | <a id="mutationgooglecloudloggingconfigurationupdategoogleprojectidname"></a>`googleProjectIdName` | [`String`](#string) | Unique identifier of the Google Cloud project to which the logging configuration belongs. | | <a id="mutationgooglecloudloggingconfigurationupdateid"></a>`id` | [`AuditEventsGoogleCloudLoggingConfigurationID!`](#auditeventsgooglecloudloggingconfigurationid) | ID of the google Cloud configuration to update. | | <a id="mutationgooglecloudloggingconfigurationupdatelogidname"></a>`logIdName` | [`String`](#string) | Unique identifier used to distinguish and manage different logs within the same Google Cloud project. | +| <a id="mutationgooglecloudloggingconfigurationupdatename"></a>`name` | [`String`](#string) | Destination name. | | <a id="mutationgooglecloudloggingconfigurationupdateprivatekey"></a>`privateKey` | [`String`](#string) | Private Key associated with the service account. This key is used to authenticate the service account and authorize it to interact with the Google Cloud Logging service. | #### Fields @@ -7472,6 +7474,33 @@ Input type: `WorkItemExportInput` | <a id="mutationworkitemexporterrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationworkitemexportmessage"></a>`message` | [`String`](#string) | Export request result message. | +### `Mutation.workItemRemoveLinkedItems` + +Remove items linked to the work item. + +WARNING: +**Introduced** in 16.3. +This feature is an Experiment. It can be changed or removed at any time. + +Input type: `WorkItemRemoveLinkedItemsInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationworkitemremovelinkeditemsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationworkitemremovelinkeditemsid"></a>`id` | [`WorkItemID!`](#workitemid) | Global ID of the work item. | +| <a id="mutationworkitemremovelinkeditemsworkitemsids"></a>`workItemsIds` | [`[WorkItemID!]!`](#workitemid) | Global IDs of the items to unlink. Maximum number of IDs you can provide: 3. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationworkitemremovelinkeditemsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationworkitemremovelinkeditemserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationworkitemremovelinkeditemsmessage"></a>`message` | [`String`](#string) | Linked items update result message. | +| <a id="mutationworkitemremovelinkeditemsworkitem"></a>`workItem` | [`WorkItem`](#workitem) | Updated work item. | + ### `Mutation.workItemSubscribe` WARNING: @@ -16583,6 +16612,7 @@ Stores Google Cloud Logging configurations associated with IAM service accounts, | <a id="googlecloudloggingconfigurationtypegroup"></a>`group` | [`Group!`](#group) | Group the configuration belongs to. | | <a id="googlecloudloggingconfigurationtypeid"></a>`id` | [`ID!`](#id) | ID of the configuration. | | <a id="googlecloudloggingconfigurationtypelogidname"></a>`logIdName` | [`String!`](#string) | Log ID. | +| <a id="googlecloudloggingconfigurationtypename"></a>`name` | [`String!`](#string) | Name of the external destination to send audit events to. | | <a id="googlecloudloggingconfigurationtypeprivatekey"></a>`privateKey` | [`String!`](#string) | Private key. | ### `GpgSignature` diff --git a/doc/architecture/blueprints/cells/index.md b/doc/architecture/blueprints/cells/index.md index 0e93b9d5d3b..160228a99de 100644 --- a/doc/architecture/blueprints/cells/index.md +++ b/doc/architecture/blueprints/cells/index.md @@ -302,7 +302,7 @@ One iteration describes one quarter's worth of work. 1. Iteration 8 - FY25Q4 - TBD -## Technical Proposals +## Technical proposals The Cells architecture has long lasting implications to data processing, location, scalability and the GitLab architecture. This section links all different technical proposals that are being evaluated. @@ -310,6 +310,19 @@ This section links all different technical proposals that are being evaluated. - [Stateless Router That Uses a Cache to Pick Cell and Is Redirected When Wrong Cell Is Reached](proposal-stateless-router-with-buffering-requests.md) - [Stateless Router That Uses a Cache to Pick Cell and pre-flight `/api/v4/cells/learn`](proposal-stateless-router-with-routes-learning.md) +## Data pipeline ingestion + +The Cells architecture will have a significant impact on the current [data pipeline](https://about.gitlab.com/handbook/business-technology/data-team/platform/pipelines/SAAS-Gitlab-com/) which exports data from Postgres to Snowflake for the use of data analytics. This data pipeline fulfils many use cases (i.e. SAAS Service ping, Gainsight metrics and Reporting and Analytics of the SAAS Platform). + +The current data pipeline is limited by not having the possibility to get data via a CDC mechanism (which leads to data quality issues) and works by polling the Postgres database and looking for new and updated records or fully extracting data for certain tables which causes a lot of overhead. +At the moment the data pipeline runs against two instances that get created from a snapshot of both the `main` and `ci` databases. +This is done to avoid workload on the production databases. +In the Cells architecture there will be more Postgres instances because of which the current pipeline couldn't scale to pull data from all the Postgres instances. Requirements around the data pipeline moving forward are as follows: + +- We need a process that allows capturing all the CDC (insert, update and delete) from all Cells, scaling automatically with N number of Cells. +- We need to have (direct or indirect) access to database instances which allows it to do data catch up in case of major failure or root cause analysis for data anomalies. +- We need monitoring in place to alert any incident that can delay the data ingestion. + ## Impacted features The Cells architecture will impact many features requiring some of them to be rewritten, or changed significantly. diff --git a/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md b/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md index 0987b317af8..df9448309ce 100644 --- a/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md +++ b/doc/architecture/blueprints/container_registry_metadata_database_self_managed_rollout/index.md @@ -66,29 +66,46 @@ the setup and maintenance of the registry database for new and existing deploys. For the registry, we need to develop and validate import tooling which coordinates with the core import functionality which was used to migrate all -container images on GitLab.com. Additionally, we must validate that each supported -storage driver works as expected with the import process and provide estimated -import times for admins. - -We can structure our work to meet the standards outlined in support for -Experiment, Beta, and Alpha features. Doing so will help to prioritize core -functionality and to allow users who wish to be early adopters to begin using -the database and providing us with invaluable feedback. - -These levels of support could be advertised to self-managed users via a simple -chart, allowing them to tell at a glance the status of this project as it relates -to their situation. - -| Installation | GCS | AWS | Filesystem | Azure | OSS | Swift| -| ------ | ------ |------ | ------ | ------ |------ | ------ | -| Omnibus | GA | GA | Beta | Experimental | Experimental | Experimental | -| Charts | GA | GA |Beta | Experimental | Experimental | Experimental | - -### Justification of Structuring Support by Driver - -It's possible that we could simplify the proposed support matrix by structuring -it only by deployment environment and not differentiate by storage driver. The -following two sections briefly summarize several points for and against. +container images on GitLab.com. Additionally, we should provide estimated import +times for admins for each supported storage driver. + +During the beta phase, we can highlight key features of our work to provide a +quick reference for what features we have now, are planning, their statuses, and +an excutive summary of the overall state of the migration experience. +This could be advertised to self-managed users via a simple chart, allowing them +to tell at a glance the status of this project and determine if it is feature- +complete enough for their needs and level of risk tolerance. + +This should be documented in the container registry administration documentation, +rather than in this blueprint. Providing this information there will place it in +a familiar place for self-managed admins, will allow for logical cross-linking +from other sections of the same document, such as from the garbage collection +section. + +For example: + +The metadata database is in early beta for self-managed users. The core migration +process for existing registries has been implemented, and online garbage collection +is fully implemented. Certain database enabled features are only enabled for GitLab.com +and automatic database provisioning for the registry database is not available. +Please see the table below for the status of features related to the container +registry database. + +| Feature | Description | Status | Link | +| --------------------------- | ------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------- | +| Import Tool | Allows existing deployments to migrate to the database. | Completed | [Import Tool](https://gitlab.com/gitlab-org/container-registry/-/issues/884) | +| Automatic Import Validation | Tests that the import maintained data integrity of imported images. | Backlog | [Validate self-managed imports](https://gitlab.com/gitlab-org/container-registry/-/issues/938) | +| Foo Bar | Lorem ipsum dolor sit amet. | Scheduled for 16.5 | <LINK> | + +### Structuring Support by Driver + +The import operation heavily relies on the object storage driver implementation +to iterate over all registry metadata so that it can be stored in the database. +It's possible that implementation differences in the driver will make a +meaningful impact on the performance and reliability of the import process. + +The following two sections briefly summarize several points for and against +structuring support by driver. #### Arguments Opposed to Structuring Support by Driver diff --git a/doc/architecture/blueprints/modular_monolith/bounded_contexts.md b/doc/architecture/blueprints/modular_monolith/bounded_contexts.md index 0f71e24864e..8133106050d 100644 --- a/doc/architecture/blueprints/modular_monolith/bounded_contexts.md +++ b/doc/architecture/blueprints/modular_monolith/bounded_contexts.md @@ -41,11 +41,16 @@ The majority of the code is not properly namespaced and organized: In June 2023 we've started extracing gems out of the main codebase, into [`gems/` directory inside the monorepo](https://gitlab.com/gitlab-org/gitlab/-/blob/4c6e120069abe751d3128c05ade45ea749a033df/doc/development/gems.md). -This is our first step towards modularization: externalize code that can be -extracted to prevent coupling from being introduced into modules that have been -designed as separate components. +This is our first step towards modularization. -These gems as still part of the monorepo. +- We want to separate generic code from domain code (that powers the business logic). +- We want to cleanup `lib/` directory from generic code. +- We want to isolate code that could live in a separate project, to prevent it from depending on domain code. + +These gems as still part of the monorepo but could be extracted into dedicated repositories if needed. + +Extraction of gems is non blocking to modularization but the less generic code exists in `lib/` the +easier will be identifying and separating bounded context. ### 1. What makes a bounded context? @@ -103,17 +108,3 @@ With this static list we could: - Understand where to place new classes and modules. - Enforce if any top-level namespaces are used that are not in the list of bounded contexts. - Autoload non-standard Rails directories based on the given list. - -## Glossary - -- `modules` are Ruby modules and can be used to nest code hierarchically. -- `namespaces` are unique hierarchies of Ruby constants. For example, `Ci::` but also `Ci::JobArtifacts::` or `Ci::Pipeline::Chain::`. -- `packages` are Packwerk packages to group together related functionalities. These packages can be big or small depending on the design and architecture. Inside a package all constants (classes and modules) have the same namespace. For example: - - In a package `ci`, all the classes would be nested under `Ci::` namespace. There can be also nested namespaces like `Ci::PipelineProcessing::`. - - In a package `ci-pipeline_creation` all classes are nested under `Ci::PipelineCreation`, like `Ci::PipelineCreation::Chain::Command`. - - In a package `ci` a class named `MergeRequests::UpdateHeadPipelineService` would not be allowed because it would not match the package's namespace. - - This can be enforced easily with [Packwerk's based Rubocop Cops](https://github.com/rubyatscale/rubocop-packs/blob/main/lib/rubocop/cop/packs/root_namespace_is_pack_name.rb). -- `bounded context` is a top-level Packwerk package that represents a macro aspect of the domain. For example: `Ci::`, `MergeRequests::`, `Packages::`, etc. - - A bounded context is represented by a single Ruby module/namespace. For example, `Ci::` and not `Ci::JobArtifacts::`. - - A bounded context can be made of 1 or multiple Packwerk packages. Nested packages would be recommended if the domain is quite complex and we want to enforce privacy among all the implementation details. For example: `Ci::PipelineProcessing::` and `Ci::PipelineCreation::` could be separate packages of the same bounded context and expose their public API while keeping implementation details private. - - A new bounded context like `RemoteDevelopment::` can be represented a single package while large and complex bounded contexts like `Ci::` would need to be organized into smaller/nested packages. diff --git a/doc/architecture/blueprints/modular_monolith/hexagonal_monolith/index.md b/doc/architecture/blueprints/modular_monolith/hexagonal_monolith/index.md index eb4b428cf52..f0f689d48ca 100644 --- a/doc/architecture/blueprints/modular_monolith/hexagonal_monolith/index.md +++ b/doc/architecture/blueprints/modular_monolith/hexagonal_monolith/index.md @@ -25,12 +25,22 @@ Use [Packwerk](https://github.com/Shopify/packwerk) to enforce privacy and depen ## Details +```mermaid +flowchart TD + u([User]) -- interacts directly with --> AA[Application Adapter: WebUI, REST, GraphQL, git, ...] + AA --uses abstractions from--> D[Application Domain] + AA -- depends on --> Platform + D -- depends on --> Platform[Platform: gems, configs, framework, ...] +``` + ### Application domain -The application core (functional domains) is divided into separate top-level bounded contexts called after the -[feature category](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml) they represent. +The application core (functional domains) is composed of all the code that describes the business logic, policies and data +that is unique to GitLab product. +It is divided into separate top-level [bounded contexts](../bounded_contexts.md). A bounded-context is represented in the form of a Ruby module. -This follows the existing [guideline on naming namespaces](../../../../development/software_design.md#use-namespaces-to-define-bounded-contexts) but puts more structure to it. +This follows the existing [guideline on naming namespaces](../../../../development/software_design.md#use-namespaces-to-define-bounded-contexts) +but puts more structure to it. Modules should: @@ -52,6 +62,12 @@ If a feature category is only relevant in the context of a parent feature catego parent's bounded context. For example: Build artifacts existing in the context of Continuous Integration feature category and they may be merged under a single bounded context. +The application domain has no knowledge of outer layers like the application adapters and only depends on the +platform code. This makes the domain code to be the SSoT of the business logic, be reusable and testable regardless +whether the request came from the WebUI or REST API. + +If a dependency between an outer layer and an inner layer is required (domain code depending on the interface of an adapter), this can be solved using inversion of control techniques, especially dependency injection. + ### Application adapters >>> @@ -67,9 +83,14 @@ Application adapters would be: - Web UI (Rails controllers, view, JS and Vue client) - REST API endpoints - GraphQL Endpoints -- Action Cable -TODO: continue describing how adapters are organized and why they are separate from the domain code. +They are responsible for the interaction with the user. Each adapter should interpret the request, parse parameters +and invoke the right abstraction from the application domain, then present the result back to the user. + +Presentation logic, and possibly authentication, would be specific to the adapters layer. + +The application adapters layer depends on the platform code to run: the Rails framework, the gems that power the adapter, +the configurations and utilities. ### Platform code @@ -95,19 +116,76 @@ This means that aside from the Rails framework code, the rest of the platform co Eventually all code inside `gems/` could potentially be extracted in a separate repository or open sourced. Placing platform code inside `gems/` makes it clear that its purpose is to serve the application code. -### Why Packwerk? +### Enforcing boundaries + +Ruby does not have the concept of privacy of constants in a given module. Unlike other programming languages, even extracting +well documented gems doesn't prevent other developers from coupling code to implementation details because all constants +are public in Ruby. + +We can have a codebase perfectly organized in an hexagonal architecture but still having the application domain, the biggest +part of the codebase, being a non modularized [big ball of mud](https://en.wikipedia.org/wiki/Big_ball_of_mud). + +Enforcing boundaries is also vital to maintaining the structure long term. We don't want that after a big modularization +effort we slowly fall back into a big ball of mud gain by violating the boundaries. + +We explored the idea of [using Packwerk in a proof of concept](../proof_of_concepts.md#use-packwerk-to-enforce-module-boundaries) +to enforce module boundaries. -TODO: +[Packwerk](https://github.com/Shopify/packwerk) is a static analyzer that allows to gradually introduce packages in the +codebase and enforce privacy and explicit dependencies. Packwerk can detect if some Ruby code is using private implementation +details of another package or if it's using a package that wasn't declared explicitly as a dependency. -- boundaries not enforced at runtime. Ruby code will still work as being all loaded in the same memory space. -- can be introduced incrementally. Not everything requires to be moved to packs for the Rails autoloader to work. +Being a static analyzer it does not affect code execution, meaning that introducing Packwerk is safe and can be done +gradually. Companies like Gusto have been developing and maintaining a list of [development and engineering tools](https://github.com/rubyatscale) for organizations that want to move to using a Rails modular monolith around Packwerk. ### EE and JH extensions -TODO: +One of the unique challenges of modularizing the GitLab codebase is the presence of EE extensions (managed by GitLab) +and JH extensions (managed by JiHu). + +By moving related domain code (e.g. `Ci::`) under the same bounded context and Packwerk package, we would also need to +move `ee/` extensions in it. + +To have top-level bounded contexts to also match Packwerk packages it means that all code related to a specific domain +needs to be placed under the same package directory, including EE extensions, for example. + +The following is just an example of a possible directory structure: + +```shell +domains +├── ci +│ ├── package.yml # package definition. +│ ├── packwerk.yml # tool configurations for this package. +│ ├── package_todo.yml # existing violations. +│ ├── core # Core features available in Community Edition and always autoloaded. +│ │ ├── app +│ │ │ ├── models/... +│ │ │ ├── services/... +│ │ │ └── lib/... # domain-specific `lib` moved inside `app` together with other classes. +│ │ └── spec +│ │ └── models/... +│ ├── ee # EE extensions specific to the bounded context, conditionally autoloaded. +│ │ ├── models/... +│ │ └── spec +│ │ └── models/... +│ └── public # Public constants are placed here so they can be referenced by other packages. +│ ├── core +│ │ ├── app +│ │ │ └── models/... +│ │ └── spec +│ │ └── models/... +│ └── ee +│ ├── app +│ │ └── models/... +│ └── spec +│ └── models/... +├── merge_requests/ +├── repositories/ +└── ... +``` ## Challenges diff --git a/doc/architecture/blueprints/modular_monolith/index.md b/doc/architecture/blueprints/modular_monolith/index.md index ef50be643a6..f1e6c119552 100644 --- a/doc/architecture/blueprints/modular_monolith/index.md +++ b/doc/architecture/blueprints/modular_monolith/index.md @@ -93,12 +93,11 @@ There are many aspects and details required to make modularization of our monolith successful. We will work on the aspects listed below, refine them, and add more important details as we move forward towards the goal: -1. [Deliver modularization proof-of-concepts that will deliver key insights](proof_of_concepts.md) -1. [Align modularization plans to the organizational structure](bounded_contexts.md) +1. [Deliver modularization proof-of-concepts that will deliver key insights](proof_of_concepts.md). +1. Align modularization plans to the organizational structure by [defining bounded contexts](bounded_contexts.md). +1. Separate domains into modules that will reflect organizational structure (TODO) 1. Start a training program for team members on how to work with decoupled domains (TODO) 1. Build tools that will make it easier to build decoupled domains through inversion of control (TODO) -1. Separate domains into modules that will reflect organizational structure (TODO) -1. Build necessary services to align frontend and backend modularization (TODO) 1. [Introduce hexagonal architecture within the monolith](hexagonal_monolith/index.md) 1. Introduce clean architecture with one-way-dependencies and host application (TODO) 1. Build abstractions that will make it possible to run and deploy domains separately (TODO) @@ -107,6 +106,20 @@ add more important details as we move forward towards the goal: In progress. +## Glossary + +- `modules` are Ruby modules and can be used to nest code hierarchically. +- `namespaces` are unique hierarchies of Ruby constants. For example, `Ci::` but also `Ci::JobArtifacts::` or `Ci::Pipeline::Chain::`. +- `packages` are Packwerk packages to group together related functionalities. These packages can be big or small depending on the design and architecture. Inside a package all constants (classes and modules) have the same namespace. For example: + - In a package `ci`, all the classes would be nested under `Ci::` namespace. There can be also nested namespaces like `Ci::PipelineProcessing::`. + - In a package `ci-pipeline_creation` all classes are nested under `Ci::PipelineCreation`, like `Ci::PipelineCreation::Chain::Command`. + - In a package `ci` a class named `MergeRequests::UpdateHeadPipelineService` would not be allowed because it would not match the package's namespace. + - This can be enforced easily with [Packwerk's based Rubocop Cops](https://github.com/rubyatscale/rubocop-packs/blob/main/lib/rubocop/cop/packs/root_namespace_is_pack_name.rb). +- `bounded context` is a top-level Packwerk package that represents a macro aspect of the domain. For example: `Ci::`, `MergeRequests::`, `Packages::`, etc. + - A bounded context is represented by a single Ruby module/namespace. For example, `Ci::` and not `Ci::JobArtifacts::`. + - A bounded context can be made of 1 or multiple Packwerk packages. Nested packages would be recommended if the domain is quite complex and we want to enforce privacy among all the implementation details. For example: `Ci::PipelineProcessing::` and `Ci::PipelineCreation::` could be separate packages of the same bounded context and expose their public API while keeping implementation details private. + - A new bounded context like `RemoteDevelopment::` can be represented a single package while large and complex bounded contexts like `Ci::` would need to be organized into smaller/nested packages. + ## References [List of references](references.md) diff --git a/doc/ci/yaml/signing_examples.md b/doc/ci/yaml/signing_examples.md index 72e007a749f..4c880d4be05 100644 --- a/doc/ci/yaml/signing_examples.md +++ b/doc/ci/yaml/signing_examples.md @@ -7,12 +7,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Use Sigstore for keyless signing and verification **(FREE SAAS)** The [Sigstore](https://www.sigstore.dev/) project provides a CLI called -[Cosign](https://docs.sigstore.dev/cosign/overview/) which can be used for keyless signing of container images built +[Cosign](https://docs.sigstore.dev/signing/quickstart/) which can be used for keyless signing of container images built with GitLab CI/CD. Keyless signing has many advantages, including eliminating the need to manage, safeguard, and rotate a private key. Cosign requests a short-lived key pair to use for signing, records it on a certificate transparency log, and then discards it. The key is generated through a token obtained from the GitLab server using the OIDC identity of the user who ran the pipeline. This token includes unique claims that certify the token was generated by a CI/CD pipeline. To learn more, -see Cosign [documentation](https://docs.sigstore.dev/cosign/overview/#example-working-with-containers) on keyless signatures. +see Cosign [documentation](https://docs.sigstore.dev/signing/quickstart/#example-working-with-containers) on keyless signatures. For details on the mapping between GitLab OIDC claims and Fulcio certificate extensions, see the GitLab column of [Mapping OIDC token claims to Fulcio OIDs](https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md#mapping-oidc-token-claims-to-fulcio-oids). @@ -36,11 +36,11 @@ You can use Cosign to sign and verify container images and build artifacts. - When signing container images, sign the digest (which is immutable) instead of the tag. GitLab [ID tokens](../secrets/id_token_authentication.md#id-tokens) can be used by Cosign for -[keyless signing](https://docs.sigstore.dev/cosign/overview/). The token must have +[keyless signing](https://docs.sigstore.dev/signing/quickstart/). The token must have `sigstore` set as the [`aud`](../secrets/id_token_authentication.md#token-payload) claim. The token can be used by Cosign automatically when it is set in the `SIGSTORE_ID_TOKEN` environment variable. -To learn more about how to install Cosign, see [Cosign Installation documentation](https://docs.sigstore.dev/cosign/installation/). +To learn more about how to install Cosign, see [Cosign Installation documentation](https://docs.sigstore.dev/system_config/installation/). ### Signing @@ -49,7 +49,7 @@ To learn more about how to install Cosign, see [Cosign Installation documentatio The example below demonstrates how to sign a container image in GitLab CI. The signature is automatically stored in the same container repository as the image. -To learn more about signing containers, see [Cosign Signing Containers documentation](https://docs.sigstore.dev/cosign/signing_with_containers/). +To learn more about signing containers, see [Cosign Signing Containers documentation](https://docs.sigstore.dev/signing/signing_with_containers/). ```yaml build_and_sign_image: @@ -77,7 +77,7 @@ build_and_sign_image: The example below demonstrates how to sign a build artifact in GitLab CI. You should save the `cosign.bundle` file produced by `cosign sign-blob`, which is used for signature verification. -To learn more about signing artifacts, see [Cosign Signing Blobs documentation](https://docs.sigstore.dev/cosign/signing_with_blobs/#keyless-signing-of-blobs-and-files). +To learn more about signing artifacts, see [Cosign Signing Blobs documentation](https://docs.sigstore.dev/signing/signing_with_blobs/). ```yaml build_and_sign_artifact: @@ -109,7 +109,7 @@ build_and_sign_artifact: | `--certificate-oidc-issuer` | The GitLab instance URL where the image/artifact was signed. For example, `https://gitlab.com`. | | `--bundle` | The `bundle` file produced by `cosign sign-blob`. Only used for verifying build artifacts. | -To learn more about verifying signed images/artifacts, see [Cosign Verifying documentation](https://docs.sigstore.dev/cosign/verify/#keyless-verification-using-openid-connect). +To learn more about verifying signed images/artifacts, see [Cosign Verifying documentation](https://docs.sigstore.dev/verifying/verify/). #### Container images @@ -149,7 +149,7 @@ You can use Sigstore and npm, together with GitLab CI/CD, to digitally sign buil ### About npm provenance -[npm CLI](https://docs.npmjs.com/cli) allows package maintainers to provide users with provenance attestations. Using npm +[npm CLI](https://docs.npmjs.com/cli/) allows package maintainers to provide users with provenance attestations. Using npm CLI provenance generation allows users to trust and verify that the package they are downloading and using is from you and the build system that built it. diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 8da4350074d..3800e22b2f9 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -51,7 +51,7 @@ The default timeout for Jest is set in If your test exceeds that time, it fails. If you cannot improve the performance of the tests, you can increase the timeout -for the whole suite using [`jest.setTimeout`](https://jestjs.io/docs/28.x/jest-object#jestsettimeouttimeout) +for the whole suite using [`jest.setTimeout`](https://jestjs.io/docs/next/jest-object#jestsettimeouttimeout) ```javascript jest.setTimeout(500); @@ -63,7 +63,7 @@ describe('Component', () => { }); ``` -or for a specific test by providing a third argument to [`it`](https://jestjs.io/docs/28.x/api#testname-fn-timeout) +or for a specific test by providing a third argument to [`it`](https://jestjs.io/docs/next/api#testname-fn-timeout) ```javascript describe('Component', () => { diff --git a/doc/user/packages/yarn_repository/index.md b/doc/user/packages/yarn_repository/index.md index 262e15fe240..850b2bb02d5 100644 --- a/doc/user/packages/yarn_repository/index.md +++ b/doc/user/packages/yarn_repository/index.md @@ -301,7 +301,7 @@ Then you can use `yarn add` to install your packages. ## Related topics - [npm documentation](../npm_registry/index.md#helpful-hints) -- [Yarn Migration Guide](https://yarnpkg.com/getting-started/migration) +- [Yarn Migration Guide](https://yarnpkg.com/migration/guide/) ## Troubleshooting diff --git a/doc/user/search/index.md b/doc/user/search/index.md index c2813cf6a61..84d469b06ec 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -67,35 +67,18 @@ To search in a project: The results are displayed. To filter the results, on the left sidebar, select a filter. -## Search for code - -To search for code in a project: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. -1. Select **Search GitLab** (**{search}**) again and type the code you want to search for. -1. Press <kbd>Enter</kbd> to search, or select from the list. - -Code search shows only the first result in the file. -To search for code in all GitLab, ask your administrator to enable [advanced search](advanced_search.md). - -### View Git blame from code search - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327052) in GitLab 14.7. - -After you find search results, you can view who made the last change to the line -where the results were found. - -1. From the code search result, hover over the line number. -1. On the left, select **View blame**. +## Search for a project by full path -### Filter code search results by language +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342651) in GitLab 15.10. +You can search for a project by entering its full path (including the namespace it belongs to) in the search box. +As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed. -To filter code search results by one or more languages: +For example: -1. On the code search page, on the left sidebar, select one or more languages. -1. On the left sidebar, select **Apply**. +- `gitlab-org/gitlab` searches for the `gitlab` project in the `gitlab-org` namespace. +- `gitlab-org/` displays autocomplete suggestions for projects that belong to the `gitlab-org` namespace. ## Include archived projects in search results @@ -103,7 +86,7 @@ To filter code search results by one or more languages: > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/413821) in GitLab 16.3. Feature flag `search_projects_hide_archived` removed. By default, archived projects are excluded from search results. -To include archived projects in search results: +To include archived projects: 1. On the project search page, on the left sidebar, select the **Include archived** checkbox. 1. On the left sidebar, select **Apply**. @@ -116,22 +99,41 @@ FLAG: On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `search_issues_hide_archived_projects`. On GitLab.com, this feature is not available. -Issues in archived projects are included in search results by default. To exclude issues in archived projects, ensure the `search_issues_hide_archived_projects` flag is enabled. +By default, issues in archived projects are included in search results. +To exclude issues in archived projects, ensure the `search_issues_hide_archived_projects` flag is enabled. -To include issues in archived projects with `search_issues_hide_archived_projects` enabled, you must add the parameter `include_archived=true` to the URL. +To include issues in archived projects with `search_issues_hide_archived_projects` enabled, +you must add the parameter `include_archived=true` to the URL. -## Search for a project by full path +## Search for code -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/108906) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `full_path_project_search`. Disabled by default. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/114932) in GitLab 15.11. Feature flag `full_path_project_search` removed. +To search for code in a project: -You can search for a project by entering its full path (including the namespace it belongs to) in the search box. -As you type the project path, [autocomplete suggestions](#autocomplete-suggestions) are displayed. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Search GitLab** (**{search}**) again and type the code you want to search for. +1. Press <kbd>Enter</kbd> to search, or select from the list. -For example: +Code search shows only the first result in the file. +To search for code in all GitLab, ask your administrator to enable [advanced search](advanced_search.md). -- `gitlab-org/gitlab` searches for the `gitlab` project in the `gitlab-org` namespace. -- `gitlab-org/` displays autocomplete suggestions for projects that belong to the `gitlab-org` namespace. +### View Git blame from code search + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327052) in GitLab 14.7. + +After you find search results, you can view who made the last change to the line +where the results were found. + +1. From the code search result, hover over the line number. +1. On the left, select **View blame**. + +### Filter code search results by language + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/342651) in GitLab 15.10. + +To filter code search results by one or more languages: + +1. On the code search page, on the left sidebar, select one or more languages. +1. On the left sidebar, select **Apply**. ## Search for a commit SHA |