diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-18 15:10:41 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-18 15:10:41 +0300 |
commit | f23a9a17ed6237c346d2e9210c6841e319e8d030 (patch) | |
tree | 7b46c0ff193c445f35774a86ec3d0ff000d2ff77 /doc | |
parent | d7432b66ff241af3f39d82da581832a084983378 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/graphql/img/users_query_example_v13_8.png | bin | 0 -> 200017 bytes | |||
-rw-r--r-- | doc/api/graphql/reference/gitlab_schema.graphql | 120 | ||||
-rw-r--r-- | doc/api/graphql/reference/gitlab_schema.json | 219 | ||||
-rw-r--r-- | doc/api/graphql/reference/index.md | 27 | ||||
-rw-r--r-- | doc/api/graphql/users_example.md | 109 | ||||
-rw-r--r-- | doc/api/users.md | 1 | ||||
-rw-r--r-- | doc/user/admin_area/settings/user_and_ip_rate_limits.md | 16 | ||||
-rw-r--r-- | doc/user/gitlab_com/index.md | 17 |
8 files changed, 501 insertions, 8 deletions
diff --git a/doc/api/graphql/img/users_query_example_v13_8.png b/doc/api/graphql/img/users_query_example_v13_8.png Binary files differnew file mode 100644 index 00000000000..b4c2b4e999a --- /dev/null +++ b/doc/api/graphql/img/users_query_example_v13_8.png diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql index 3c82e19e3c5..26f0cd705c6 100644 --- a/doc/api/graphql/reference/gitlab_schema.graphql +++ b/doc/api/graphql/reference/gitlab_schema.graphql @@ -743,6 +743,106 @@ enum AlertManagementIntegrationType { } """ +Field that are available while modifying the custom mapping attributes for an HTTP integration +""" +input AlertManagementPayloadAlertFieldInput { + """ + A GitLab alert field name. + """ + fieldName: AlertManagementPayloadAlertFieldName! + + """ + Human-readable label of the payload path. + """ + label: String + + """ + Path to value inside payload JSON. + """ + path: [String!]! + + """ + Type of the parsed value. + """ + type: AlertManagementPayloadAlertFieldType! +} + +""" +Values for alert field names used in the custom mapping +""" +enum AlertManagementPayloadAlertFieldName { + """ + A high-level summary of the problem. + """ + DESCRIPTION + + """ + The resolved time of the incident. + """ + END_TIME + + """ + The unique identifier of the alert. This can be used to group occurrences of the same alert. + """ + FINGERPRINT + + """ + The name of the associated GitLab environment. + """ + GITLAB_ENVIRONMENT_NAME + + """ + One or more hosts, as to where this incident occurred. + """ + HOSTS + + """ + The name of the associated monitoring tool. + """ + MONITORING_TOOL + + """ + The affected service. + """ + SERVICE + + """ + The severity of the alert. + """ + SEVERITY + + """ + The time of the incident. + """ + START_TIME + + """ + The title of the incident. + """ + TITLE +} + +""" +Values for alert field types used in the custom mapping +""" +enum AlertManagementPayloadAlertFieldType { + """ + Array field type + """ + ARRAY + + """ + DateTime field type + """ + DATETIME + + """ + String field type + """ + STRING +} + +""" An endpoint and credentials used to accept Prometheus alerts for a project """ type AlertManagementPrometheusIntegration implements AlertManagementIntegration { @@ -11317,6 +11417,16 @@ input HttpIntegrationCreateInput { name: String! """ + The custom mapping of GitLab alert attributes to fields from the payload_example. + """ + payloadAttributeMappings: [AlertManagementPayloadAlertFieldInput!] + + """ + The example of an alert payload. + """ + payloadExample: JsonString + + """ The project to create the integration in. """ projectPath: ID! @@ -13532,6 +13642,11 @@ enum JobArtifactFileType { TRACE } +""" +JSON object as raw string +""" +scalar JsonString + type Label { """ Background color of the label @@ -20367,6 +20482,11 @@ type Query { """ users( """ + Return only admin users. + """ + admins: Boolean = false + + """ Returns the elements in the list that come after the specified cursor. """ after: String diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index e872ecf8ad8..625892f3d97 100644 --- a/doc/api/graphql/reference/gitlab_schema.json +++ b/doc/api/graphql/reference/gitlab_schema.json @@ -1910,6 +1910,177 @@ "possibleTypes": null }, { + "kind": "INPUT_OBJECT", + "name": "AlertManagementPayloadAlertFieldInput", + "description": "Field that are available while modifying the custom mapping attributes for an HTTP integration", + "fields": null, + "inputFields": [ + { + "name": "fieldName", + "description": "A GitLab alert field name.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "AlertManagementPayloadAlertFieldName", + "ofType": null + } + }, + "defaultValue": null + }, + { + "name": "path", + "description": "Path to value inside payload JSON.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + } + } + }, + "defaultValue": null + }, + { + "name": "label", + "description": "Human-readable label of the payload path.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "type", + "description": "Type of the parsed value.", + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "AlertManagementPayloadAlertFieldType", + "ofType": null + } + }, + "defaultValue": null + } + ], + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "AlertManagementPayloadAlertFieldName", + "description": "Values for alert field names used in the custom mapping", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "TITLE", + "description": "The title of the incident.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DESCRIPTION", + "description": "A high-level summary of the problem.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "START_TIME", + "description": "The time of the incident.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "END_TIME", + "description": "The resolved time of the incident.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "SERVICE", + "description": "The affected service.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "MONITORING_TOOL", + "description": "The name of the associated monitoring tool.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "HOSTS", + "description": "One or more hosts, as to where this incident occurred.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "SEVERITY", + "description": "The severity of the alert.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "FINGERPRINT", + "description": "The unique identifier of the alert. This can be used to group occurrences of the same alert.", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "GITLAB_ENVIRONMENT_NAME", + "description": "The name of the associated GitLab environment.", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { + "kind": "ENUM", + "name": "AlertManagementPayloadAlertFieldType", + "description": "Values for alert field types used in the custom mapping", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": [ + { + "name": "ARRAY", + "description": "Array field type", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "DATETIME", + "description": "DateTime field type", + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "STRING", + "description": "String field type", + "isDeprecated": false, + "deprecationReason": null + } + ], + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "AlertManagementPrometheusIntegration", "description": "An endpoint and credentials used to accept Prometheus alerts for a project", @@ -30958,6 +31129,34 @@ "defaultValue": null }, { + "name": "payloadExample", + "description": "The example of an alert payload.", + "type": { + "kind": "SCALAR", + "name": "JsonString", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "payloadAttributeMappings", + "description": "The custom mapping of GitLab alert attributes to fields from the payload_example.", + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "INPUT_OBJECT", + "name": "AlertManagementPayloadAlertFieldInput", + "ofType": null + } + } + }, + "defaultValue": null + }, + { "name": "clientMutationId", "description": "A unique identifier for the client performing the mutation.", "type": { @@ -37236,6 +37435,16 @@ "possibleTypes": null }, { + "kind": "SCALAR", + "name": "JsonString", + "description": "JSON object as raw string", + "fields": null, + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": null + }, + { "kind": "OBJECT", "name": "Label", "description": null, @@ -59245,6 +59454,16 @@ "defaultValue": null }, { + "name": "admins", + "description": "Return only admin users.", + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "defaultValue": "false" + }, + { "name": "after", "description": "Returns the elements in the list that come after the specified cursor.", "type": { diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 70b6a29f1ed..72c38f67773 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -4254,6 +4254,33 @@ Values of types of integrations. | `HTTP` | Integration with any monitoring tool | | `PROMETHEUS` | Prometheus integration | +### AlertManagementPayloadAlertFieldName + +Values for alert field names used in the custom mapping. + +| Value | Description | +| ----- | ----------- | +| `DESCRIPTION` | A high-level summary of the problem. | +| `END_TIME` | The resolved time of the incident. | +| `FINGERPRINT` | The unique identifier of the alert. This can be used to group occurrences of the same alert. | +| `GITLAB_ENVIRONMENT_NAME` | The name of the associated GitLab environment. | +| `HOSTS` | One or more hosts, as to where this incident occurred. | +| `MONITORING_TOOL` | The name of the associated monitoring tool. | +| `SERVICE` | The affected service. | +| `SEVERITY` | The severity of the alert. | +| `START_TIME` | The time of the incident. | +| `TITLE` | The title of the incident. | + +### AlertManagementPayloadAlertFieldType + +Values for alert field types used in the custom mapping. + +| Value | Description | +| ----- | ----------- | +| `ARRAY` | Array field type | +| `DATETIME` | DateTime field type | +| `STRING` | String field type | + ### AlertManagementSeverity Alert severity values. diff --git a/doc/api/graphql/users_example.md b/doc/api/graphql/users_example.md new file mode 100644 index 00000000000..e4a697d11fd --- /dev/null +++ b/doc/api/graphql/users_example.md @@ -0,0 +1,109 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Query users with GraphQL + +This page describes how you can use the GraphiQL explorer to query users. + +You can run the same query directly via a HTTP endpoint, using `cURL`. For more information, see our +guidance on getting started from the [command line](getting_started.md#command-line). + +The [example users query](#set-up-the-graphiql-explorer) looks for a subset of users in +o +a GitLab instance either by username or +[Global ID](../../development/api_graphql_styleguide.md#global-ids). +The query includes: + +- [`pageInfo`](#pageinfo) +- [`nodes`](#nodes) + +## pageInfo + +This contains the data needed to implement pagination. GitLab uses cursor-based +[pagination](getting_started.md#pagination). For more information, see +[Pagination](https://graphql.org/learn/pagination/) in the GraphQL documentation. + +## nodes + +In a GraphQL query, `nodes` is used to represent a collection of [`nodes` on a graph](https://en.wikipedia.org/wiki/Vertex_(graph_theory)). +In this case, the collection of nodes is a collection of `User` objects. For each one, +we output: + +- Their user's `id`. +- The `membership` fragment, which represents a Project or Group membership belonging + to that user. Outputting a fragment is denoted with the `...memberships` notation. + +The GitLab GraphQL API is extensive and a large amount of data for a wide variety of entities can be output. +See the official [reference documentation](reference/index.md) for the most up-to-date information. + +## Set up the GraphiQL explorer + +This procedure presents a substantive example that you can copy and paste into GraphiQL +explorer. GraphiQL explorer is available for: + +- GitLab.com users at [https://gitlab.com/-/graphql-explorer](https://gitlab.com/-/graphql-explorer). +- Self-managed users at `https://gitlab.example.com/-/graphql-explorer`. + +1. Copy the following code excerpt: + + ```graphql + { + users(usernames: ["user1", "user3", "user4"]) { + pageInfo { + endCursor + startCursor + hasNextPage + } + nodes { + id + username, + publicEmail + location + webUrl + userPermissions { + createSnippet + } + } + } + } + ``` + +1. Open the [GraphiQL explorer tool](https://gitlab.com/-/graphql-explorer). +1. Paste the `query` listed above into the left window of your GraphiQL explorer tool. +1. Click Play to get the result shown here: + +![GraphiQL explorer search for boards](img/users_query_example_v13_8.png) + +NOTE: +[The GraphQL API returns a GlobalID, rather than a standard ID.](getting_started.md#queries-and-mutations) It also expects a GlobalID as an input rather than +a single integer. + +This GraphQL query returns the specified information for the three users with the listed username. Since the GraphiQL explorer uses the session token to authorize access to resources, +the output is limited to the projects and groups accessible to the currently signed-in user. + +If you've signed in as an instance administrator, you would have access to all records, regardless of ownership. + +If you are signed in as an administrator, you can show just the matching administrators on the instance by adding the `admins: true` parameter to the query changing the second line to: + +```graphql + users(usernames: ["user1", "user3", "user4"], admins: true) { + ... + } +``` + +Or you can just get all of the administrators: + +```graphql + users(admins: true) { + ... + } +``` + +For more information on: + +- GraphQL specific entities, such as Fragments and Interfaces, see the official + [GraphQL documentation](https://graphql.org/learn/). +- Individual attributes, see the [GraphQL API Resources](reference/index.md). diff --git a/doc/api/users.md b/doc/api/users.md index f8b752f47e1..ecfd8e26626 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -89,6 +89,7 @@ GET /users | `sort` | string | no | Return users sorted in `asc` or `desc` order. Default is `desc` | | `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users | | `without_projects` | boolean | no | Filter users without projects. Default is `false` | +| `admins` | boolean | no | Return only admin users. Default is `false` | ```json [ diff --git a/doc/user/admin_area/settings/user_and_ip_rate_limits.md b/doc/user/admin_area/settings/user_and_ip_rate_limits.md index e24068901df..e2040ef19d6 100644 --- a/doc/user/admin_area/settings/user_and_ip_rate_limits.md +++ b/doc/user/admin_area/settings/user_and_ip_rate_limits.md @@ -46,15 +46,15 @@ blocked. The server may respond with rate-limiting information allowing the requester to retry after a specific period of time. These information are attached into the response headers. -| Header | Example | Description | -|:----------------------|:--------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Header | Example | Description | +|:----------------------|:--------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `RateLimit-Limit` | `60` | The request quota for the client **each minute**. If the rate limit period set in the admin area is different from 1 minute, the value of this header is adjusted to approximately the nearest 60-minute period. | -| `RateLimit-Name` | `throttle_authenticated_web` | Name of the throttle blocking the requests. | -| `RateLimit-Observed` | `67` | Number of requests associated to the client in the time window. | -| `RateLimit-Remaining` | `0` | Remaining quota in the time window. The result of `RateLimit-Limit` - `RateLimit-Remaining`. | -| `RateLimit-Reset` | `30` | An alias of `Retry-After` header. | -| `RateLimit-ResetTime` | `Tue, 05 Jan 2021 11:00:00 GMT` | [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3.1)-formatted date and time when the request quota is reset. | -| `Retry-After` | `30` | Remaining duration **in seconds** until the quota is reset. This is a [standard HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | +| `RateLimit-Name` | `throttle_authenticated_web` | Name of the throttle blocking the requests. | +| `RateLimit-Observed` | `67` | Number of requests associated to the client in the time window. | +| `RateLimit-Remaining` | `0` | Remaining quota in the time window. The result of `RateLimit-Limit` - `RateLimit-Remaining`. | +| `RateLimit-Reset` | `1609844400` | [Unix time](https://en.wikipedia.org/wiki/Unix_time)-formatted time when the request quota is reset. | +| `RateLimit-ResetTime` | `Tue, 05 Jan 2021 11:00:00 GMT` | [RFC2616](https://tools.ietf.org/html/rfc2616#section-3.3.1)-formatted date and time when the request quota is reset. | +| `Retry-After` | `30` | Remaining duration **in seconds** until the quota is reset. This is a [standard HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). | ## Use an HTTP header to bypass rate limiting diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index cbb4d731200..611c1105961 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -132,6 +132,23 @@ All our runners are deployed into Google Cloud Platform (GCP) - any IP based firewall can be configured by looking up all [IP address ranges or CIDR blocks for GCP](https://cloud.google.com/compute/docs/faq#where_can_i_find_product_name_short_ip_ranges). +## Hostname list + +To configure allow-lists in local HTTP(S) proxies, or other +web-blocking software that govern end-user machines, +pages on GitLab.com will attempt to load content from +the following hostnames: + +- `gitlab.com` +- `*.gitlab.com` +- `*.gitlab-static.net` +- `*.gitlab.io` +- `*.gitlab.net` + +Documentation and Company pages served over `docs.gitlab.com` +and `about.gitlab.com` will attempt to also load certain page +content directly from common public CDN hostnames. + ## Webhooks A limit of: |