diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index cbaa648570c..157e2f042e7 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -338,7 +338,57 @@ export const gqClient = createGqClient( ); ``` -### Feature flags in queries +### Working on GraphQL-based features when frontend and backend are not in sync + +Any feature that requires GraphQL queries/mutations to be created or updated should be carefully +planned. Frontend and backend counterparts should agree on a schema that satisfies both client-side and +server-side requirements. This enables both departments to start implementing their parts without +blocking each other. + +Ideally, the backend implementation should be done prior to the frontend so that the client can +immediately start querying the API with minimal back and forth between departments. However, we +recognize that priorities don't always align. For the sake of iteration and +delivering work we're committed to, it might be necessary for the frontend to be implemented ahead +of the backend. + +#### Implementing frontend queries and mutations ahead of the backend + +In such case, the frontend will define GraphQL schemas or fields that do not correspond to any +backend resolver yet. This is fine as long as the implementation is properly feature-flagged so it +does not translate to public-facing errors in the product. However, we do validate client-side +queries/mutations against the backend GraphQL schema with the `graphql-verify` CI job. +You must confirm your changes pass the validation if they are to be merged before the +backend actually supports them. Below are a few suggestions to go about this. + +##### Using the `@client` directive + +The preferred approach is to use the `@client` directive on any new query, mutation, or field that +isn't yet supported by the backend. Any entity with the directive is skipped by the +`graphql-verify` validation job. + +Additionally Apollo will attempt to resolve them client-side, which can be used in conjunction with +[Mocking API response with local Apollo cache](#mocking-api-response-with-local-apollo-cache). This +provides a convenient way of testing your feature with fake data defined client-side. +When opening a merge request for your changes, it can be a good idea to provide local resolvers as a +patch that reviewers can apply in their GDK to easily smoke-test your work. + +Make sure to track the removal of the directive in a follow-up issue, or as part of the backend +implementation plan. + +##### Adding an exception to the list of known failures + +GraphQL queries/mutations validation can be completely turned off for specific files by adding their +paths to the +[`config/known_invalid_graphql_queries.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/known_invalid_graphql_queries.yml) +file, much like you would disable ESLint for some files via an `.eslintignore` file. +Bear in mind that any file listed in here will not be validated at all. So if you're only adding +fields to an existing query, use the `@client` directive approach so that the rest of the query +is still validated. + +Again, make sure that those overrides are as short-lived as possible by tracking their removal in +the appropriate issue. + +#### Feature flags in queries Sometimes it may be useful to have an entity in the GraphQL query behind a feature flag. For example, when working on a feature where the backend has already been merged but the frontend diff --git a/doc/user/admin_area/img/license_details.png b/doc/user/admin_area/img/license_details.png deleted file mode 100644 index 3e980d9316d..00000000000 Binary files a/doc/user/admin_area/img/license_details.png and /dev/null differ diff --git a/doc/user/admin_area/img/license_details_v13_8.png b/doc/user/admin_area/img/license_details_v13_8.png new file mode 100644 index 00000000000..dc12649fbe9 Binary files /dev/null and b/doc/user/admin_area/img/license_details_v13_8.png differ diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index d06b0c844ec..4a594e12434 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -92,7 +92,7 @@ functionality. You can review the license details at any time in the **License** section of the **Admin Area**. -![License details](img/license_details.png) +![License details](img/license_details_v13_8.png) ## Notification before the license expires diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index 0ae038924ec..001d0aa9061 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -156,6 +156,19 @@ To override a job definition, (for example, change properties like `variables` o declare a job with the same name as the SAST job to override. Place this new job after the template inclusion and specify any additional keys under it. +WARNING: +Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) +is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. + +#### GIT_DEPTH + +The [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) affects Secret Detection. +The Secret Detection analyzer relies on generating patches between commits to scan content for +secrets. If you override the default, ensure the value is greater than 1. If the number of commits +in an MR is greater than the GIT_DEPTH value, Secret Detection will [fail to detect secrets](#error-couldnt-run-the-gitleaks-command-exit-status-2). + +#### Custom settings example + In the following example, we include the Secret Detection template and at the same time we override the `secret_detection` job with the `SECRET_DETECTION_HISTORIC_SCAN` variable to `true`: @@ -171,10 +184,6 @@ secret_detection: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable takes precedence. -WARNING: -Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#onlyexcept-basic) -is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead. - #### Available variables Secret Detection can be customized by defining available variables: @@ -331,11 +340,15 @@ For information on this, see the [general Application Security troubleshooting s ### Error: `Couldn't run the gitleaks command: exit status 2` -This error is usually caused by the `GIT_DEPTH` value of 50 that is set for all [projects by default](../../../ci/pipelines/settings.md#git-shallow-clone). +If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable +is set to 50 (a [project default](../../../ci/pipelines/settings.md#git-shallow-clone)), +the Secret Detection job fails as the clone is not deep enough to contain all of the +relevant commits. -For example, if a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` is set to 50, the Secret Detection job fails as the clone is not deep enough to contain all of the relevant commits. - -You can confirm this to be the cause of the error by implementing a [logging level](../../application_security/secret_detection/index.md#logging-level) of `debug`. Once implemented, the logs should look similar to the following example, wherein an "object not found" error can be seen: +To confirm this as the cause of the error, set the +[logging level](../../application_security/secret_detection/index.md#logging-level) to `debug`, then +rerun the pipeline. The logs should look similar to the following example. The text "object not +found" is a symptom of this error. ```plaintext ERRO[2020-11-18T18:05:52Z] object not found @@ -343,7 +356,9 @@ ERRO[2020-11-18T18:05:52Z] object not found [ERRO] [secrets] [2020-11-18T18:05:52Z] ▶ Gitleaks analysis failed: exit status 2 ``` -If this is the case, we can resolve the issue by setting the [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) to a higher value. In order to apply this only to the Secret Detection job, the following can be added to your `.gitlab-ci.yml`: +To resolve the issue, set the [`GIT_DEPTH` variable](../../../ci/runners/README.md#shallow-cloning) +to a higher value. To apply this only to the Secret Detection job, the following can be added to +your `.gitlab-ci.yml` file: ```yaml secret_detection: diff --git a/locale/gitlab.pot b/locale/gitlab.pot index 40accd34767..99d0136630f 100644 --- a/locale/gitlab.pot +++ b/locale/gitlab.pot @@ -4448,7 +4448,7 @@ msgstr "" msgid "Billing" msgstr "" -msgid "BillingPlans|%{group_name} is currently using the %{plan_name} plan." +msgid "BillingPlans|%{group_name} is currently using the %{plan_name}." msgstr "" msgid "BillingPlans|@%{user_name} you are currently using the %{plan_name} plan."