diff options
Diffstat (limited to 'doc/api')
52 files changed, 2475 insertions, 1753 deletions
diff --git a/doc/api/README.md b/doc/api/README.md deleted file mode 100644 index 0e6c2f63f9e..00000000000 --- a/doc/api/README.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2021-09-28' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after 2021-09-28. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 1634184a374..df830a1607d 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -2,13 +2,10 @@ stage: Manage group: Access 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" -type: reference, api --- # Group and project access requests API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18583) in GitLab 8.11. - ## Valid access levels The access levels are defined in the `Gitlab::Access` module, and the diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index 8706b1e7e76..7dc3fd1db21 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -42,6 +42,7 @@ The following API resources are available in the project context: | [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | | [Feature Flags](feature_flags.md) | `/projects/:id/feature_flags` | | [Feature Flag User Lists](feature_flag_user_lists.md) | `/projects/:id/feature_flags_user_lists` | +| [Integrations](integrations.md) | `/projects/:id/integrations` | | [Invitations](invitations.md) | `/projects/:id/invitations` (also available for groups) | | [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | | [Issues Statistics](issues_statistics.md) | `/projects/:id/issues_statistics` (also available for groups and standalone) | @@ -82,7 +83,7 @@ The following API resources are available in the project context: | [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` (also available for groups) | | [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | | [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | -| [Services](services.md) | `/projects/:id/services` | +| [Services](services.md) (renamed to [Integrations](integrations.md)) | `/projects/:id/services` | | [Tags](tags.md) | `/projects/:id/repository/tags` | | [User-starred metrics dashboards](metrics_user_starred_dashboards.md ) | `/projects/:id/metrics/user_starred_dashboards` | | [Visual Review discussions](visual_review_discussions.md) **(PREMIUM)** | `/projects/:id/merge_requests/:merge_request_id/visual_review_discussions` | diff --git a/doc/api/applications.md b/doc/api/applications.md index 2b5eff68010..22d858bd68a 100644 --- a/doc/api/applications.md +++ b/doc/api/applications.md @@ -34,14 +34,14 @@ Parameters: |:---------------|:--------|:---------|:---------------------------------| | `name` | string | yes | Name of the application. | | `redirect_uri` | string | yes | Redirect URI of the application. | -| `scopes` | string | yes | Scopes of the application. | +| `scopes` | string | yes | Scopes of the application. You can specify multiple scopes by separating each scope using a space. | | `confidential` | boolean | no | The application is used where the client secret can be kept confidential. Native mobile apps and Single Page Apps are considered non-confidential. Defaults to `true` if not supplied | Example request: ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ - --data "name=MyApplication&redirect_uri=http://redirect.uri&scopes=" \ + --data "name=MyApplication&redirect_uri=http://redirect.uri&scopes=api read_user email" \ "https://gitlab.example.com/api/v4/applications" ``` diff --git a/doc/api/commits.md b/doc/api/commits.md index e91da23596f..94d1ced181c 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -2,7 +2,6 @@ stage: Create group: Source Code 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" -type: reference, api --- # Commits API **(FREE)** @@ -75,8 +74,6 @@ Example response: ## Create a commit with multiple files and actions -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6096) in GitLab 8.13. - Create a commit by posting a JSON payload ```plaintext @@ -256,8 +253,6 @@ Example response: ## Get references a commit is pushed to -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15026) in GitLab 10.6 - Get all references (from branches or tags) a commit is pushed to. The pagination parameters `page` and `per_page` can be used to restrict the list of references. @@ -291,8 +286,6 @@ Example response: ## Cherry-pick a commit -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8047) in GitLab 8.15. - Cherry-picks a commit to a given branch. ```plaintext @@ -366,8 +359,6 @@ dry run. ## Revert a commit -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22919) in GitLab 11.5. - Reverts a commit in a given branch. ```plaintext @@ -622,7 +613,7 @@ Example response: ## Commit status -In GitLab 8.1 and later, this is the new commit status API. +This is the commit status API for use with GitLab. ### List the statuses of a commit @@ -752,8 +743,6 @@ Example response: ## List Merge Requests associated with a commit -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18004) in GitLab 10.7. - Get a list of Merge Requests related to the specified commit. ```plaintext diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 2885cc7d803..1b9778a01b3 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -350,7 +350,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \ ``` This action doesn't delete blobs. To delete them and recycle disk space, -[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests). +[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/index.html#removing-unused-layers-not-referenced-by-manifests). ## Delete registry repository tags in bulk @@ -388,7 +388,7 @@ This API call performs the following operations: These operations are executed asynchronously and can take time to get executed. You can run this at most once an hour for a given container repository. This action doesn't delete blobs. To delete them and recycle disk space, -[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests). +[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/index.html#removing-unused-layers-not-referenced-by-manifests). WARNING: The number of tags deleted by this API is limited on GitLab.com diff --git a/doc/api/dependencies.md b/doc/api/dependencies.md index 6e9c37980ac..b421a32b88a 100644 --- a/doc/api/dependencies.md +++ b/doc/api/dependencies.md @@ -34,7 +34,7 @@ GET /projects/:id/dependencies?package_manager=yarn,bundler | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | -| `package_manager` | string array | no | Returns dependencies belonging to specified package manager. Valid values: `bundler`, `composer`, `conan`, `maven`, `npm`, `pip` or `yarn`. | +| `package_manager` | string array | no | Returns dependencies belonging to specified package manager. Valid values: `bundler`, `composer`, `conan`, `go`, `maven`, `npm`, `nuget`, `pip`, `yarn`, or `sbt`. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/dependencies" diff --git a/doc/api/deploy_tokens.md b/doc/api/deploy_tokens.md index 3de7ff4ac44..c7189586230 100644 --- a/doc/api/deploy_tokens.md +++ b/doc/api/deploy_tokens.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9. -Get a list of all deploy tokens across the GitLab instance. This endpoint requires administrator access. +Get a list of all deploy tokens across the GitLab instance. This endpoint requires the Administrator role. ```plaintext GET /deploy_tokens diff --git a/doc/api/dora/metrics.md b/doc/api/dora/metrics.md index 8c82446db2e..4fbd2b0fa80 100644 --- a/doc/api/dora/metrics.md +++ b/doc/api/dora/metrics.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Manage +group: Optimize 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 type: reference, api --- diff --git a/doc/api/dora4_project_analytics.md b/doc/api/dora4_project_analytics.md index 5a6e1576a3d..f69c918c6e2 100644 --- a/doc/api/dora4_project_analytics.md +++ b/doc/api/dora4_project_analytics.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Manage +group: Optimize 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 type: reference, api --- diff --git a/doc/api/environments.md b/doc/api/environments.md index 5187ac7c1b2..8188e0e7b85 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -64,6 +64,8 @@ Example of response "slug": "review-fix-foo-dfjre3", "external_url": "https://review-fix-foo-dfjre3.gitlab.example.com", "state": "available", + "created_at": "2019-05-25T18:55:13.252Z", + "updated_at": "2019-05-27T18:55:13.252Z", "last_deployment": { "id": 100, "iid": 34, @@ -176,7 +178,9 @@ Example response: "name": "deploy", "slug": "deploy", "external_url": "https://deploy.gitlab.example.com", - "state": "available" + "state": "available", + "created_at": "2019-05-25T18:55:13.252Z", + "updated_at": "2019-05-27T18:55:13.252Z" } ``` @@ -210,7 +214,9 @@ Example response: "name": "staging", "slug": "staging", "external_url": "https://staging.gitlab.example.com", - "state": "available" + "state": "available", + "created_at": "2019-05-25T18:55:13.252Z", + "updated_at": "2019-05-27T18:55:13.252Z" } ``` @@ -302,6 +308,8 @@ Example response: "name": "deploy", "slug": "deploy", "external_url": "https://deploy.gitlab.example.com", - "state": "stopped" + "state": "stopped", + "created_at": "2019-05-25T18:55:13.252Z", + "updated_at": "2019-05-27T18:55:13.252Z" } ``` diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md index 1abe5522840..203c1a23996 100644 --- a/doc/api/error_tracking.md +++ b/doc/api/error_tracking.md @@ -73,7 +73,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68384) in GitLab 14.3. -For [integrated error tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) feature that is behind a disabled feature flag. Only for project maintainers. +For [integrated error tracking](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) feature. Only for project maintainers. ### List project client keys diff --git a/doc/api/events.md b/doc/api/events.md index 8800e7f7f9b..2d173f0053f 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -87,10 +87,6 @@ GitLab removes events older than 3 years from the events table for performance r ## List currently authenticated user's events ->**Notes:** -> This endpoint was introduced in GitLab 9.3. -> `read_user` access was introduced in GitLab 11.3. - Get a list of events for the authenticated user. Scope `read_user` or `api` is required. ```plaintext @@ -163,10 +159,6 @@ Example response: ### Get user contribution events ->**Notes:** -> Documentation was formerly located in the [Users API pages](users.md). -> `read_user` access was introduced in GitLab 11.3. - Get the contribution events for the specified user, sorted from newest to oldest. Scope `read_user` or `api` is required. ```plaintext diff --git a/doc/api/experiments.md b/doc/api/experiments.md index c5e217a3d66..669d00454bd 100644 --- a/doc/api/experiments.md +++ b/doc/api/experiments.md @@ -4,7 +4,7 @@ group: Expansion 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 --- -# Experiments API +# Experiments API (GitLab team only) **(FREE SAAS)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/262725) in GitLab 13.5. diff --git a/doc/api/freeze_periods.md b/doc/api/freeze_periods.md index 6ca69d047da..6dc4e8745d6 100644 --- a/doc/api/freeze_periods.md +++ b/doc/api/freeze_periods.md @@ -94,7 +94,7 @@ POST /projects/:id/freeze_periods | `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `freeze_start` | string | yes | Start of the Freeze Period in [cron](https://crontab.guru/) format. | | `freeze_end` | string | yes | End of the Freeze Period in [cron](https://crontab.guru/) format. | -| `cron_timezone` | string | no | The timezone for the cron fields, defaults to UTC if not provided. | +| `cron_timezone` | string | no | The time zone for the cron fields, defaults to UTC if not provided. | Example request: @@ -131,7 +131,7 @@ PUT /projects/:id/freeze_periods/:freeze_period_id | `freeze_period_id` | integer or string | yes | The database ID of the Freeze Period. | | `freeze_start` | string | no | Start of the Freeze Period in [cron](https://crontab.guru/) format. | | `freeze_end` | string | no | End of the Freeze Period in [cron](https://crontab.guru/) format. | -| `cron_timezone` | string | no | The timezone for the cron fields. | +| `cron_timezone` | string | no | The time zone for the cron fields. | Example request: diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index c4e73f9c058..e0f18f931f5 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -25,13 +25,30 @@ Items (fields, enums, etc) that have been removed according to our [deprecation in [Removed Items](../removed_items.md). <!-- vale off --> -<!-- Docs linting disabled after this line. --> +<!-- Vale linting disabled after this line. --> <!-- See https://docs.gitlab.com/ee/development/documentation/testing.html#disable-vale-tests --> +<!-- markdownlint-disable MD044 --> +<!-- MD044/proper-names test disabled after this line to make page compatible with markdownlint-cli 0.29.0. --> +<!-- See https://docs.gitlab.com/ee/development/documentation/testing.html#disable-markdownlint-tests --> + ## `Query` type The `Query` type contains the API's top-level entry points for all executable queries. +### `Query.boardList` + +Find an issue board list. + +Returns [`BoardList`](#boardlist). + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="queryboardlistid"></a>`id` | [`ListID!`](#listid) | Global ID of the list. | +| <a id="queryboardlistissuefilters"></a>`issueFilters` | [`BoardIssueInput`](#boardissueinput) | Filters applied when getting issue metadata in the board list. | + ### `Query.ciApplicationSettings` CI related settings that apply to the entire instance. @@ -469,6 +486,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="queryvulnerabilitieshasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have linked issues. | | <a id="queryvulnerabilitieshasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have been resolved on default branch. | +| <a id="queryvulnerabilitiesimage"></a>`image` | [`[String!]`](#string) | Filter vulnerabilities by location image. When this filter is present, the response only matches entries for a `reportType` that includes `container_scanning`, `cluster_image_scanning`. | | <a id="queryvulnerabilitiesprojectid"></a>`projectId` | [`[ID!]`](#id) | Filter vulnerabilities by project. | | <a id="queryvulnerabilitiesreporttype"></a>`reportType` | [`[VulnerabilityReportType!]`](#vulnerabilityreporttype) | Filter vulnerabilities by report type. | | <a id="queryvulnerabilitiesscanner"></a>`scanner` | [`[String!]`](#string) | Filter vulnerabilities by VulnerabilityScanner.externalId. | @@ -1266,6 +1284,9 @@ Input type: `CreateIssueInput` | <a id="mutationcreateissueepicid"></a>`epicId` | [`EpicID`](#epicid) | ID of an epic to associate the issue with. | | <a id="mutationcreateissuehealthstatus"></a>`healthStatus` | [`HealthStatus`](#healthstatus) | Desired health status. | | <a id="mutationcreateissueiid"></a>`iid` | [`Int`](#int) | IID (internal ID) of a project issue. Only admins and project owners can modify. | +| <a id="mutationcreateissueiterationcadenceid"></a>`iterationCadenceId` | [`IterationsCadenceID`](#iterationscadenceid) | Global iteration cadence ID. Required when `iterationWildcardId` is provided. | +| <a id="mutationcreateissueiterationid"></a>`iterationId` | [`IterationID`](#iterationid) | Global iteration ID. Mutually exlusive argument with `iterationWildcardId`. | +| <a id="mutationcreateissueiterationwildcardid"></a>`iterationWildcardId` | [`IssueCreationIterationWildcardId`](#issuecreationiterationwildcardid) | Iteration wildcard ID. Supported values are: `CURRENT`. Mutually exclusive argument with `iterationId`. iterationCadenceId also required when this argument is provided. | | <a id="mutationcreateissuelabelids"></a>`labelIds` | [`[LabelID!]`](#labelid) | IDs of labels to be added to the issue. | | <a id="mutationcreateissuelabels"></a>`labels` | [`[String!]`](#string) | Labels of the issue. | | <a id="mutationcreateissuelocked"></a>`locked` | [`Boolean`](#boolean) | Indicates discussion is locked on the issue. | @@ -1408,6 +1429,56 @@ Input type: `CreateTestCaseInput` | <a id="mutationcreatetestcaseerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | | <a id="mutationcreatetestcasetestcase"></a>`testCase` | [`Issue`](#issue) | Test case created. | +### `Mutation.customerRelationsContactCreate` + +Input type: `CustomerRelationsContactCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcustomerrelationscontactcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcustomerrelationscontactcreatedescription"></a>`description` | [`String`](#string) | Description of or notes for the contact. | +| <a id="mutationcustomerrelationscontactcreateemail"></a>`email` | [`String`](#string) | Email address of the contact. | +| <a id="mutationcustomerrelationscontactcreatefirstname"></a>`firstName` | [`String!`](#string) | First name of the contact. | +| <a id="mutationcustomerrelationscontactcreategroupid"></a>`groupId` | [`GroupID!`](#groupid) | Group for the contact. | +| <a id="mutationcustomerrelationscontactcreatelastname"></a>`lastName` | [`String!`](#string) | Last name of the contact. | +| <a id="mutationcustomerrelationscontactcreateorganizationid"></a>`organizationId` | [`CustomerRelationsOrganizationID`](#customerrelationsorganizationid) | Organization for the contact. | +| <a id="mutationcustomerrelationscontactcreatephone"></a>`phone` | [`String`](#string) | Phone number of the contact. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcustomerrelationscontactcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcustomerrelationscontactcreatecontact"></a>`contact` | [`CustomerRelationsContact`](#customerrelationscontact) | Contact after the mutation. | +| <a id="mutationcustomerrelationscontactcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + +### `Mutation.customerRelationsContactUpdate` + +Input type: `CustomerRelationsContactUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcustomerrelationscontactupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcustomerrelationscontactupdatedescription"></a>`description` | [`String`](#string) | Description of or notes for the contact. | +| <a id="mutationcustomerrelationscontactupdateemail"></a>`email` | [`String`](#string) | Email address of the contact. | +| <a id="mutationcustomerrelationscontactupdatefirstname"></a>`firstName` | [`String`](#string) | First name of the contact. | +| <a id="mutationcustomerrelationscontactupdateid"></a>`id` | [`CustomerRelationsContactID!`](#customerrelationscontactid) | Global ID of the contact. | +| <a id="mutationcustomerrelationscontactupdatelastname"></a>`lastName` | [`String`](#string) | Last name of the contact. | +| <a id="mutationcustomerrelationscontactupdateorganizationid"></a>`organizationId` | [`CustomerRelationsOrganizationID`](#customerrelationsorganizationid) | Organization of the contact. | +| <a id="mutationcustomerrelationscontactupdatephone"></a>`phone` | [`String`](#string) | Phone number of the contact. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationcustomerrelationscontactupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationcustomerrelationscontactupdatecontact"></a>`contact` | [`CustomerRelationsContact`](#customerrelationscontact) | Contact after the mutation. | +| <a id="mutationcustomerrelationscontactupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.customerRelationsOrganizationCreate` Input type: `CustomerRelationsOrganizationCreateInput` @@ -1418,7 +1489,7 @@ Input type: `CustomerRelationsOrganizationCreateInput` | ---- | ---- | ----------- | | <a id="mutationcustomerrelationsorganizationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcustomerrelationsorganizationcreatedefaultrate"></a>`defaultRate` | [`Float`](#float) | Standard billing rate for the organization. | -| <a id="mutationcustomerrelationsorganizationcreatedescription"></a>`description` | [`String`](#string) | Description or notes for the organization. | +| <a id="mutationcustomerrelationsorganizationcreatedescription"></a>`description` | [`String`](#string) | Description of or notes for the organization. | | <a id="mutationcustomerrelationsorganizationcreategroupid"></a>`groupId` | [`GroupID!`](#groupid) | Group for the organization. | | <a id="mutationcustomerrelationsorganizationcreatename"></a>`name` | [`String!`](#string) | Name of the organization. | @@ -1440,7 +1511,7 @@ Input type: `CustomerRelationsOrganizationUpdateInput` | ---- | ---- | ----------- | | <a id="mutationcustomerrelationsorganizationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationcustomerrelationsorganizationupdatedefaultrate"></a>`defaultRate` | [`Float`](#float) | Standard billing rate for the organization. | -| <a id="mutationcustomerrelationsorganizationupdatedescription"></a>`description` | [`String`](#string) | Description or notes for the organization. | +| <a id="mutationcustomerrelationsorganizationupdatedescription"></a>`description` | [`String`](#string) | Description of or notes for the organization. | | <a id="mutationcustomerrelationsorganizationupdateid"></a>`id` | [`CustomerRelationsOrganizationID!`](#customerrelationsorganizationid) | Global ID of the organization. | | <a id="mutationcustomerrelationsorganizationupdatename"></a>`name` | [`String`](#string) | Name of the organization. | @@ -2432,6 +2503,64 @@ Input type: `ExportRequirementsInput` | <a id="mutationexportrequirementsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | | <a id="mutationexportrequirementserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.externalAuditEventDestinationCreate` + +Input type: `ExternalAuditEventDestinationCreateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationexternalauditeventdestinationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationexternalauditeventdestinationcreatedestinationurl"></a>`destinationUrl` | [`String!`](#string) | Destination URL. | +| <a id="mutationexternalauditeventdestinationcreategrouppath"></a>`groupPath` | [`ID!`](#id) | Group path. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationexternalauditeventdestinationcreateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationexternalauditeventdestinationcreateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationexternalauditeventdestinationcreateexternalauditeventdestination"></a>`externalAuditEventDestination` | [`ExternalAuditEventDestination`](#externalauditeventdestination) | Destination created. | + +### `Mutation.externalAuditEventDestinationDestroy` + +Input type: `ExternalAuditEventDestinationDestroyInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationexternalauditeventdestinationdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationexternalauditeventdestinationdestroyid"></a>`id` | [`AuditEventsExternalAuditEventDestinationID!`](#auditeventsexternalauditeventdestinationid) | ID of external audit event destination to destroy. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationexternalauditeventdestinationdestroyclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationexternalauditeventdestinationdestroyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + +### `Mutation.externalAuditEventDestinationUpdate` + +Input type: `ExternalAuditEventDestinationUpdateInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationexternalauditeventdestinationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationexternalauditeventdestinationupdatedestinationurl"></a>`destinationUrl` | [`String`](#string) | Destination URL to change. | +| <a id="mutationexternalauditeventdestinationupdateid"></a>`id` | [`AuditEventsExternalAuditEventDestinationID!`](#auditeventsexternalauditeventdestinationid) | ID of external audit event destination to destroy. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationexternalauditeventdestinationupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationexternalauditeventdestinationupdateerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +| <a id="mutationexternalauditeventdestinationupdateexternalauditeventdestination"></a>`externalAuditEventDestination` | [`ExternalAuditEventDestination`](#externalauditeventdestination) | Updated destination. | + ### `Mutation.gitlabSubscriptionActivate` Input type: `GitlabSubscriptionActivateInput` @@ -3904,6 +4033,8 @@ Input type: `RunnersRegistrationTokenResetInput` ### `Mutation.scanExecutionPolicyCommit` +Commits the `policy_yaml` content to the assigned security policy project for the given project(`project_path`). + Input type: `ScanExecutionPolicyCommitInput` #### Arguments @@ -3925,6 +4056,8 @@ Input type: `ScanExecutionPolicyCommitInput` ### `Mutation.securityPolicyProjectAssign` +Assigns the specified project(`security_policy_project_id`) as security policy project for the given project(`project_path`). If the project already has a security policy project, this reassigns the project's security policy project with the given `security_policy_project_id`. + Input type: `SecurityPolicyProjectAssignInput` #### Arguments @@ -3944,6 +4077,8 @@ Input type: `SecurityPolicyProjectAssignInput` ### `Mutation.securityPolicyProjectCreate` +Creates and assigns a security policy project for the given project(`project_path`). + Input type: `SecurityPolicyProjectCreateInput` #### Arguments @@ -4269,6 +4404,26 @@ Input type: `UpdateDependencyProxyImageTtlGroupPolicyInput` | <a id="mutationupdatedependencyproxyimagettlgrouppolicydependencyproxyimagettlpolicy"></a>`dependencyProxyImageTtlPolicy` | [`DependencyProxyImageTtlGroupPolicy`](#dependencyproxyimagettlgrouppolicy) | Group image TTL policy after mutation. | | <a id="mutationupdatedependencyproxyimagettlgrouppolicyerrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | +### `Mutation.updateDependencyProxySettings` + +Input type: `UpdateDependencyProxySettingsInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationupdatedependencyproxysettingsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationupdatedependencyproxysettingsenabled"></a>`enabled` | [`Boolean`](#boolean) | Indicates whether the policy is enabled or disabled. | +| <a id="mutationupdatedependencyproxysettingsgrouppath"></a>`groupPath` | [`ID!`](#id) | Group path for the group dependency proxy. | + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="mutationupdatedependencyproxysettingsclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. | +| <a id="mutationupdatedependencyproxysettingsdependencyproxysetting"></a>`dependencyProxySetting` | [`DependencyProxySetting`](#dependencyproxysetting) | Group dependency proxy settings after mutation. | +| <a id="mutationupdatedependencyproxysettingserrors"></a>`errors` | [`[String!]!`](#string) | Errors encountered during execution of the mutation. | + ### `Mutation.updateEpic` Input type: `UpdateEpicInput` @@ -4560,13 +4715,13 @@ Input type: `VulnerabilityCreateInput` | <a id="mutationvulnerabilitycreatedismissedat"></a>`dismissedAt` | [`Time`](#time) | Timestamp of when the vulnerability state changed to dismissed (defaults to creation time if status is `dismissed`). | | <a id="mutationvulnerabilitycreateidentifiers"></a>`identifiers` | [`[VulnerabilityIdentifierInput!]!`](#vulnerabilityidentifierinput) | Array of CVE or CWE identifiers for the vulnerability. | | <a id="mutationvulnerabilitycreatemessage"></a>`message` | [`String`](#string) | Additional information about the vulnerability. | +| <a id="mutationvulnerabilitycreatename"></a>`name` | [`String!`](#string) | Name of the vulnerability. | | <a id="mutationvulnerabilitycreateproject"></a>`project` | [`ProjectID!`](#projectid) | ID of the project to attach the vulnerability to. | | <a id="mutationvulnerabilitycreateresolvedat"></a>`resolvedAt` | [`Time`](#time) | Timestamp of when the vulnerability state changed to resolved (defaults to creation time if status is `resolved`). | -| <a id="mutationvulnerabilitycreatescannername"></a>`scannerName` | [`String!`](#string) | Name of the security scanner used to discover the vulnerability. | +| <a id="mutationvulnerabilitycreatescanner"></a>`scanner` | [`VulnerabilityScannerInput!`](#vulnerabilityscannerinput) | Information about the scanner used to discover the vulnerability. | | <a id="mutationvulnerabilitycreateseverity"></a>`severity` | [`VulnerabilitySeverity`](#vulnerabilityseverity) | Severity of the vulnerability (defaults to `unknown`). | | <a id="mutationvulnerabilitycreatesolution"></a>`solution` | [`String`](#string) | How to fix this vulnerability. | | <a id="mutationvulnerabilitycreatestate"></a>`state` | [`VulnerabilityState`](#vulnerabilitystate) | State of the vulnerability (defaults to `detected`). | -| <a id="mutationvulnerabilitycreatetitle"></a>`title` | [`String!`](#string) | Title of the vulnerability. | #### Fields @@ -5173,6 +5328,7 @@ The edge type for [`CiRunner`](#cirunner). | ---- | ---- | ----------- | | <a id="cirunneredgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="cirunneredgenode"></a>`node` | [`CiRunner`](#cirunner) | The item at the end of the edge. | +| <a id="cirunneredgeweburl"></a>`webUrl` | [`String`](#string) | Web URL of the runner. The value depends on where you put this field in the query. You can use it for projects or groups. | #### `CiStageConnection` @@ -5915,6 +6071,29 @@ The edge type for [`Event`](#event). | <a id="eventedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | | <a id="eventedgenode"></a>`node` | [`Event`](#event) | The item at the end of the edge. | +#### `ExternalAuditEventDestinationConnection` + +The connection type for [`ExternalAuditEventDestination`](#externalauditeventdestination). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="externalauditeventdestinationconnectionedges"></a>`edges` | [`[ExternalAuditEventDestinationEdge]`](#externalauditeventdestinationedge) | A list of edges. | +| <a id="externalauditeventdestinationconnectionnodes"></a>`nodes` | [`[ExternalAuditEventDestination]`](#externalauditeventdestination) | A list of nodes. | +| <a id="externalauditeventdestinationconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | + +#### `ExternalAuditEventDestinationEdge` + +The edge type for [`ExternalAuditEventDestination`](#externalauditeventdestination). + +##### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="externalauditeventdestinationedgecursor"></a>`cursor` | [`String!`](#string) | A cursor for use in pagination. | +| <a id="externalauditeventdestinationedgenode"></a>`node` | [`ExternalAuditEventDestination`](#externalauditeventdestination) | The item at the end of the edge. | + #### `GroupConnection` The connection type for [`Group`](#group). @@ -6503,6 +6682,7 @@ The connection type for [`Package`](#package). | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="packageconnectioncount"></a>`count` | [`Int!`](#int) | Total count of collection. | | <a id="packageconnectionedges"></a>`edges` | [`[PackageEdge]`](#packageedge) | A list of edges. | | <a id="packageconnectionnodes"></a>`nodes` | [`[Package]`](#package) | A list of nodes. | | <a id="packageconnectionpageinfo"></a>`pageInfo` | [`PageInfo!`](#pageinfo) | Information to aid in pagination. | @@ -8072,7 +8252,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="boardepicancestorsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="boardepicancestorsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="boardepicancestorsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | -| <a id="boardepicancestorssearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | +| <a id="boardepicancestorssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="boardepicancestorssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="boardepicancestorsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="boardepicancestorsstate"></a>`state` | [`EpicState`](#epicstate) | Filter epics by state. | @@ -8105,7 +8285,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="boardepicchildrenmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="boardepicchildrenmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="boardepicchildrennot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | -| <a id="boardepicchildrensearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | +| <a id="boardepicchildrensearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="boardepicchildrensort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="boardepicchildrenstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="boardepicchildrenstate"></a>`state` | [`EpicState`](#epicstate) | Filter epics by state. | @@ -8391,6 +8571,7 @@ Represents the total number of issues and their weights for a particular day. | ---- | ---- | ----------- | | <a id="cirunneraccesslevel"></a>`accessLevel` | [`CiRunnerAccessLevel!`](#cirunneraccesslevel) | Access level of the runner. | | <a id="cirunneractive"></a>`active` | [`Boolean!`](#boolean) | Indicates the runner is allowed to receive jobs. | +| <a id="cirunneradminurl"></a>`adminUrl` | [`String`](#string) | Admin URL of the runner. Only available for adminstrators. | | <a id="cirunnercontactedat"></a>`contactedAt` | [`Time`](#time) | Last contact from the runner. | | <a id="cirunnerdescription"></a>`description` | [`String`](#string) | Description of the runner. | | <a id="cirunnerid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner. | @@ -8407,6 +8588,7 @@ Represents the total number of issues and their weights for a particular day. | <a id="cirunnershortsha"></a>`shortSha` | [`String`](#string) | First eight characters of the runner's token used to authenticate new job requests. Used as the runner's unique ID. | | <a id="cirunnerstatus"></a>`status` | [`CiRunnerStatus!`](#cirunnerstatus) | Status of the runner. | | <a id="cirunnertaglist"></a>`tagList` | [`[String!]`](#string) | Tags associated with the runner. | +| <a id="cirunneruserpermissions"></a>`userPermissions` | [`RunnerPermissions!`](#runnerpermissions) | Permissions for the current user on the resource. | | <a id="cirunnerversion"></a>`version` | [`String`](#string) | Version of the runner. | ### `CiStage` @@ -8737,7 +8919,7 @@ A custom emoji uploaded by user. | Name | Type | Description | | ---- | ---- | ----------- | | <a id="customerrelationscontactcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp the contact was created. | -| <a id="customerrelationscontactdescription"></a>`description` | [`String`](#string) | Description or notes for the contact. | +| <a id="customerrelationscontactdescription"></a>`description` | [`String`](#string) | Description of or notes for the contact. | | <a id="customerrelationscontactemail"></a>`email` | [`String`](#string) | Email address of the contact. | | <a id="customerrelationscontactfirstname"></a>`firstName` | [`String!`](#string) | First name of the contact. | | <a id="customerrelationscontactid"></a>`id` | [`ID!`](#id) | Internal ID of the contact. | @@ -8754,7 +8936,7 @@ A custom emoji uploaded by user. | ---- | ---- | ----------- | | <a id="customerrelationsorganizationcreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp the organization was created. | | <a id="customerrelationsorganizationdefaultrate"></a>`defaultRate` | [`Float`](#float) | Standard billing rate for the organization. | -| <a id="customerrelationsorganizationdescription"></a>`description` | [`String`](#string) | Description or notes for the organization. | +| <a id="customerrelationsorganizationdescription"></a>`description` | [`String`](#string) | Description of or notes for the organization. | | <a id="customerrelationsorganizationid"></a>`id` | [`ID!`](#id) | Internal ID of the organization. | | <a id="customerrelationsorganizationname"></a>`name` | [`String!`](#string) | Name of the organization. | | <a id="customerrelationsorganizationupdatedat"></a>`updatedAt` | [`Time!`](#time) | Timestamp the organization was last updated. | @@ -9477,7 +9659,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="epicancestorsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="epicancestorsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="epicancestorsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | -| <a id="epicancestorssearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | +| <a id="epicancestorssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="epicancestorssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="epicancestorsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="epicancestorsstate"></a>`state` | [`EpicState`](#epicstate) | Filter epics by state. | @@ -9510,7 +9692,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="epicchildrenmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="epicchildrenmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="epicchildrennot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | -| <a id="epicchildrensearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | +| <a id="epicchildrensearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="epicchildrensort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="epicchildrenstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="epicchildrenstate"></a>`state` | [`EpicState`](#epicstate) | Filter epics by state. | @@ -9634,6 +9816,7 @@ Relationship between an epic and an issue. | <a id="epicissueconfidential"></a>`confidential` | [`Boolean!`](#boolean) | Indicates the issue is confidential. | | <a id="epicissuecreatenoteemail"></a>`createNoteEmail` | [`String`](#string) | User specific email address for the issue. | | <a id="epicissuecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the issue was created. | +| <a id="epicissuecustomerrelationscontacts"></a>`customerRelationsContacts` | [`CustomerRelationsContactConnection`](#customerrelationscontactconnection) | Customer relations contacts of the issue. (see [Connections](#connections)) | | <a id="epicissuedescription"></a>`description` | [`String`](#string) | Description of the issue. | | <a id="epicissuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | | <a id="epicissuedesigncollection"></a>`designCollection` | [`DesignCollection`](#designcollection) | Collection of design images associated with this issue. | @@ -9806,6 +9989,18 @@ Representing an event. | <a id="eventid"></a>`id` | [`ID!`](#id) | ID of the event. | | <a id="eventupdatedat"></a>`updatedAt` | [`Time!`](#time) | When this event was updated. | +### `ExternalAuditEventDestination` + +Represents an external resource to send audit events to. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="externalauditeventdestinationdestinationurl"></a>`destinationUrl` | [`String!`](#string) | External destination to send audit events to. | +| <a id="externalauditeventdestinationgroup"></a>`group` | [`Group!`](#group) | Group the destination belongs to. | +| <a id="externalauditeventdestinationid"></a>`id` | [`ID!`](#id) | ID of the destination. | + ### `ExternalIssue` Represents an external issue. @@ -9976,7 +10171,7 @@ four standard [pagination arguments](#connection-pagination-arguments): ##### `GeoNode.uploadRegistries` -Find Upload registries on this Geo node Available only when feature flag `geo_upload_replication` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. +Find Upload registries on this Geo node. Returns [`UploadRegistryConnection`](#uploadregistryconnection). @@ -10031,6 +10226,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupemailsdisabled"></a>`emailsDisabled` | [`Boolean`](#boolean) | Indicates if a group has email notifications disabled. | | <a id="groupepicboards"></a>`epicBoards` | [`EpicBoardConnection`](#epicboardconnection) | Find epic boards. (see [Connections](#connections)) | | <a id="groupepicsenabled"></a>`epicsEnabled` | [`Boolean`](#boolean) | Indicates if Epics are enabled for namespace. | +| <a id="groupexternalauditeventdestinations"></a>`externalAuditEventDestinations` | [`ExternalAuditEventDestinationConnection`](#externalauditeventdestinationconnection) | External locations that receive audit events belonging to the group. Available only when feature flag `ff_external_audit_events_namespace` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. (see [Connections](#connections)) | | <a id="groupfullname"></a>`fullName` | [`String!`](#string) | Full name of the namespace. | | <a id="groupfullpath"></a>`fullPath` | [`ID!`](#id) | Full path of the namespace. | | <a id="groupid"></a>`id` | [`ID!`](#id) | ID of the namespace. | @@ -10181,7 +10377,7 @@ Returns [`Epic`](#epic). | <a id="groupepicmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="groupepicmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="groupepicnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | -| <a id="groupepicsearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | +| <a id="groupepicsearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="groupepicsort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="groupepicstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="groupepicstate"></a>`state` | [`EpicState`](#epicstate) | Filter epics by state. | @@ -10226,7 +10422,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupepicsmilestonetitle"></a>`milestoneTitle` | [`String`](#string) | Filter epics by milestone title, computed from epic's issues. | | <a id="groupepicsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | | <a id="groupepicsnot"></a>`not` | [`NegatedEpicFilterInput`](#negatedepicfilterinput) | Negated epic arguments. | -| <a id="groupepicssearch"></a>`search` | [`String`](#string) | Search query for epic title or description. | +| <a id="groupepicssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="groupepicssort"></a>`sort` | [`EpicSort`](#epicsort) | List epics by sort order. | | <a id="groupepicsstartdate"></a>`startDate` **{warning-solid}** | [`Time`](#time) | **Deprecated** in 13.5. Use timeframe.start. | | <a id="groupepicsstate"></a>`state` | [`EpicState`](#epicstate) | Filter epics by state. | @@ -10269,11 +10465,13 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupissuesauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the issue. | | <a id="groupissuesclosedafter"></a>`closedAfter` | [`Time`](#time) | Issues closed after this date. | | <a id="groupissuesclosedbefore"></a>`closedBefore` | [`Time`](#time) | Issues closed before this date. | +| <a id="groupissuesconfidential"></a>`confidential` | [`Boolean`](#boolean) | Filter for confidential issues. If "false", excludes confidential issues. If "true", returns only confidential issues. | | <a id="groupissuescreatedafter"></a>`createdAfter` | [`Time`](#time) | Issues created after this date. | | <a id="groupissuescreatedbefore"></a>`createdBefore` | [`Time`](#time) | Issues created before this date. | | <a id="groupissuesepicid"></a>`epicId` | [`String`](#string) | ID of an epic associated with the issues, "none" and "any" values are supported. | | <a id="groupissuesiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | | <a id="groupissuesiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | +| <a id="groupissuesincludesubepics"></a>`includeSubepics` | [`Boolean`](#boolean) | Whether to include subepics when filtering issues by epicId. | | <a id="groupissuesincludesubgroups"></a>`includeSubgroups` | [`Boolean`](#boolean) | Include issues belonging to subgroups. | | <a id="groupissuesiterationid"></a>`iterationId` | [`[ID]`](#id) | List of iteration Global IDs applied to the issue. | | <a id="groupissuesiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | @@ -10282,7 +10480,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="groupissuesmilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | | <a id="groupissuesmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="groupissuesnot"></a>`not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | -| <a id="groupissuessearch"></a>`search` | [`String`](#string) | Search query for issue title or description. | +| <a id="groupissuessearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="groupissuessort"></a>`sort` | [`IssueSort`](#issuesort) | Sort issues by this criteria. | | <a id="groupissuesstate"></a>`state` | [`IssuableState`](#issuablestate) | Current state of this issue. | | <a id="groupissuestypes"></a>`types` | [`[IssueType!]`](#issuetype) | Filter issues by the given issue types. | @@ -10520,6 +10718,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="groupvulnerabilitieshasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have linked issues. | | <a id="groupvulnerabilitieshasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have been resolved on default branch. | +| <a id="groupvulnerabilitiesimage"></a>`image` | [`[String!]`](#string) | Filter vulnerabilities by location image. When this filter is present, the response only matches entries for a `reportType` that includes `container_scanning`, `cluster_image_scanning`. | | <a id="groupvulnerabilitiesprojectid"></a>`projectId` | [`[ID!]`](#id) | Filter vulnerabilities by project. | | <a id="groupvulnerabilitiesreporttype"></a>`reportType` | [`[VulnerabilityReportType!]`](#vulnerabilityreporttype) | Filter vulnerabilities by report type. | | <a id="groupvulnerabilitiesscanner"></a>`scanner` | [`[String!]`](#string) | Filter vulnerabilities by VulnerabilityScanner.externalId. | @@ -10781,6 +10980,7 @@ Returns [`VulnerabilitySeveritiesCount`](#vulnerabilityseveritiescount). | <a id="issueconfidential"></a>`confidential` | [`Boolean!`](#boolean) | Indicates the issue is confidential. | | <a id="issuecreatenoteemail"></a>`createNoteEmail` | [`String`](#string) | User specific email address for the issue. | | <a id="issuecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of when the issue was created. | +| <a id="issuecustomerrelationscontacts"></a>`customerRelationsContacts` | [`CustomerRelationsContactConnection`](#customerrelationscontactconnection) | Customer relations contacts of the issue. (see [Connections](#connections)) | | <a id="issuedescription"></a>`description` | [`String`](#string) | Description of the issue. | | <a id="issuedescriptionhtml"></a>`descriptionHtml` | [`String`](#string) | The GitLab Flavored Markdown rendering of `description`. | | <a id="issuedesigncollection"></a>`designCollection` | [`DesignCollection`](#designcollection) | Collection of design images associated with this issue. | @@ -11948,10 +12148,10 @@ Nuget metadata. | Name | Type | Description | | ---- | ---- | ----------- | -| <a id="nugetmetadataiconurl"></a>`iconUrl` | [`String!`](#string) | Icon URL of the Nuget package. | +| <a id="nugetmetadataiconurl"></a>`iconUrl` | [`String`](#string) | Icon URL of the Nuget package. | | <a id="nugetmetadataid"></a>`id` | [`PackagesNugetMetadatumID!`](#packagesnugetmetadatumid) | ID of the metadatum. | -| <a id="nugetmetadatalicenseurl"></a>`licenseUrl` | [`String!`](#string) | License URL of the Nuget package. | -| <a id="nugetmetadataprojecturl"></a>`projectUrl` | [`String!`](#string) | Project URL of the Nuget package. | +| <a id="nugetmetadatalicenseurl"></a>`licenseUrl` | [`String`](#string) | License URL of the Nuget package. | +| <a id="nugetmetadataprojecturl"></a>`projectUrl` | [`String`](#string) | Project URL of the Nuget package. | ### `OncallParticipantType` @@ -11985,6 +12185,7 @@ Represents a package in the Package Registry. Note that this type is in beta and | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="packagecandestroy"></a>`canDestroy` | [`Boolean!`](#boolean) | Whether the user can destroy the package. | | <a id="packagecreatedat"></a>`createdAt` | [`Time!`](#time) | Date of creation. | | <a id="packageid"></a>`id` | [`PackagesPackageID!`](#packagespackageid) | ID of the package. | | <a id="packagemetadata"></a>`metadata` | [`PackageMetadata`](#packagemetadata) | Package metadata. | @@ -12044,6 +12245,7 @@ Represents a package details in the Package Registry. Note that this type is in | Name | Type | Description | | ---- | ---- | ----------- | +| <a id="packagedetailstypecandestroy"></a>`canDestroy` | [`Boolean!`](#boolean) | Whether the user can destroy the package. | | <a id="packagedetailstypecreatedat"></a>`createdAt` | [`Time!`](#time) | Date of creation. | | <a id="packagedetailstypedependencylinks"></a>`dependencyLinks` | [`PackageDependencyLinkConnection`](#packagedependencylinkconnection) | Dependency link. (see [Connections](#connections)) | | <a id="packagedetailstypeid"></a>`id` | [`PackagesPackageID!`](#packagespackageid) | ID of the package. | @@ -12179,6 +12381,7 @@ Represents a file or directory in the project repository that has been locked. | <a id="pipelineconfigsource"></a>`configSource` | [`PipelineConfigSourceEnum`](#pipelineconfigsourceenum) | Configuration source of the pipeline (UNKNOWN_SOURCE, REPOSITORY_SOURCE, AUTO_DEVOPS_SOURCE, WEBIDE_SOURCE, REMOTE_SOURCE, EXTERNAL_PROJECT_SOURCE, BRIDGE_SOURCE, PARAMETER_SOURCE, COMPLIANCE_SOURCE). | | <a id="pipelinecoverage"></a>`coverage` | [`Float`](#float) | Coverage percentage. | | <a id="pipelinecreatedat"></a>`createdAt` | [`Time!`](#time) | Timestamp of the pipeline's creation. | +| <a id="pipelinedastprofile"></a>`dastProfile` | [`DastProfile`](#dastprofile) | DAST profile associated with the pipeline. Returns `null`if `dast_view_scans` feature flag is disabled. | | <a id="pipelinedetailedstatus"></a>`detailedStatus` | [`DetailedStatus!`](#detailedstatus) | Detailed status of the pipeline. | | <a id="pipelinedownstream"></a>`downstream` | [`PipelineConnection`](#pipelineconnection) | Pipelines this pipeline will trigger. (see [Connections](#connections)) | | <a id="pipelineduration"></a>`duration` | [`Int`](#int) | Duration of the pipeline in seconds. | @@ -12624,7 +12827,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | Name | Type | Description | | ---- | ---- | ----------- | | <a id="projectdastsitevalidationsnormalizedtargeturls"></a>`normalizedTargetUrls` | [`[String!]`](#string) | Normalized URL of the target to be scanned. | -| <a id="projectdastsitevalidationsstatus"></a>`status` | [`DastSiteValidationStatusEnum`](#dastsitevalidationstatusenum) | Status of the site validation. Ignored if `dast_failed_site_validations` feature flag is disabled. | +| <a id="projectdastsitevalidationsstatus"></a>`status` | [`DastSiteValidationStatusEnum`](#dastsitevalidationstatusenum) | Status of the site validation. | ##### `Project.environment` @@ -12702,11 +12905,13 @@ Returns [`Issue`](#issue). | <a id="projectissueauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the issue. | | <a id="projectissueclosedafter"></a>`closedAfter` | [`Time`](#time) | Issues closed after this date. | | <a id="projectissueclosedbefore"></a>`closedBefore` | [`Time`](#time) | Issues closed before this date. | +| <a id="projectissueconfidential"></a>`confidential` | [`Boolean`](#boolean) | Filter for confidential issues. If "false", excludes confidential issues. If "true", returns only confidential issues. | | <a id="projectissuecreatedafter"></a>`createdAfter` | [`Time`](#time) | Issues created after this date. | | <a id="projectissuecreatedbefore"></a>`createdBefore` | [`Time`](#time) | Issues created before this date. | | <a id="projectissueepicid"></a>`epicId` | [`String`](#string) | ID of an epic associated with the issues, "none" and "any" values are supported. | | <a id="projectissueiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | | <a id="projectissueiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | +| <a id="projectissueincludesubepics"></a>`includeSubepics` | [`Boolean`](#boolean) | Whether to include subepics when filtering issues by epicId. | | <a id="projectissueiterationid"></a>`iterationId` | [`[ID]`](#id) | List of iteration Global IDs applied to the issue. | | <a id="projectissueiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | | <a id="projectissuelabelname"></a>`labelName` | [`[String]`](#string) | Labels applied to this issue. | @@ -12714,7 +12919,7 @@ Returns [`Issue`](#issue). | <a id="projectissuemilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | | <a id="projectissuemyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="projectissuenot"></a>`not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | -| <a id="projectissuesearch"></a>`search` | [`String`](#string) | Search query for issue title or description. | +| <a id="projectissuesearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="projectissuesort"></a>`sort` | [`IssueSort`](#issuesort) | Sort issues by this criteria. | | <a id="projectissuestate"></a>`state` | [`IssuableState`](#issuablestate) | Current state of this issue. | | <a id="projectissuetypes"></a>`types` | [`[IssueType!]`](#issuetype) | Filter issues by the given issue types. | @@ -12738,6 +12943,7 @@ Returns [`IssueStatusCountsType`](#issuestatuscountstype). | <a id="projectissuestatuscountsauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the issue. | | <a id="projectissuestatuscountsclosedafter"></a>`closedAfter` | [`Time`](#time) | Issues closed after this date. | | <a id="projectissuestatuscountsclosedbefore"></a>`closedBefore` | [`Time`](#time) | Issues closed before this date. | +| <a id="projectissuestatuscountsconfidential"></a>`confidential` | [`Boolean`](#boolean) | Filter for confidential issues. If "false", excludes confidential issues. If "true", returns only confidential issues. | | <a id="projectissuestatuscountscreatedafter"></a>`createdAfter` | [`Time`](#time) | Issues created after this date. | | <a id="projectissuestatuscountscreatedbefore"></a>`createdBefore` | [`Time`](#time) | Issues created before this date. | | <a id="projectissuestatuscountsiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | @@ -12747,7 +12953,7 @@ Returns [`IssueStatusCountsType`](#issuestatuscountstype). | <a id="projectissuestatuscountsmilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | | <a id="projectissuestatuscountsmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="projectissuestatuscountsnot"></a>`not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | -| <a id="projectissuestatuscountssearch"></a>`search` | [`String`](#string) | Search query for issue title or description. | +| <a id="projectissuestatuscountssearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="projectissuestatuscountstypes"></a>`types` | [`[IssueType!]`](#issuetype) | Filter issues by the given issue types. | | <a id="projectissuestatuscountsupdatedafter"></a>`updatedAfter` | [`Time`](#time) | Issues updated after this date. | | <a id="projectissuestatuscountsupdatedbefore"></a>`updatedBefore` | [`Time`](#time) | Issues updated before this date. | @@ -12772,11 +12978,13 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectissuesauthorusername"></a>`authorUsername` | [`String`](#string) | Username of the author of the issue. | | <a id="projectissuesclosedafter"></a>`closedAfter` | [`Time`](#time) | Issues closed after this date. | | <a id="projectissuesclosedbefore"></a>`closedBefore` | [`Time`](#time) | Issues closed before this date. | +| <a id="projectissuesconfidential"></a>`confidential` | [`Boolean`](#boolean) | Filter for confidential issues. If "false", excludes confidential issues. If "true", returns only confidential issues. | | <a id="projectissuescreatedafter"></a>`createdAfter` | [`Time`](#time) | Issues created after this date. | | <a id="projectissuescreatedbefore"></a>`createdBefore` | [`Time`](#time) | Issues created before this date. | | <a id="projectissuesepicid"></a>`epicId` | [`String`](#string) | ID of an epic associated with the issues, "none" and "any" values are supported. | | <a id="projectissuesiid"></a>`iid` | [`String`](#string) | IID of the issue. For example, "1". | | <a id="projectissuesiids"></a>`iids` | [`[String!]`](#string) | List of IIDs of issues. For example, `["1", "2"]`. | +| <a id="projectissuesincludesubepics"></a>`includeSubepics` | [`Boolean`](#boolean) | Whether to include subepics when filtering issues by epicId. | | <a id="projectissuesiterationid"></a>`iterationId` | [`[ID]`](#id) | List of iteration Global IDs applied to the issue. | | <a id="projectissuesiterationwildcardid"></a>`iterationWildcardId` | [`IterationWildcardId`](#iterationwildcardid) | Filter by iteration ID wildcard. | | <a id="projectissueslabelname"></a>`labelName` | [`[String]`](#string) | Labels applied to this issue. | @@ -12784,7 +12992,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | <a id="projectissuesmilestonewildcardid"></a>`milestoneWildcardId` | [`MilestoneWildcardId`](#milestonewildcardid) | Filter issues by milestone ID wildcard. | | <a id="projectissuesmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. Wildcard values "NONE" and "ANY" are supported. | | <a id="projectissuesnot"></a>`not` | [`NegatedIssueFilterInput`](#negatedissuefilterinput) | Negated arguments. | -| <a id="projectissuessearch"></a>`search` | [`String`](#string) | Search query for issue title or description. | +| <a id="projectissuessearch"></a>`search` | [`String`](#string) | Search query for title or description. | | <a id="projectissuessort"></a>`sort` | [`IssueSort`](#issuesort) | Sort issues by this criteria. | | <a id="projectissuesstate"></a>`state` | [`IssuableState`](#issuablestate) | Current state of this issue. | | <a id="projectissuestypes"></a>`types` | [`[IssueType!]`](#issuetype) | Filter issues by the given issue types. | @@ -13196,6 +13404,7 @@ four standard [pagination arguments](#connection-pagination-arguments): | ---- | ---- | ----------- | | <a id="projectvulnerabilitieshasissues"></a>`hasIssues` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have linked issues. | | <a id="projectvulnerabilitieshasresolution"></a>`hasResolution` | [`Boolean`](#boolean) | Returns only the vulnerabilities which have been resolved on default branch. | +| <a id="projectvulnerabilitiesimage"></a>`image` | [`[String!]`](#string) | Filter vulnerabilities by location image. When this filter is present, the response only matches entries for a `reportType` that includes `container_scanning`, `cluster_image_scanning`. | | <a id="projectvulnerabilitiesprojectid"></a>`projectId` | [`[ID!]`](#id) | Filter vulnerabilities by project. | | <a id="projectvulnerabilitiesreporttype"></a>`reportType` | [`[VulnerabilityReportType!]`](#vulnerabilityreporttype) | Filter vulnerabilities by report type. | | <a id="projectvulnerabilitiesscanner"></a>`scanner` | [`[String!]`](#string) | Filter vulnerabilities by VulnerabilityScanner.externalId. | @@ -13524,7 +13733,7 @@ Returns [`[String!]`](#string). ##### `Repository.paginatedTree` -Paginated tree of the repository. Available only when feature flag `paginated_tree_graphql_query` is enabled. This flag is disabled by default, because the feature is experimental and is subject to change without notice. +Paginated tree of the repository. Available only when feature flag `paginated_tree_graphql_query` is enabled. This flag is enabled by default. Returns [`TreeConnection`](#treeconnection). @@ -13676,6 +13885,16 @@ Counts of requirements by their state. | <a id="runnerarchitecturedownloadlocation"></a>`downloadLocation` | [`String!`](#string) | Download location for the runner for the platform architecture. | | <a id="runnerarchitecturename"></a>`name` | [`String!`](#string) | Name of the runner platform architecture. | +### `RunnerPermissions` + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="runnerpermissionsdeleterunner"></a>`deleteRunner` | [`Boolean!`](#boolean) | Indicates the user can perform `delete_runner` on this resource. | +| <a id="runnerpermissionsreadrunner"></a>`readRunner` | [`Boolean!`](#boolean) | Indicates the user can perform `read_runner` on this resource. | +| <a id="runnerpermissionsupdaterunner"></a>`updateRunner` | [`Boolean!`](#boolean) | Indicates the user can perform `update_runner` on this resource. | + ### `RunnerPlatform` #### Fields @@ -13850,6 +14069,7 @@ A Sentry error. | <a id="sentrydetailederrorgitlabcommitpath"></a>`gitlabCommitPath` | [`String`](#string) | Path to the GitLab page for the GitLab commit attributed to the error. | | <a id="sentrydetailederrorgitlabissuepath"></a>`gitlabIssuePath` | [`String`](#string) | URL of GitLab Issue. | | <a id="sentrydetailederrorid"></a>`id` | [`ID!`](#id) | ID (global ID) of the error. | +| <a id="sentrydetailederrorintegrated"></a>`integrated` | [`Boolean`](#boolean) | Error tracking backend. | | <a id="sentrydetailederrorlastreleaselastcommit"></a>`lastReleaseLastCommit` | [`String`](#string) | Commit the error was last seen. | | <a id="sentrydetailederrorlastreleaseshortversion"></a>`lastReleaseShortVersion` | [`String`](#string) | Release short version the error was last seen. | | <a id="sentrydetailederrorlastreleaseversion"></a>`lastReleaseVersion` | [`String`](#string) | Release version the error was last seen. | @@ -14709,8 +14929,10 @@ Represents a vulnerability. | <a id="vulnerabilityhassolutions"></a>`hasSolutions` | [`Boolean`](#boolean) | Indicates whether there is a solution available for this vulnerability. | | <a id="vulnerabilityid"></a>`id` | [`ID!`](#id) | GraphQL ID of the vulnerability. | | <a id="vulnerabilityidentifiers"></a>`identifiers` | [`[VulnerabilityIdentifier!]!`](#vulnerabilityidentifier) | Identifiers of the vulnerability. | +| <a id="vulnerabilitylinks"></a>`links` | [`[VulnerabilityLink!]!`](#vulnerabilitylink) | List of links associated with the vulnerability. | | <a id="vulnerabilitylocation"></a>`location` | [`VulnerabilityLocation`](#vulnerabilitylocation) | Location metadata for the vulnerability. Its fields depend on the type of security scan that found the vulnerability. | | <a id="vulnerabilitymergerequest"></a>`mergeRequest` | [`MergeRequest`](#mergerequest) | Merge request that fixes the vulnerability. | +| <a id="vulnerabilitymessage"></a>`message` | [`String`](#string) | Short text description of the vulnerability. This may include the finding's specific information. | | <a id="vulnerabilitynotes"></a>`notes` | [`NoteConnection!`](#noteconnection) | All notes on this noteable. (see [Connections](#connections)) | | <a id="vulnerabilityprimaryidentifier"></a>`primaryIdentifier` | [`VulnerabilityIdentifier`](#vulnerabilityidentifier) | Primary identifier of the vulnerability. | | <a id="vulnerabilityproject"></a>`project` | [`Project`](#project) | Project on which the vulnerability was found. | @@ -14956,6 +15178,17 @@ Represents an issue link of a vulnerability. | <a id="vulnerabilityissuelinkissue"></a>`issue` | [`Issue!`](#issue) | Issue attached to issue link. | | <a id="vulnerabilityissuelinklinktype"></a>`linkType` | [`VulnerabilityIssueLinkType!`](#vulnerabilityissuelinktype) | Type of the issue link. | +### `VulnerabilityLink` + +Represents a link related to a vulnerability. + +#### Fields + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="vulnerabilitylinkname"></a>`name` | [`String`](#string) | Name of the link. | +| <a id="vulnerabilitylinkurl"></a>`url` | [`String!`](#string) | URL of the link. | + ### `VulnerabilityLocationContainerScanning` Represents the location of a vulnerability found by a container security scan. @@ -15345,10 +15578,10 @@ Values for sorting runners. | Value | Description | | ----- | ----------- | -| <a id="cirunnerstatusactive"></a>`ACTIVE` | A runner that is active. | -| <a id="cirunnerstatusnot_connected"></a>`NOT_CONNECTED` | A runner that is not connected. | -| <a id="cirunnerstatusoffline"></a>`OFFLINE` | A runner that is offline. | -| <a id="cirunnerstatusonline"></a>`ONLINE` | A runner that is online. | +| <a id="cirunnerstatusactive"></a>`ACTIVE` | A runner that is not paused. | +| <a id="cirunnerstatusnot_connected"></a>`NOT_CONNECTED` | A runner that has never contacted this instance. | +| <a id="cirunnerstatusoffline"></a>`OFFLINE` | A runner that has not contacted this instance within the last 2 hours. | +| <a id="cirunnerstatusonline"></a>`ONLINE` | A runner that contacted this instance within the last 2 hours. | | <a id="cirunnerstatuspaused"></a>`PAUSED` | A runner that is paused. | ### `CiRunnerType` @@ -15425,6 +15658,7 @@ Conan file types. | <a id="containerexpirationpolicyolderthanenumfourteen_days"></a>`FOURTEEN_DAYS` | 14 days until tags are automatically removed. | | <a id="containerexpirationpolicyolderthanenumninety_days"></a>`NINETY_DAYS` | 90 days until tags are automatically removed. | | <a id="containerexpirationpolicyolderthanenumseven_days"></a>`SEVEN_DAYS` | 7 days until tags are automatically removed. | +| <a id="containerexpirationpolicyolderthanenumsixty_days"></a>`SIXTY_DAYS` | 60 days until tags are automatically removed. | | <a id="containerexpirationpolicyolderthanenumthirty_days"></a>`THIRTY_DAYS` | 30 days until tags are automatically removed. | ### `ContainerRepositoryCleanupStatus` @@ -15750,6 +15984,14 @@ State of a GitLab issue or merge request. | <a id="issuablestatelocked"></a>`locked` | Discussion has been locked. | | <a id="issuablestateopened"></a>`opened` | In open state. | +### `IssueCreationIterationWildcardId` + +Iteration ID wildcard values for issue creation. + +| Value | Description | +| ----- | ----------- | +| <a id="issuecreationiterationwildcardidcurrent"></a>`CURRENT` | Current iteration. | + ### `IssueSort` Values for sorting issues. @@ -16013,7 +16255,7 @@ Milestone ID wildcard values. | <a id="milestonewildcardidany"></a>`ANY` | Milestone is assigned. | | <a id="milestonewildcardidnone"></a>`NONE` | No milestone is assigned. | | <a id="milestonewildcardidstarted"></a>`STARTED` | Milestone assigned is open and started (start date <= today). | -| <a id="milestonewildcardidupcoming"></a>`UPCOMING` | Milestone assigned is due closest in the future (due date > today). | +| <a id="milestonewildcardidupcoming"></a>`UPCOMING` | Milestone assigned is due in the future (due date > today). | ### `MoveType` @@ -16455,6 +16697,7 @@ Name of the feature that the callout is for. | <a id="usercalloutfeaturenameenumregistration_enabled_callout"></a>`REGISTRATION_ENABLED_CALLOUT` | Callout feature name for registration_enabled_callout. | | <a id="usercalloutfeaturenameenumsecurity_configuration_devops_alert"></a>`SECURITY_CONFIGURATION_DEVOPS_ALERT` | Callout feature name for security_configuration_devops_alert. | | <a id="usercalloutfeaturenameenumsecurity_configuration_upgrade_banner"></a>`SECURITY_CONFIGURATION_UPGRADE_BANNER` | Callout feature name for security_configuration_upgrade_banner. | +| <a id="usercalloutfeaturenameenumsecurity_newsletter_callout"></a>`SECURITY_NEWSLETTER_CALLOUT` | Callout feature name for security_newsletter_callout. | | <a id="usercalloutfeaturenameenumsuggest_pipeline"></a>`SUGGEST_PIPELINE` | Callout feature name for suggest_pipeline. | | <a id="usercalloutfeaturenameenumsuggest_popover_dismissed"></a>`SUGGEST_POPOVER_DISMISSED` | Callout feature name for suggest_popover_dismissed. | | <a id="usercalloutfeaturenameenumtabs_position_highlight"></a>`TABS_POSITION_HIGHLIGHT` | Callout feature name for tabs_position_highlight. | @@ -16646,6 +16889,12 @@ A `AnalyticsDevopsAdoptionEnabledNamespaceID` is a global ID. It is encoded as a An example `AnalyticsDevopsAdoptionEnabledNamespaceID` is: `"gid://gitlab/Analytics::DevopsAdoption::EnabledNamespace/1"`. +### `AuditEventsExternalAuditEventDestinationID` + +A `AuditEventsExternalAuditEventDestinationID` is a global ID. It is encoded as a string. + +An example `AuditEventsExternalAuditEventDestinationID` is: `"gid://gitlab/AuditEvents::ExternalAuditEventDestination/1"`. + ### `AwardableID` A `AwardableID` is a global ID. It is encoded as a string. @@ -16732,6 +16981,12 @@ A `CustomEmojiID` is a global ID. It is encoded as a string. An example `CustomEmojiID` is: `"gid://gitlab/CustomEmoji/1"`. +### `CustomerRelationsContactID` + +A `CustomerRelationsContactID` is a global ID. It is encoded as a string. + +An example `CustomerRelationsContactID` is: `"gid://gitlab/CustomerRelations::Contact/1"`. + ### `CustomerRelationsOrganizationID` A `CustomerRelationsOrganizationID` is a global ID. It is encoded as a string. @@ -17906,6 +18161,7 @@ Represents an escalation rule. | <a id="negatedissuefilterinputmilestonetitle"></a>`milestoneTitle` | [`[String!]`](#string) | Milestone not applied to this issue. | | <a id="negatedissuefilterinputmilestonewildcardid"></a>`milestoneWildcardId` | [`NegatedMilestoneWildcardId`](#negatedmilestonewildcardid) | Filter by negated milestone wildcard values. | | <a id="negatedissuefilterinputmyreactionemoji"></a>`myReactionEmoji` | [`String`](#string) | Filter by reaction emoji applied by the current user. | +| <a id="negatedissuefilterinputtypes"></a>`types` | [`[IssueType!]`](#issuetype) | Filters out issues by the given issue types. | | <a id="negatedissuefilterinputweight"></a>`weight` | [`String`](#string) | Weight not applied to the issue. | ### `OncallRotationActivePeriodInputType` @@ -18057,3 +18313,23 @@ A time-frame defined as a closed inclusive range of two dates. | <a id="vulnerabilityidentifierinputexternaltype"></a>`externalType` | [`String`](#string) | External type of the vulnerability identifier. | | <a id="vulnerabilityidentifierinputname"></a>`name` | [`String!`](#string) | Name of the vulnerability identifier. | | <a id="vulnerabilityidentifierinputurl"></a>`url` | [`String!`](#string) | URL of the vulnerability identifier. | + +### `VulnerabilityScannerInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="vulnerabilityscannerinputid"></a>`id` | [`String!`](#string) | Unique ID that identifies the scanner. | +| <a id="vulnerabilityscannerinputname"></a>`name` | [`String!`](#string) | Human readable value that identifies the analyzer, not required to be unique. | +| <a id="vulnerabilityscannerinputurl"></a>`url` | [`String!`](#string) | Link to more information about the analyzer. | +| <a id="vulnerabilityscannerinputvendor"></a>`vendor` | [`VulnerabilityScannerVendorInput`](#vulnerabilityscannervendorinput) | Information about vendor/maintainer of the scanner. | +| <a id="vulnerabilityscannerinputversion"></a>`version` | [`String!`](#string) | Version of the scanner. | + +### `VulnerabilityScannerVendorInput` + +#### Arguments + +| Name | Type | Description | +| ---- | ---- | ----------- | +| <a id="vulnerabilityscannervendorinputname"></a>`name` | [`String!`](#string) | Name of the vendor/maintainer. | diff --git a/doc/api/group_clusters.md b/doc/api/group_clusters.md index 83373368fc6..81ca45c4531 100644 --- a/doc/api/group_clusters.md +++ b/doc/api/group_clusters.md @@ -250,7 +250,7 @@ Parameters: NOTE: `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added -through the ["Add existing Kubernetes cluster"](../user/project/clusters/add_remove_clusters.md#add-existing-cluster) option or +through the ["Add existing Kubernetes cluster"](../user/project/clusters/add_existing_cluster.md) option or through the ["Add existing cluster to group"](#add-existing-cluster-to-group) endpoint. Example request: diff --git a/doc/api/group_import_export.md b/doc/api/group_import_export.md index 0a431cfdfbf..212a62516f1 100644 --- a/doc/api/group_import_export.md +++ b/doc/api/group_import_export.md @@ -57,8 +57,12 @@ GET /groups/:id/export/download | `id` | integer/string | yes | ID of the group owned by the authenticated user | ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \ - --remote-name "https://gitlab.example.com/api/v4/groups/1/export/download" +group=1 +token=secret +curl --request GET\ + --header "PRIVATE-TOKEN: ${token}" \ + --output download_group_${group}.tar.gz \ + "https://gitlab.example.com/api/v4/groups/${group}/export/download" ``` ```shell diff --git a/doc/api/group_repository_storage_moves.md b/doc/api/group_repository_storage_moves.md index a893bffb1f5..9d4120ec355 100644 --- a/doc/api/group_repository_storage_moves.md +++ b/doc/api/group_repository_storage_moves.md @@ -10,7 +10,7 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53016) in GitLab 13.9. Group repositories can be moved between storages. This API can help you when -[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster), for +[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrating-to-gitaly-cluster), for example, or to migrate a [group wiki](../user/project/wiki/index.md#group-wikis). As group repository storage moves are processed, they transition through different states. Values diff --git a/doc/api/groups.md b/doc/api/groups.md index bd4c7de567c..7efecfc2c9c 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -830,7 +830,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ## Transfer project to group -Transfer a project to the Group namespace. Available only to instance administrators, although an [alternative API endpoint](projects.md#transfer-a-project-to-a-new-namespace) is available which does not require instance administrator access. Transferring projects may fail when tagged packages exist in the project's repository. +Transfer a project to the Group namespace. Available only to instance administrators, although an [alternative API endpoint](projects.md#transfer-a-project-to-a-new-namespace) is available which does not require instance administrator role. Transferring projects may fail when tagged packages exist in the project's repository. ```plaintext POST /groups/:id/projects/:project_id diff --git a/doc/api/instance_clusters.md b/doc/api/instance_clusters.md index 4e0ec3bd433..58f88b26bc4 100644 --- a/doc/api/instance_clusters.md +++ b/doc/api/instance_clusters.md @@ -8,10 +8,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36001) in GitLab 13.2. -Instance-level Kubernetes clusters allow you to connect a Kubernetes cluster to the GitLab instance, which enables you to use the same cluster across multiple projects. [More information](../user/instance/clusters/index.md) +With [instance-level Kubernetes clusters](../user/instance/clusters/index.md), +you can connect a Kubernetes cluster to the GitLab instance and use the same cluster across all of +the projects within your instance. NOTE: -Users need administrator access to use these endpoints. +Users need the Administrator role to use these endpoints. ## List instance clusters @@ -240,7 +242,7 @@ Parameters: NOTE: `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added -through the [Add existing Kubernetes cluster](../user/project/clusters/add_remove_clusters.md#add-existing-cluster) option or +through the [Add existing Kubernetes cluster](../user/project/clusters/add_existing_cluster.md) option or through the [Add existing instance cluster](#add-existing-instance-cluster) endpoint. Example request: diff --git a/doc/api/integrations.md b/doc/api/integrations.md new file mode 100644 index 00000000000..3c649e8d044 --- /dev/null +++ b/doc/api/integrations.md @@ -0,0 +1,1566 @@ +--- +stage: Ecosystem +group: Integrations +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 +--- + +# Integrations API **(FREE)** + +This API enables you to work with external services that integrate with GitLab. + +NOTE: +In GitLab 14.4, the `services` endpoint was [renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/334500) to `integrations`. +Calls to the Integrations API can be made to both `/projects/:id/services` and `/projects/:id/integrations`. +The examples in this document refer to the endpoint at `/projects/:id/integrations`. + +This API requires an access token with the [Maintainer or Owner role](../user/permissions.md). + +## List all active integrations + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21330) in GitLab 12.7. + +Get a list of all active project integrations. + +```plaintext +GET /projects/:id/integrations +``` + +Example response: + +```json +[ + { + "id": 75, + "title": "Jenkins CI", + "slug": "jenkins", + "created_at": "2019-11-20T11:20:25.297Z", + "updated_at": "2019-11-20T12:24:37.498Z", + "active": true, + "commit_events": true, + "push_events": true, + "issues_events": true, + "confidential_issues_events": true, + "merge_requests_events": true, + "tag_push_events": false, + "note_events": true, + "confidential_note_events": true, + "pipeline_events": true, + "wiki_page_events": true, + "job_events": true, + "comment_on_event_enabled": true + }, + { + "id": 76, + "title": "Alerts endpoint", + "slug": "alerts", + "created_at": "2019-11-20T11:20:25.297Z", + "updated_at": "2019-11-20T12:24:37.498Z", + "active": true, + "commit_events": true, + "push_events": true, + "issues_events": true, + "confidential_issues_events": true, + "merge_requests_events": true, + "tag_push_events": true, + "note_events": true, + "confidential_note_events": true, + "pipeline_events": true, + "wiki_page_events": true, + "job_events": true, + "comment_on_event_enabled": true + } +] +``` + +## Asana + +Add commit messages as comments to Asana tasks. + +See also the [Asana integration documentation](../user/project/integrations/asana.md). + +### Create/Edit Asana integration + +Set Asana integration for a project. + +```plaintext +PUT /projects/:id/integrations/asana +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `api_key` | string | true | User API token. User must have access to task. All comments are attributed to this user. | +| `restrict_to_branch` | string | false | Comma-separated list of branches to be are automatically inspected. Leave blank to include all branches. | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Asana integration + +Delete Asana integration for a project. + +```plaintext +DELETE /projects/:id/integrations/asana +``` + +### Get Asana integration settings + +Get Asana integration settings for a project. + +```plaintext +GET /projects/:id/integrations/asana +``` + +## Assembla + +Project Management Software (Source Commits Endpoint) + +### Create/Edit Assembla integration + +Set Assembla integration for a project. + +```plaintext +PUT /projects/:id/integrations/assembla +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | true | The authentication token +| `subdomain` | string | false | The subdomain setting | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Assembla integration + +Delete Assembla integration for a project. + +```plaintext +DELETE /projects/:id/integrations/assembla +``` + +### Get Assembla integration settings + +Get Assembla integration settings for a project. + +```plaintext +GET /projects/:id/integrations/assembla +``` + +## Atlassian Bamboo CI + +A continuous integration and build server + +### Create/Edit Atlassian Bamboo CI integration + +Set Atlassian Bamboo CI integration for a project. + +> You must set up automatic revision labeling and a repository trigger in Bamboo. + +```plaintext +PUT /projects/:id/integrations/bamboo +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `bamboo_url` | string | true | Bamboo root URL. For example, `https://bamboo.example.com`. | +| `build_key` | string | true | Bamboo build plan key like KEY | +| `username` | string | true | A user with API access, if applicable | +| `password` | string | true | Password of the user | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Atlassian Bamboo CI integration + +Delete Atlassian Bamboo CI integration for a project. + +```plaintext +DELETE /projects/:id/integrations/bamboo +``` + +### Get Atlassian Bamboo CI integration settings + +Get Atlassian Bamboo CI integration settings for a project. + +```plaintext +GET /projects/:id/integrations/bamboo +``` + +## Bugzilla + +Bugzilla Issue Tracker + +### Create/Edit Bugzilla integration + +Set Bugzilla integration for a project. + +```plaintext +PUT /projects/:id/integrations/bugzilla +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `new_issue_url` | string | true | New Issue URL | +| `issues_url` | string | true | Issue URL | +| `project_url` | string | true | Project URL | +| `description` | string | false | Description | +| `title` | string | false | Title | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Bugzilla integration + +Delete Bugzilla integration for a project. + +```plaintext +DELETE /projects/:id/integrations/bugzilla +``` + +### Get Bugzilla integration settings + +Get Bugzilla integration settings for a project. + +```plaintext +GET /projects/:id/integrations/bugzilla +``` + +## Buildkite + +Continuous integration and deployments + +### Create/Edit Buildkite integration + +Set Buildkite integration for a project. + +```plaintext +PUT /projects/:id/integrations/buildkite +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | true | Buildkite project GitLab token | +| `project_url` | string | true | Pipeline URL. For example, `https://buildkite.com/example/pipeline` | +| `enable_ssl_verification` | boolean | false | DEPRECATED: This parameter has no effect since SSL verification is always enabled | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Buildkite integration + +Delete Buildkite integration for a project. + +```plaintext +DELETE /projects/:id/integrations/buildkite +``` + +### Get Buildkite integration settings + +Get Buildkite integration settings for a project. + +```plaintext +GET /projects/:id/integrations/buildkite +``` + +## Campfire + +Send notifications about push events to Campfire chat rooms. +[New users can no longer sign up for Campfire](https://basecamp.com/retired/campfire). + +### Create/Edit Campfire integration + +Set Campfire integration for a project. + +```plaintext +PUT /projects/:id/integrations/campfire +``` + +Parameters: + +| Parameter | Type | Required | Description | +|---------------|---------|----------|---------------------------------------------------------------------------------------------| +| `token` | string | true | Campfire API token. To find it, log into Campfire and select **My info**. | +| `subdomain` | string | false | Campfire subdomain. Text between `https://` and `.campfirenow.com` when you're logged in. | +| `room` | string | false | Campfire room. The last part of the URL when you're in a room. | +| `push_events` | boolean | false | Enable notifications for push events. | + +### Delete Campfire integration + +Delete Campfire integration for a project. + +```plaintext +DELETE /projects/:id/integrations/campfire +``` + +### Get Campfire integration settings + +Get Campfire integration settings for a project. + +```plaintext +GET /projects/:id/integrations/campfire +``` + +## Datadog + +Datadog system monitoring. + +### Create/Edit Datadog integration + +Set Datadog integration for a project. + +```plaintext +PUT /projects/:id/integrations/datadog +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `api_key` | string | true | API key used for authentication with Datadog | +| `api_url` | string | false | (Advanced) Define the full URL for your Datadog site directly | +| `datadog_site` | string | false | Choose the Datadog site to send data to. Set to `datadoghq.eu` to send data to the EU site | +| `datadog_service` | string | false | Name of this GitLab instance that all data will be tagged with | +| `datadog_env` | string | false | The environment tag that traces will be tagged with | + +### Delete Datadog integration + +Delete Datadog integration for a project. + +```plaintext +DELETE /projects/:id/integrations/datadog +``` + +### Get Datadog integration settings + +Get Datadog integration settings for a project. + +```plaintext +GET /projects/:id/integrations/datadog +``` + +## Unify Circuit + +Unify Circuit RTC and collaboration tool. + +### Create/Edit Unify Circuit integration + +Set Unify Circuit integration for a project. + +```plaintext +PUT /projects/:id/integrations/unify-circuit +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `webhook` | string | true | The Unify Circuit webhook. For example, `https://circuit.com/rest/v2/webhooks/incoming/...`. | +| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | +| `push_events` | boolean | false | Enable notifications for push events | +| `issues_events` | boolean | false | Enable notifications for issue events | +| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `tag_push_events` | boolean | false | Enable notifications for tag push events | +| `note_events` | boolean | false | Enable notifications for note events | +| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | +| `pipeline_events` | boolean | false | Enable notifications for pipeline events | +| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | + +### Delete Unify Circuit integration + +Delete Unify Circuit integration for a project. + +```plaintext +DELETE /projects/:id/integrations/unify-circuit +``` + +### Get Unify Circuit integration settings + +Get Unify Circuit integration settings for a project. + +```plaintext +GET /projects/:id/integrations/unify-circuit +``` + +## Webex Teams + +Webex Teams collaboration tool. + +### Create/Edit Webex Teams integration + +Set Webex Teams integration for a project. + +```plaintext +PUT /projects/:id/integrations/webex-teams +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `webhook` | string | true | The Webex Teams webhook. For example, `https://api.ciscospark.com/v1/webhooks/incoming/...`. | +| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | +| `push_events` | boolean | false | Enable notifications for push events | +| `issues_events` | boolean | false | Enable notifications for issue events | +| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `tag_push_events` | boolean | false | Enable notifications for tag push events | +| `note_events` | boolean | false | Enable notifications for note events | +| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | +| `pipeline_events` | boolean | false | Enable notifications for pipeline events | +| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | + +### Delete Webex Teams integration + +Delete Webex Teams integration for a project. + +```plaintext +DELETE /projects/:id/integrations/webex-teams +``` + +### Get Webex Teams integration settings + +Get Webex Teams integration settings for a project. + +```plaintext +GET /projects/:id/integrations/webex-teams +``` + +## Custom Issue Tracker + +Custom issue tracker + +### Create/Edit Custom Issue Tracker integration + +Set Custom Issue Tracker integration for a project. + +```plaintext +PUT /projects/:id/integrations/custom-issue-tracker +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `new_issue_url` | string | true | New Issue URL | +| `issues_url` | string | true | Issue URL | +| `project_url` | string | true | Project URL | +| `description` | string | false | Description | +| `title` | string | false | Title | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Custom Issue Tracker integration + +Delete Custom Issue Tracker integration for a project. + +```plaintext +DELETE /projects/:id/integrations/custom-issue-tracker +``` + +### Get Custom Issue Tracker integration settings + +Get Custom Issue Tracker integration settings for a project. + +```plaintext +GET /projects/:id/integrations/custom-issue-tracker +``` + +## Discord + +Send notifications about project events to a Discord channel. + +### Create/Edit Discord integration + +Set Discord integration for a project. + +```plaintext +PUT /projects/:id/integrations/discord +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `webhook` | string | true | Discord webhook. For example, `https://discord.com/api/webhooks/…` | + +### Delete Discord integration + +Delete Discord integration for a project. + +```plaintext +DELETE /projects/:id/integrations/discord +``` + +### Get Discord integration settings + +Get Discord integration settings for a project. + +```plaintext +GET /projects/:id/integrations/discord +``` + +## Drone CI + +Drone is a Continuous Integration platform built on Docker, written in Go + +### Create/Edit Drone CI integration + +Set Drone CI integration for a project. + +```plaintext +PUT /projects/:id/integrations/drone-ci +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | true | Drone CI project specific token | +| `drone_url` | string | true | `http://drone.example.com` | +| `enable_ssl_verification` | boolean | false | Enable SSL verification | +| `push_events` | boolean | false | Enable notifications for push events | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `tag_push_events` | boolean | false | Enable notifications for tag push events | + +### Delete Drone CI integration + +Delete Drone CI integration for a project. + +```plaintext +DELETE /projects/:id/integrations/drone-ci +``` + +### Get Drone CI integration settings + +Get Drone CI integration settings for a project. + +```plaintext +GET /projects/:id/integrations/drone-ci +``` + +## Emails on Push + +Email the commits and diff of each push to a list of recipients. + +### Create/Edit Emails on Push integration + +Set Emails on Push integration for a project. + +```plaintext +PUT /projects/:id/integrations/emails-on-push +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `recipients` | string | true | Emails separated by whitespace | +| `disable_diffs` | boolean | false | Disable code diffs | +| `send_from_committer_email` | boolean | false | Send from committer | +| `push_events` | boolean | false | Enable notifications for push events | +| `tag_push_events` | boolean | false | Enable notifications for tag push events | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". Notifications are always fired for tag pushes. The default value is "all" | + +### Delete Emails on Push integration + +Delete Emails on Push integration for a project. + +```plaintext +DELETE /projects/:id/integrations/emails-on-push +``` + +### Get Emails on Push integration settings + +Get Emails on Push integration settings for a project. + +```plaintext +GET /projects/:id/integrations/emails-on-push +``` + +## Engineering Workflow Management (EWM) + +Use IBM Engineering Workflow Management (EWM) as a project's issue tracker. + +### Create/Edit EWM integration + +Set EWM integration for a project. + +```plaintext +PUT /projects/:id/integrations/ewm +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `new_issue_url` | string | true | The URL to create an issue in EWM | +| `project_url` | string | true | The URL to the project in EWM | +| `issues_url` | string | true | The URL to view an issue in EWM. Must contain `:id` | + +### Delete EWM integration + +Delete EWM integration for a project. + +```plaintext +DELETE /projects/:id/integrations/ewm +``` + +### Get EWM integration settings + +Get EWM integration settings for a project. + +```plaintext +GET /projects/:id/integrations/ewm +``` + +## Confluence integration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220934) in GitLab 13.2. + +Replaces the link to the internal wiki with a link to a Confluence Cloud Workspace. + +### Create/Edit Confluence integration + +Set Confluence integration for a project. + +```plaintext +PUT /projects/:id/integrations/confluence +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `confluence_url` | string | true | The URL of the Confluence Cloud Workspace hosted on atlassian.net. | + +### Delete Confluence integration + +Delete Confluence integration for a project. + +```plaintext +DELETE /projects/:id/integrations/confluence +``` + +### Get Confluence integration settings + +Get Confluence integration settings for a project. + +```plaintext +GET /projects/:id/integrations/confluence +``` + +## External wiki + +Replaces the link to the internal wiki with a link to an external wiki. + +### Create/Edit External wiki integration + +Set External wiki integration for a project. + +```plaintext +PUT /projects/:id/integrations/external-wiki +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `external_wiki_url` | string | true | The URL of the external wiki | + +### Delete External wiki integration + +Delete External wiki integration for a project. + +```plaintext +DELETE /projects/:id/integrations/external-wiki +``` + +### Get External wiki integration settings + +Get External wiki integration settings for a project. + +```plaintext +GET /projects/:id/integrations/external-wiki +``` + +## Flowdock + +Flowdock is a ChatOps application for collaboration in software engineering +companies. You can send notifications from GitLab events to Flowdock flows. +For integration instructions, see the [Flowdock documentation](https://www.flowdock.com/help/gitlab). + +### Create/Edit Flowdock integration + +Set Flowdock integration for a project. + +```plaintext +PUT /projects/:id/integrations/flowdock +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | true | Flowdock Git source token | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Flowdock integration + +Delete Flowdock integration for a project. + +```plaintext +DELETE /projects/:id/integrations/flowdock +``` + +### Get Flowdock integration settings + +Get Flowdock integration settings for a project. + +```plaintext +GET /projects/:id/integrations/flowdock +``` + +## GitHub **(PREMIUM)** + +Code collaboration software. + +### Create/Edit GitHub integration + +Set GitHub integration for a project. + +```plaintext +PUT /projects/:id/integrations/github +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | true | GitHub API token with `repo:status` OAuth scope | +| `repository_url` | string | true | GitHub repository URL | +| `static_context` | boolean | false | Append instance name instead of branch to [status check name](../user/project/integrations/github.md#static--dynamic-status-check-names) | + +### Delete GitHub integration + +Delete GitHub integration for a project. + +```plaintext +DELETE /projects/:id/integrations/github +``` + +### Get GitHub integration settings + +Get GitHub integration settings for a project. + +```plaintext +GET /projects/:id/integrations/github +``` + +## Hangouts Chat + +Google Workspace team collaboration tool. + +### Create/Edit Hangouts Chat integration + +Set Hangouts Chat integration for a project. + +```plaintext +PUT /projects/:id/integrations/hangouts-chat +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `webhook` | string | true | The Hangouts Chat webhook. For example, `https://chat.googleapis.com/v1/spaces...`. | +| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | +| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | +| `push_events` | boolean | false | Enable notifications for push events | +| `issues_events` | boolean | false | Enable notifications for issue events | +| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `tag_push_events` | boolean | false | Enable notifications for tag push events | +| `note_events` | boolean | false | Enable notifications for note events | +| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | +| `pipeline_events` | boolean | false | Enable notifications for pipeline events | +| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | + +### Delete Hangouts Chat integration + +Delete Hangouts Chat integration for a project. + +```plaintext +DELETE /projects/:id/integrations/hangouts-chat +``` + +### Get Hangouts Chat integration settings + +Get Hangouts Chat integration settings for a project. + +```plaintext +GET /projects/:id/integrations/hangouts-chat +``` + +## Irker (IRC gateway) + +Send IRC messages, on update, to a list of recipients through an irker gateway. + +For more information, see the [irker integration documentation](../user/project/integrations/irker.md). + +### Create/Edit Irker (IRC gateway) integration + +Set Irker (IRC gateway) integration for a project. + +```plaintext +PUT /projects/:id/integrations/irker +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `recipients` | string | true | Recipients/channels separated by whitespaces | +| `default_irc_uri` | string | false | `irc://irc.network.net:6697/` | +| `server_host` | string | false | localhost | +| `server_port` | integer | false | 6659 | +| `colorize_messages` | boolean | false | Colorize messages | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Irker (IRC gateway) integration + +Delete Irker (IRC gateway) integration for a project. + +```plaintext +DELETE /projects/:id/integrations/irker +``` + +### Get Irker (IRC gateway) integration settings + +Get Irker (IRC gateway) integration settings for a project. + +```plaintext +GET /projects/:id/integrations/irker +``` + +## Jira + +Jira issue tracker. + +### Get Jira integration settings + +Get Jira integration settings for a project. + +```plaintext +GET /projects/:id/integrations/jira +``` + +### Create/Edit Jira integration + +Set Jira integration for a project. + +```plaintext +PUT /projects/:id/integrations/jira +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `url` | string | yes | The URL to the Jira project which is being linked to this GitLab project. For example, `https://jira.example.com`. | +| `api_url` | string | no | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. | +| `username` | string | yes | The username of the user created to be used with GitLab/Jira. | +| `password` | string | yes | The password of the user created to be used with GitLab/Jira. | +| `active` | boolean | no | Activates or deactivates the integration. Defaults to false (deactivated). | +| `jira_issue_transition_automatic` | boolean | no | Enable [automatic issue transitions](../integration/jira/issues.md#automatic-issue-transitions). Takes precedence over `jira_issue_transition_id` if enabled. Defaults to `false` | +| `jira_issue_transition_id` | string | no | The ID of one or more transitions for [custom issue transitions](../integration/jira/issues.md#custom-issue-transitions). Ignored if `jira_issue_transition_automatic` is enabled. Defaults to a blank string, which disables custom transitions. | +| `commit_events` | boolean | false | Enable notifications for commit events | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `comment_on_event_enabled` | boolean | false | Enable comments inside Jira issues on each GitLab event (commit / merge request) | + +### Delete Jira integration + +Remove all previously Jira integrations from a project. + +```plaintext +DELETE /projects/:id/integrations/jira +``` + +## Slack Slash Commands + +Ability to receive slash commands from a Slack chat instance. + +### Get Slack Slash Command integration settings + +Get Slack Slash Command integration settings for a project. + +```plaintext +GET /projects/:id/integrations/slack-slash-commands +``` + +Example response: + +```json +{ + "id": 4, + "title": "Slack slash commands", + "slug": "slack-slash-commands", + "created_at": "2017-06-27T05:51:39-07:00", + "updated_at": "2017-06-27T05:51:39-07:00", + "active": true, + "push_events": true, + "issues_events": true, + "confidential_issues_events": true, + "merge_requests_events": true, + "tag_push_events": true, + "note_events": true, + "job_events": true, + "pipeline_events": true, + "comment_on_event_enabled": false, + "properties": { + "token": "<your_access_token>" + } +} +``` + +### Create/Edit Slack Slash Commands integration + +Set Slack Slash Command for a project. + +```plaintext +PUT /projects/:id/integrations/slack-slash-commands +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | yes | The Slack token | + +### Delete Slack Slash Command integration + +Delete Slack Slash Command integration for a project. + +```plaintext +DELETE /projects/:id/integrations/slack-slash-commands +``` + +## Mattermost Slash Commands + +Ability to receive slash commands from a Mattermost chat instance. + +### Get Mattermost Slash Command integration settings + +Get Mattermost Slash Command integration settings for a project. + +```plaintext +GET /projects/:id/integrations/mattermost-slash-commands +``` + +### Create/Edit Mattermost Slash Command integration + +Set Mattermost Slash Command for a project. + +```plaintext +PUT /projects/:id/integrations/mattermost-slash-commands +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | yes | The Mattermost token | +| `username` | string | no | The username to use to post the message | + +### Delete Mattermost Slash Command integration + +Delete Mattermost Slash Command integration for a project. + +```plaintext +DELETE /projects/:id/integrations/mattermost-slash-commands +``` + +## Packagist + +Update your project on Packagist (the main Composer repository) when commits or tags are pushed to GitLab. + +### Create/Edit Packagist integration + +Set Packagist integration for a project. + +```plaintext +PUT /projects/:id/integrations/packagist +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `username` | string | yes | The username of a Packagist account | +| `token` | string | yes | API token to the Packagist server | +| `server` | boolean | no | URL of the Packagist server. Leave blank for default: <https://packagist.org> | +| `push_events` | boolean | false | Enable notifications for push events | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `tag_push_events` | boolean | false | Enable notifications for tag push events | + +### Delete Packagist integration + +Delete Packagist integration for a project. + +```plaintext +DELETE /projects/:id/integrations/packagist +``` + +### Get Packagist integration settings + +Get Packagist integration settings for a project. + +```plaintext +GET /projects/:id/integrations/packagist +``` + +## Pipeline-Emails + +Get emails for GitLab CI/CD pipelines. + +### Create/Edit Pipeline-Emails integration + +Set Pipeline-Emails integration for a project. + +```plaintext +PUT /projects/:id/integrations/pipelines-email +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `recipients` | string | yes | Comma-separated list of recipient email addresses | +| `add_pusher` | boolean | no | Add pusher to recipients list | +| `notify_only_broken_pipelines` | boolean | no | Notify only broken pipelines | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected. The default value is "default" | +| `notify_only_default_branch` | boolean | no | Send notifications only for the default branch ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28271)) | +| `pipeline_events` | boolean | false | Enable notifications for pipeline events | + +### Delete Pipeline-Emails integration + +Delete Pipeline-Emails integration for a project. + +```plaintext +DELETE /projects/:id/integrations/pipelines-email +``` + +### Get Pipeline-Emails integration settings + +Get Pipeline-Emails integration settings for a project. + +```plaintext +GET /projects/:id/integrations/pipelines-email +``` + +## Pivotal Tracker + +Add commit messages as comments to Pivotal Tracker stories. + +See also the [Pivotal Tracker integration documentation](../user/project/integrations/pivotal_tracker.md). + +### Create/Edit Pivotal Tracker integration + +Set Pivotal Tracker integration for a project. + +```plaintext +PUT /projects/:id/integrations/pivotaltracker +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | true | The Pivotal Tracker token | +| `restrict_to_branch` | boolean | false | Comma-separated list of branches to automatically inspect. Leave blank to include all branches. | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Pivotal Tracker integration + +Delete Pivotal Tracker integration for a project. + +```plaintext +DELETE /projects/:id/integrations/pivotaltracker +``` + +### Get Pivotal Tracker integration settings + +Get Pivotal Tracker integration settings for a project. + +```plaintext +GET /projects/:id/integrations/pivotaltracker +``` + +## Prometheus + +Prometheus is a powerful time-series monitoring service. + +### Create/Edit Prometheus integration + +Set Prometheus integration for a project. + +```plaintext +PUT /projects/:id/integrations/prometheus +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `api_url` | string | true | Prometheus API Base URL. For example, `http://prometheus.example.com/`. | +| `google_iap_audience_client_id` | string | false | Client ID of the IAP secured resource (looks like IAP_CLIENT_ID.apps.googleusercontent.com) | +| `google_iap_service_account_json` | string | false | `credentials.json` file for your service account, like { "type": "service_account", "project_id": ... } | + +### Delete Prometheus integration + +Delete Prometheus integration for a project. + +```plaintext +DELETE /projects/:id/integrations/prometheus +``` + +### Get Prometheus integration settings + +Get Prometheus integration settings for a project. + +```plaintext +GET /projects/:id/integrations/prometheus +``` + +## Pushover + +Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop. + +### Create/Edit Pushover integration + +Set Pushover integration for a project. + +```plaintext +PUT /projects/:id/integrations/pushover +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `api_key` | string | true | Your application key | +| `user_key` | string | true | Your user key | +| `priority` | string | true | The priority | +| `device` | string | false | Leave blank for all active devices | +| `sound` | string | false | The sound of the notification | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Pushover integration + +Delete Pushover integration for a project. + +```plaintext +DELETE /projects/:id/integrations/pushover +``` + +### Get Pushover integration settings + +Get Pushover integration settings for a project. + +```plaintext +GET /projects/:id/integrations/pushover +``` + +## Redmine + +Redmine issue tracker + +### Create/Edit Redmine integration + +Set Redmine integration for a project. + +```plaintext +PUT /projects/:id/integrations/redmine +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `new_issue_url` | string | true | New Issue URL | +| `project_url` | string | true | Project URL | +| `issues_url` | string | true | Issue URL | +| `description` | string | false | Description | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete Redmine integration + +Delete Redmine integration for a project. + +```plaintext +DELETE /projects/:id/integrations/redmine +``` + +### Get Redmine integration settings + +Get Redmine integration settings for a project. + +```plaintext +GET /projects/:id/integrations/redmine +``` + +## Slack notifications + +Receive event notifications in Slack + +### Create/Edit Slack integration + +Set Slack integration for a project. + +```plaintext +PUT /projects/:id/integrations/slack +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `webhook` | string | true | `https://hooks.slack.com/services/...` | +| `username` | string | false | username | +| `channel` | string | false | Default channel to use if others are not configured | +| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | +| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | +| `commit_events` | boolean | false | Enable notifications for commit events | +| `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications | +| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | +| `confidential_note_channel` | string | false | The name of the channel to receive confidential note events notifications | +| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | +| `deployment_channel` | string | false | The name of the channel to receive deployment events notifications | +| `deployment_events` | boolean | false | Enable notifications for deployment events | +| `issue_channel` | string | false | The name of the channel to receive issues events notifications | +| `issues_events` | boolean | false | Enable notifications for issue events | +| `job_events` | boolean | false | Enable notifications for job events | +| `merge_request_channel` | string | false | The name of the channel to receive merge request events notifications | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `note_channel` | string | false | The name of the channel to receive note events notifications | +| `note_events` | boolean | false | Enable notifications for note events | +| `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications | +| `pipeline_events` | boolean | false | Enable notifications for pipeline events | +| `push_channel` | string | false | The name of the channel to receive push events notifications | +| `push_events` | boolean | false | Enable notifications for push events | +| `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications | +| `tag_push_events` | boolean | false | Enable notifications for tag push events | +| `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications | +| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | + +### Delete Slack integration + +Delete Slack integration for a project. + +```plaintext +DELETE /projects/:id/integrations/slack +``` + +### Get Slack integration settings + +Get Slack integration settings for a project. + +```plaintext +GET /projects/:id/integrations/slack +``` + +## Microsoft Teams + +Group Chat Software + +### Create/Edit Microsoft Teams integration + +Set Microsoft Teams integration for a project. + +```plaintext +PUT /projects/:id/integrations/microsoft-teams +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `webhook` | string | true | The Microsoft Teams webhook. For example, `https://outlook.office.com/webhook/...` | +| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | +| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | +| `push_events` | boolean | false | Enable notifications for push events | +| `issues_events` | boolean | false | Enable notifications for issue events | +| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `tag_push_events` | boolean | false | Enable notifications for tag push events | +| `note_events` | boolean | false | Enable notifications for note events | +| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | +| `pipeline_events` | boolean | false | Enable notifications for pipeline events | +| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | + +### Delete Microsoft Teams integration + +Delete Microsoft Teams integration for a project. + +```plaintext +DELETE /projects/:id/integrations/microsoft-teams +``` + +### Get Microsoft Teams integration settings + +Get Microsoft Teams integration settings for a project. + +```plaintext +GET /projects/:id/integrations/microsoft-teams +``` + +## Mattermost notifications + +Receive event notifications in Mattermost + +### Create/Edit Mattermost notifications integration + +Set Mattermost notifications integration for a project. + +```plaintext +PUT /projects/:id/integrations/mattermost +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `webhook` | string | true | The Mattermost webhook. For example, `http://mattermost_host/hooks/...` | +| `username` | string | false | username | +| `channel` | string | false | Default channel to use if others are not configured | +| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | +| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | +| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | +| `push_events` | boolean | false | Enable notifications for push events | +| `issues_events` | boolean | false | Enable notifications for issue events | +| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `tag_push_events` | boolean | false | Enable notifications for tag push events | +| `note_events` | boolean | false | Enable notifications for note events | +| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | +| `pipeline_events` | boolean | false | Enable notifications for pipeline events | +| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | +| `push_channel` | string | false | The name of the channel to receive push events notifications | +| `issue_channel` | string | false | The name of the channel to receive issues events notifications | +| `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications | +| `merge_request_channel` | string | false | The name of the channel to receive merge request events notifications | +| `note_channel` | string | false | The name of the channel to receive note events notifications | +| `confidential_note_channel` | string | false | The name of the channel to receive confidential note events notifications | +| `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications | +| `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications | +| `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications | + +### Delete Mattermost notifications integration + +Delete Mattermost notifications integration for a project. + +```plaintext +DELETE /projects/:id/integrations/mattermost +``` + +### Get Mattermost notifications integration settings + +Get Mattermost notifications integration settings for a project. + +```plaintext +GET /projects/:id/integrations/mattermost +``` + +## JetBrains TeamCity CI + +A continuous integration and build server + +### Create/Edit JetBrains TeamCity CI integration + +Set JetBrains TeamCity CI integration for a project. + +> The build configuration in TeamCity must use the build format number `%build.vcs.number%`. Configure monitoring of all branches so merge requests build. That setting is in the VSC root advanced settings. + +```plaintext +PUT /projects/:id/integrations/teamcity +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `teamcity_url` | string | true | TeamCity root URL. For example, `https://teamcity.example.com` | +| `build_type` | string | true | Build configuration ID | +| `username` | string | true | A user with permissions to trigger a manual build | +| `password` | string | true | The password of the user | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete JetBrains TeamCity CI integration + +Delete JetBrains TeamCity CI integration for a project. + +```plaintext +DELETE /projects/:id/integrations/teamcity +``` + +### Get JetBrains TeamCity CI integration settings + +Get JetBrains TeamCity CI integration settings for a project. + +```plaintext +GET /projects/:id/integrations/teamcity +``` + +## Jenkins CI + +A continuous integration and build server + +### Create/Edit Jenkins CI integration + +Set Jenkins CI integration for a project. + +```plaintext +PUT /projects/:id/integrations/jenkins +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `jenkins_url` | string | true | Jenkins URL like `http://jenkins.example.com`. | +| `project_name` | string | true | The URL-friendly project name. Example: `my_project_name`. | +| `username` | string | false | Username for authentication with the Jenkins server, if authentication is required by the server. | +| `password` | string | false | Password for authentication with the Jenkins server, if authentication is required by the server. | +| `push_events` | boolean | false | Enable notifications for push events. | +| `merge_requests_events` | boolean | false | Enable notifications for merge request events. | +| `tag_push_events` | boolean | false | Enable notifications for tag push events. | + +### Delete Jenkins CI integration + +Delete Jenkins CI integration for a project. + +```plaintext +DELETE /projects/:id/integrations/jenkins +``` + +### Get Jenkins CI integration settings + +Get Jenkins CI integration settings for a project. + +```plaintext +GET /projects/:id/integrations/jenkins +``` + +## Jenkins CI (Deprecated) integration + +A continuous integration and build server + +NOTE: +This integration was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) in GitLab 13.0. + +### Create/Edit Jenkins CI (Deprecated) integration + +Set Jenkins CI (Deprecated) integration for a project. + +```plaintext +PUT /projects/:id/integrations/jenkins-deprecated +``` + +Parameters: + +- `project_url` (**required**) - Jenkins project URL like `http://jenkins.example.com/job/my-project/` +- `multiproject_enabled` (optional) - Multi-project mode is configured in Jenkins GitLab Hook plugin +- `pass_unstable` (optional) - Unstable builds are treated as passing + +### Delete Jenkins CI (Deprecated) integration + +Delete Jenkins CI (Deprecated) integration for a project. + +```plaintext +DELETE /projects/:id/integrations/jenkins-deprecated +``` + +### Get Jenkins CI (Deprecated) integration settings + +Get Jenkins CI (Deprecated) integration settings for a project. + +```plaintext +GET /projects/:id/integrations/jenkins-deprecated +``` + +## MockCI + +Mock an external CI. See [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service) for an example of a companion mock integration. + +This integration is only available when your environment is set to development. + +### Create/Edit MockCI integration + +Set MockCI integration for a project. + +```plaintext +PUT /projects/:id/integrations/mock-ci +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `mock_service_url` | string | true | `http://localhost:4004` | + +### Delete MockCI integration + +Delete MockCI integration for a project. + +```plaintext +DELETE /projects/:id/integrations/mock-ci +``` + +### Get MockCI integration settings + +Get MockCI integration settings for a project. + +```plaintext +GET /projects/:id/integrations/mock-ci +``` + +## YouTrack + +YouTrack issue tracker + +### Create/Edit YouTrack integration + +Set YouTrack integration for a project. + +```plaintext +PUT /projects/:id/integrations/youtrack +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `issues_url` | string | true | Issue URL | +| `project_url` | string | true | Project URL | +| `description` | string | false | Description | +| `push_events` | boolean | false | Enable notifications for push events | + +### Delete YouTrack integration + +Delete YouTrack integration for a project. + +```plaintext +DELETE /projects/:id/integrations/youtrack +``` + +### Get YouTrack integration settings + +Get YouTrack integration settings for a project. + +```plaintext +GET /projects/:id/integrations/youtrack +``` diff --git a/doc/api/issues.md b/doc/api/issues.md index 97d0fd3ce8f..204d75e9ee4 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -1487,6 +1487,113 @@ NOTE: The `closed_by` attribute was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17042) in GitLab 10.6. This value is only present for issues closed after GitLab 10.6 and if the user account that closed the issue still exists. +## Clone an issue + +Clone the issue to given project. If the user has insufficient permissions, +an error message with status code `400` is returned. + +Copies as much data as possible as long as the target project contains equivalent labels, milestones, +and so on. + +```plaintext +POST /projects/:id/issues/:issue_iid/clone +``` + +| Attribute | Type | Required | Description | +| --------------- | -------------- | ---------------------- | --------------------------------- | +| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | +| `issue_iid` | integer | **{check-circle}** Yes | Internal ID of a project's issue. | +| `to_project_id` | integer | **{check-circle}** Yes | ID of the new project. | +| `with_notes` | boolean | **{dotted-circle}** No | Clone the issue with [notes](notes.md). Default is `false`. | + +```shell +curl --request POST \ +--header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/1/clone?with_notes=true&to_project_id=6" +``` + +Example response: + +```json +{ + "id":290, + "iid":1, + "project_id":143, + "title":"foo", + "description":"closed", + "state":"opened", + "created_at":"2021-09-14T22:24:11.696Z", + "updated_at":"2021-09-14T22:24:11.696Z", + "closed_at":null, + "closed_by":null, + "labels":[ + + ], + "milestone":null, + "assignees":[ + { + "id":179, + "name":"John Doe2", + "username":"john", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/10fc7f102be8de7657fb4d80898bbfe3?s=80\u0026d=identicon", + "web_url":"https://gitlab.example.com/john" + } + ], + "author":{ + "id":179, + "name":"John Doe2", + "username":"john", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/10fc7f102be8de7657fb4d80898bbfe3?s=80\u0026d=identicon", + "web_url":"https://gitlab.example.com/john" + }, + "type":"ISSUE", + "assignee":{ + "id":179, + "name":"John Doe2", + "username":"john", + "state":"active", + "avatar_url":"https://www.gravatar.com/avatar/10fc7f102be8de7657fb4d80898bbfe3?s=80\u0026d=identicon", + "web_url":"https://gitlab.example.com/john" + }, + "user_notes_count":1, + "merge_requests_count":0, + "upvotes":0, + "downvotes":0, + "due_date":null, + "confidential":false, + "discussion_locked":null, + "issue_type":"issue", + "web_url":"https://gitlab.example.com/namespace1/project2/-/issues/1", + "time_stats":{ + "time_estimate":0, + "total_time_spent":0, + "human_time_estimate":null, + "human_total_time_spent":null + }, + "task_completion_status":{ + "count":0, + "completed_count":0 + }, + "blocking_issues_count":0, + "has_tasks":false, + "_links":{ + "self":"https://gitlab.example.com/api/v4/projects/143/issues/1", + "notes":"https://gitlab.example.com/api/v4/projects/143/issues/1/notes", + "award_emoji":"https://gitlab.example.com/api/v4/projects/143/issues/1/award_emoji", + "project":"https://gitlab.example.com/api/v4/projects/143" + }, + "references":{ + "short":"#1", + "relative":"#1", + "full":"namespace1/project2#1" + }, + "subscribed":true, + "moved_to_id":null, + "service_desk_reply_to":null +} +``` + ## Subscribe to an issue Subscribes the authenticated user to an issue to receive notifications. diff --git a/doc/api/members.md b/doc/api/members.md index 0b8cf686b8c..44e58f49d3b 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -336,7 +336,7 @@ The response represents only direct memberships. Inherited memberships are not i This API endpoint works on top-level groups only. It does not work on subgroups. -This API endpoint requires permission to admin memberships for the group. +This API endpoint requires permission to administer memberships for the group. This API endpoint takes [pagination](index.md#pagination) parameters `page` and `per_page` to restrict the list of memberships. @@ -561,7 +561,12 @@ Example response: ## Remove a member from a group or project -Removes a user from a group or project. +Removes a user from a group or project where the user has been explicitly assigned a role. + +The user needs to be a group member to qualify for removal. +For example, if the user was added directly to a project within the group but not this +group explicitly, you cannot use this API to remove them. See +[Remove a billable member from a group](#remove-a-billable-member-from-a-group) for an alternative approach. ```plaintext DELETE /groups/:id/members/:user_id diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index b4403e1d9b9..4ede95ea189 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -2,7 +2,6 @@ stage: Create group: Source Code 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" -type: reference, api --- # Merge request approvals API **(PREMIUM)** @@ -15,8 +14,7 @@ in the project. Must be authenticated for all endpoints. ### Get Configuration -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in GitLab 10.6. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. You can request information about a project's approval configuration using the following endpoint: @@ -44,8 +42,7 @@ GET /projects/:id/approvals ### Change configuration -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in GitLab 10.6. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. If you are allowed to, you can change approval configuration using the following endpoint: @@ -180,7 +177,7 @@ GET /projects/:id/approval_rules ### Get a single project-level rule -> - Introduced 13.7. +> Introduced in GitLab 13.7. You can request information about a single project approval rules using the following endpoint: @@ -294,9 +291,10 @@ POST /projects/:id/approval_rules | `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) | | `name` | string | yes | The name of the approval rule | | `approvals_required` | integer | yes | The number of required approvals for this rule | +| `rule_type` | string | no | The type of rule. `any_approver` is a pre-configured default rule with `approvals_required` at `0`. Other rules are `regular`. | `user_ids` | Array | no | The ids of users as approvers | | `group_ids` | Array | no | The ids of groups as approvers | -| `protected_branch_ids` | Array | no | **(PREMIUM)** The ids of protected branches to scope the rule by | +| `protected_branch_ids` | Array | no | **(PREMIUM)** The ids of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | ```json { @@ -379,6 +377,23 @@ POST /projects/:id/approval_rules } ``` +You can increase the default number of 0 required approvers like this: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header 'Content-Type: application/json' \ + --data '{"name": "Any name", "rule_type": "any_approver", "approvals_required": 2}' +``` + +Another example is creating an additional, user-specific rule: + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + --header 'Content-Type: application/json' \ + --data '{"name": "Name of your rule", "approvals_required": 3, "user_ids": [123, 456, 789]}' \ + https://gitlab.example.com/api/v4/projects/<project_id>/approval_rules +``` + ### Update project-level rule > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3. @@ -402,7 +417,7 @@ PUT /projects/:id/approval_rules/:approval_rule_id | `approvals_required` | integer | yes | The number of required approvals for this rule | | `user_ids` | Array | no | The ids of users as approvers | | `group_ids` | Array | no | The ids of groups as approvers | -| `protected_branch_ids` | Array | no | **(PREMIUM)** The ids of protected branches to scope the rule by | +| `protected_branch_ids` | Array | no | **(PREMIUM)** The ids of protected branches to scope the rule by. To identify the ID, [use the API](protected_branches.md#list-protected-branches). | ```json { @@ -509,8 +524,7 @@ Configuration for approvals on a specific Merge Request. Must be authenticated f ### Get Configuration -> - Introduced in GitLab 8.9. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. You can request information about a merge request's approval status using the following endpoint: @@ -556,8 +570,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals ### Change approval configuration -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/183) in GitLab 10.6. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. If you are allowed to, you can change `approvals_required` using the following endpoint: @@ -937,8 +950,7 @@ These are system generated rules. ## Approve Merge Request -> - Introduced in GitLab 8.9. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. If you are allowed to, you can approve a merge request using the following endpoint: @@ -1001,8 +1013,7 @@ does not match, the response code is `409`. ## Unapprove Merge Request -> - Introduced in GitLab 9.0. -> - Moved to GitLab Premium in 13.9. +> Moved to GitLab Premium in 13.9. If you did approve a merge request, you can unapprove it using the following endpoint: diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index abf9d7af229..8a8a54a753a 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -5,15 +5,15 @@ group: Access 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/#designated-technical-writers --- -# GitLab as an OAuth 2.0 provider **(FREE)** +# OAuth 2.0 identity provider API **(FREE)** -This document covers using the [OAuth2](https://oauth.net/2/) protocol to allow -other services to access GitLab resources on user's behalf. +GitLab provides an API to allow third-party services to access GitLab resources on a user's behalf +with the [OAuth2](https://oauth.net/2/) protocol. -If you want GitLab to be an OAuth authentication service provider to sign into -other services, see the [OAuth2 authentication service provider](../integration/oauth_provider.md) -documentation. This functionality is based on the -[doorkeeper Ruby gem](https://github.com/doorkeeper-gem/doorkeeper). +To configure GitLab for this, see +[Configure GitLab as an OAuth 2.0 authentication identity provider](../integration/oauth_provider.md). + +This functionality is based on the [doorkeeper Ruby gem](https://github.com/doorkeeper-gem/doorkeeper). ## Supported OAuth 2.0 flows @@ -25,7 +25,7 @@ GitLab supports the following authorization flows: - **Authorization code:** Secure and common flow. Recommended option for secure server-side apps. - **Implicit grant:** Originally designed for user-agent only apps, such as - single page web apps running on GitLab Pages). + single page web apps running on GitLab Pages. The [Internet Engineering Task Force (IETF)](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-09#section-2.1.2) recommends against Implicit grant flow. - **Resource owner password credentials:** To be used **only** for securely @@ -412,6 +412,16 @@ prevent breaking changes introduced in [doorkeeper 5.0.2](https://github.com/doo Don't rely on these fields as they are slated for removal in a later release. +## Revoke a token + +To revoke a token, use the `revoke` endpoint. The API returns a 200 response code and an empty +JSON hash to indicate success. + +```ruby +parameters = 'client_id=APP_ID&client_secret=APP_SECRET&token=TOKEN' +RestClient.post 'https://gitlab.example.com/oauth/revoke', parameters +``` + ## OAuth 2.0 tokens and GitLab registries Standard OAuth 2.0 tokens support different degrees of access to GitLab diff --git a/doc/api/packages/debian.md b/doc/api/packages/debian.md index 154c99d7e0a..66377850c49 100644 --- a/doc/api/packages/debian.md +++ b/doc/api/packages/debian.md @@ -78,7 +78,7 @@ GET projects/:id/packages/debian/pool/:distribution/:letter/:package_name/:packa | `letter` | string | yes | The Debian Classification (first-letter or lib-first-letter). | | `package_name` | string | yes | The source package name. | | `package_version` | string | yes | The source package version. | -| `file_name` | string | yes | The file name. | +| `file_name` | string | yes | The filename. | ```shell curl --header "Private-Token: <personal_access_token>" "https://gitlab.example.com/api/v4/projects/1/packages/pool/my-distro/a/my-pkg/1.0.0/example_1.0.0~alpha2_amd64.deb" @@ -92,7 +92,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote file name in the current directory. +This writes the downloaded file using the remote filename in the current directory. ## Route prefix @@ -150,7 +150,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote file name in the current directory. +This writes the downloaded file using the remote filename in the current directory. ## Download a signed distribution Release file @@ -178,7 +178,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote file name in the current directory. +This writes the downloaded file using the remote filename in the current directory. ## Download a release file signature @@ -206,7 +206,7 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote file name in the current directory. +This writes the downloaded file using the remote filename in the current directory. ## Download a binary file's index @@ -236,4 +236,4 @@ curl --header "Private-Token: <personal_access_token>" \ --remote-name ``` -This writes the downloaded file using the remote file name in the current directory. +This writes the downloaded file using the remote filename in the current directory. diff --git a/doc/api/packages/helm.md b/doc/api/packages/helm.md index 8c3b9869368..82b3f5225b0 100644 --- a/doc/api/packages/helm.md +++ b/doc/api/packages/helm.md @@ -63,7 +63,7 @@ GET projects/:id/packages/helm/:channel/charts/:file_name.tgz | ----------- | ------ | -------- | ----------- | | `id` | string | yes | The ID or full path of the project. | | `channel` | string | yes | Helm repository channel. | -| `file_name` | string | yes | Chart file name. | +| `file_name` | string | yes | Chart filename. | ```shell curl --user <username>:<personal_access_token> \ diff --git a/doc/api/pages.md b/doc/api/pages.md index f81a3c3c72b..a115f0b0a0f 100644 --- a/doc/api/pages.md +++ b/doc/api/pages.md @@ -12,7 +12,7 @@ The GitLab Pages feature must be enabled to use these endpoints. Find out more a ## Unpublish pages -Remove pages. The user must have admin privileges. +Remove pages. The user must have the Administrator role. ```plaintext DELETE /projects/:id/pages diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 47a8df3875e..624bdf29e5d 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -12,7 +12,7 @@ The GitLab Pages feature must be enabled to use these endpoints. Find out more a ## List all Pages domains -Get a list of all Pages domains. The user must have admin permissions. +Get a list of all Pages domains. The user must have the administrator role. ```plaintext GET /pages/domains diff --git a/doc/api/personal_access_tokens.md b/doc/api/personal_access_tokens.md index b96ee81f673..9c9551a5103 100644 --- a/doc/api/personal_access_tokens.md +++ b/doc/api/personal_access_tokens.md @@ -95,6 +95,6 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git - `204: No Content` if successfully revoked. - `400 Bad Request` if not revoked successfully. -## Create a personal access token (admin only) +## Create a personal access token (administrator only) See the [Users API documentation](users.md#create-a-personal-access-token) for information on creating a personal access token. diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index 74f96e5374e..625a92f9b89 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -115,7 +115,7 @@ POST /projects/:id/pipeline_schedules | `description` | string | yes | The description of the pipeline schedule. | | `ref` | string | yes | The branch or tag name that is triggered. | | `cron` | string | yes | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. | -| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone`, for example: `Pacific Time (US & Canada)` (default: `UTC`). | +| `cron_timezone` | string | no | The time zone supported by `ActiveSupport::TimeZone`, for example: `Pacific Time (US & Canada)` (default: `UTC`). | | `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated (default: `true`). | ```shell @@ -162,7 +162,7 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id | `description` | string | no | The description of the pipeline schedule. | | `ref` | string | no | The branch or tag name that is triggered. | | `cron` | string | no | The [cron](https://en.wikipedia.org/wiki/Cron) schedule, for example: `0 1 * * *`. | -| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone` (for example `Pacific Time (US & Canada)`), or `TZInfo::Timezone` (for example `America/Los_Angeles`). | +| `cron_timezone` | string | no | The time zone supported by `ActiveSupport::TimeZone` (for example `Pacific Time (US & Canada)`), or `TZInfo::Timezone` (for example `America/Los_Angeles`). | | `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule is initially deactivated. | ```shell diff --git a/doc/api/plan_limits.md b/doc/api/plan_limits.md index 52152dd6e14..8bd87f5a896 100644 --- a/doc/api/plan_limits.md +++ b/doc/api/plan_limits.md @@ -14,7 +14,7 @@ The existing plans depend on the GitLab edition. In the Community Edition, only is available. In the Enterprise Edition, additional plans are available as well. NOTE: -Administrator access is required to use this API. +The Administrator role is required to use this API. ## Get current plan limits diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 2dcef40aacb..a2c2da9065f 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -15,8 +15,8 @@ Get list of a project's variables. GET /projects/:id/variables ``` -| Attribute | Type | required | Description | -|-----------|---------|----------|---------------------| +| Attribute | Type | required | Description | +| --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | ```shell @@ -26,14 +26,20 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a ```json [ { - "key": "TEST_VARIABLE_1", "variable_type": "env_var", - "value": "TEST_1" + "key": "TEST_VARIABLE_1", + "value": "TEST_1", + "protected": false, + "masked": true, + "environment_scope": "*" }, { - "key": "TEST_VARIABLE_2", "variable_type": "env_var", - "value": "TEST_2" + "key": "TEST_VARIABLE_2", + "value": "TEST_2", + "protected": false, + "masked": false, + "environment_scope": "*" } ] ``` @@ -46,11 +52,11 @@ Get the details of a project's specific variable. GET /projects/:id/variables/:key ``` -| Attribute | Type | required | Description | -|-----------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `key` | string | yes | The `key` of a variable | -| `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | +| Attribute | Type | required | Description | +| --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The `key` of a variable | +| `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/TEST_VARIABLE_1" @@ -62,7 +68,8 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a "variable_type": "env_var", "value": "TEST_1", "protected": false, - "masked": true + "masked": true, + "environment_scope": "*" } ``` @@ -74,15 +81,15 @@ Create a new variable. POST /projects/:id/variables ``` -| Attribute | Type | required | Description | -|---------------------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | -| `value` | string | yes | The `value` of a variable | -| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | -| `protected` | boolean | no | Whether the variable is protected. Default: `false` | -| `masked` | boolean | no | Whether the variable is masked. Default: `false` | -| `environment_scope` | string | no | The `environment_scope` of the variable. Default: `*` | +| Attribute | Type | required | Description | +| ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | +| `value` | string | yes | The `value` of a variable | +| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | +| `protected` | boolean | no | Whether the variable is protected. Default: `false` | +| `masked` | boolean | no | Whether the variable is masked. Default: `false` | +| `environment_scope` | string | no | The `environment_scope` of the variable. Default: `*` | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -91,10 +98,10 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ ```json { + "variable_type": "env_var", "key": "NEW_VARIABLE", "value": "new value", "protected": false, - "variable_type": "env_var", "masked": false, "environment_scope": "*" } @@ -108,16 +115,16 @@ Update a project's variable. PUT /projects/:id/variables/:key ``` -| Attribute | Type | required | Description | -|---------------------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `key` | string | yes | The `key` of a variable | -| `value` | string | yes | The `value` of a variable | -| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | -| `protected` | boolean | no | Whether the variable is protected | -| `masked` | boolean | no | Whether the variable is masked | -| `environment_scope` | string | no | The `environment_scope` of the variable | -| `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | +| Attribute | Type | required | Description | +| ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The `key` of a variable | +| `value` | string | yes | The `value` of a variable | +| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | +| `protected` | boolean | no | Whether the variable is protected | +| `masked` | boolean | no | Whether the variable is masked | +| `environment_scope` | string | no | The `environment_scope` of the variable | +| `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ @@ -126,9 +133,9 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ ```json { + "variable_type": "env_var", "key": "NEW_VARIABLE", "value": "updated value", - "variable_type": "env_var", "protected": true, "masked": false, "environment_scope": "*" @@ -143,11 +150,11 @@ Remove a project's variable. DELETE /projects/:id/variables/:key ``` -| Attribute | Type | required | Description | -|-----------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | -| `key` | string | yes | The `key` of a variable | -| `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | +| Attribute | Type | required | Description | +| --------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID of a project or [URL-encoded NAMESPACE/PROJECT_NAME of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The `key` of a variable | +| `filter` | hash | no | Available filters: `[environment_scope]`. See the [`filter` parameter details](#the-filter-parameter). | ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1" diff --git a/doc/api/project_relations_export.md b/doc/api/project_relations_export.md new file mode 100644 index 00000000000..2016dcbd141 --- /dev/null +++ b/doc/api/project_relations_export.md @@ -0,0 +1,111 @@ +--- +stage: Manage +group: Import +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 +--- + +# Project Relations Export API **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70330) in GitLab 14.4 behind the `bulk_import` [feature flag](../administration/feature_flags.md), disabled by default. + +FLAG: +On GitLab.com, this feature is available. +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to +[disable the `bulk_import` flag](../administration/feature_flags.md). +The feature is not ready for production use. It is still in experimental stage and might change in the future. + +With the Project Relations Export API, you can partially export project structure. This API is +similar to [project export](project_import_export.md), +but it exports each top-level relation (for example, milestones/boards/labels) as a separate file +instead of one archive. The project relations export API is primarily used in +[group migration](../user/group/import/index.md#enable-or-disable-gitlab-group-migration) +to support group project import. + +## Schedule new export + +Start a new project relations export: + +```plaintext +POST /projects/:id/export_relations +``` + +| Attribute | Type | Required | Description | +| --------- | -------------- | -------- | ---------------------------------------- | +| `id` | integer/string | yes | ID of the project owned by the authenticated user. | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/export_relations" +``` + +```json +{ + "message": "202 Accepted" +} +``` + +## Export status + +View the status of the relations export: + +```plaintext +GET /projects/:id/export_relations/status +``` + +| Attribute | Type | Required | Description | +| --------- | -------------- | -------- | ---------------------------------------- | +| `id` | integer/string | yes | ID of the project owned by the authenticated user. | + +```shell +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/projects/1/export_relations/status" +``` + +The status can be one of the following: + +- `0`: `started` +- `1`: `finished` +- `-1`: `failed` + +- `0` - `started` +- `1` - `finished` +- `-1` - `failed` + +```json +[ + { + "relation": "project_badges", + "status": 1, + "error": null, + "updated_at": "2021-05-04T11:25:20.423Z" + }, + { + "relation": "boards", + "status": 1, + "error": null, + "updated_at": "2021-05-04T11:25:20.085Z" + } +] +``` + +## Export download + +Download the finished relations export: + +```plaintext +GET /projects/:id/export_relations/download +``` + +| Attribute | Type | Required | Description | +| --------------- | -------------- | -------- | ---------------------------------------- | +| `id` | integer/string | yes | ID of the project owned by the authenticated user. | +| `relation` | string | yes | Name of the project top-level relation to download. | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \ + --remote-name "https://gitlab.example.com/api/v4/projects/1/export_relations/download?relation=labels" +``` + +```shell +ls labels.ndjson.gz +labels.ndjson.gz +``` diff --git a/doc/api/project_repository_storage_moves.md b/doc/api/project_repository_storage_moves.md index ebb15e1c1d6..b779a0046c6 100644 --- a/doc/api/project_repository_storage_moves.md +++ b/doc/api/project_repository_storage_moves.md @@ -10,7 +10,7 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31285) in GitLab 13.0. Project repositories including wiki and design repositories can be moved between storages. This can be useful when -[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster), +[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrating-to-gitaly-cluster), for example. As project repository storage moves are processed, they transition through different states. Values diff --git a/doc/api/project_statistics.md b/doc/api/project_statistics.md index a16bcc513f9..c69e41a423e 100644 --- a/doc/api/project_statistics.md +++ b/doc/api/project_statistics.md @@ -8,12 +8,12 @@ type: reference, api # Project statistics API **(FREE)** Every API call to [project](../user/project/index.md) statistics must be authenticated. +Retrieving these statistics requires write access to the repository. -## Get the statistics of the last 30 days +This API retrieves the number of times the project is either cloned or pulled +with the HTTP method. SSH fetches are not included. -Retrieving the statistics requires write access to the repository. -Currently only HTTP fetches statistics are returned. -Fetches statistics includes both clones and pulls count and are HTTP only, SSH fetches are not included. +## Get the statistics of the last 30 days ```plaintext GET /projects/:id/statistics diff --git a/doc/api/projects.md b/doc/api/projects.md index 29e3cdf6cbf..024362f3246 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -53,10 +53,10 @@ GET /projects | `last_activity_before` | datetime | **{dotted-circle}** No | Limit results to projects with last_activity before specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`) | | `membership` | boolean | **{dotted-circle}** No | Limit by projects that the current user is a member of. | | `min_access_level` | integer | **{dotted-circle}** No | Limit by current user minimal [access level](members.md#valid-access-levels). | -| `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `last_activity_at`, or `similarity` fields. `repository_size`, `storage_size`, `packages_size` or `wiki_size` fields are only allowed for admins. `similarity` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332890) in GitLab 14.1) is only available when searching and is limited to projects that the current user is a member of. Default is `created_at`. | +| `order_by` | string | **{dotted-circle}** No | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `last_activity_at`, or `similarity` fields. `repository_size`, `storage_size`, `packages_size` or `wiki_size` fields are only allowed for administrators. `similarity` ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332890) in GitLab 14.1) is only available when searching and is limited to projects that the current user is a member of. Default is `created_at`. | | `owned` | boolean | **{dotted-circle}** No | Limit by projects explicitly owned by the current user. | | `repository_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in GitLab 11.2). | -| `repository_storage` | string | **{dotted-circle}** No | Limit results to projects stored on `repository_storage`. _(admins only)_ | +| `repository_storage` | string | **{dotted-circle}** No | Limit results to projects stored on `repository_storage`. _(administrators only)_ | | `search_namespaces` | boolean | **{dotted-circle}** No | Include ancestor namespaces when matching search criteria. Default is `false`. | | `search` | string | **{dotted-circle}** No | Return list of projects matching the search criteria. | | `simple` | boolean | **{dotted-circle}** No | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | @@ -66,7 +66,7 @@ GET /projects | `topic` | string | **{dotted-circle}** No | Comma-separated topic names. Limit results to projects that match all of given topics. See `topics` attribute. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | | `wiki_checksum_failed` **(PREMIUM)** | boolean | **{dotted-circle}** No | Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6137) in GitLab 11.2). | -| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrator only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | | `with_programming_language` | string | **{dotted-circle}** No | Limit by projects which use the given programming language. | @@ -386,7 +386,7 @@ GET /users/:user_id/projects | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | -| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrator only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | | `with_programming_language` | string | **{dotted-circle}** No | Limit by projects which use the given programming language. | @@ -621,7 +621,7 @@ GET /users/:user_id/starred_projects | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `user_id` | string | **{check-circle}** Yes | The ID or username of the user. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | -| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrator only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | @@ -840,7 +840,7 @@ GET /projects/:id | `id` | integer or string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). | | `license` | boolean | **{dotted-circle}** No | Include project license data. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | -| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrators only)_ | ```json { @@ -1218,7 +1218,7 @@ POST /projects | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project members. | | `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | -| `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(admins only)_ | +| `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(administrator only)_ | | `request_access_enabled` | boolean | **{dotted-circle}** No | Allow users to request member access. | | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | @@ -1237,7 +1237,7 @@ POST /projects ## Create project for user -Creates a new project owned by the specified user. Available only for admins. +Creates a new project owned by the specified user. Available only for administrators. If your HTTP repository isn't publicly accessible, add authentication information to the URL `https://username:password@gitlab.company.com/group/project.git`, @@ -1295,7 +1295,7 @@ POST /projects/user/:user_id | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project-members. | | `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | -| `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(admins only)_ | +| `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(administrators only)_ | | `request_access_enabled` | boolean | **{dotted-circle}** No | Allow users to request member access. | | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `shared_runners_enabled` | boolean | **{dotted-circle}** No | Enable shared runners for this project. | @@ -1360,7 +1360,7 @@ PUT /projects/:id | `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. | | `mirror_overwrites_diverged_branches` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirror overwrites diverged branches. | | `mirror_trigger_builds` **(PREMIUM)** | boolean | **{dotted-circle}** No | Pull mirroring triggers builds. | -| `mirror_user_id` **(PREMIUM)** | integer | **{dotted-circle}** No | User responsible for all the activity surrounding a pull mirror event. _(admins only)_ | +| `mirror_user_id` **(PREMIUM)** | integer | **{dotted-circle}** No | User responsible for all the activity surrounding a pull mirror event. _(administrators only)_ | | `mirror` **(PREMIUM)** | boolean | **{dotted-circle}** No | Enables pull mirroring in a project. | | `name` | string | **{dotted-circle}** No | The name of the project. | | `operations_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | @@ -1375,7 +1375,7 @@ PUT /projects/:id | `public_builds` | boolean | **{dotted-circle}** No | If `true`, jobs can be viewed by non-project members. | | `remove_source_branch_after_merge` | boolean | **{dotted-circle}** No | Enable `Delete source branch` option by default for all new merge requests. | | `repository_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. | -| `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(admins only)_ | +| `repository_storage` | string | **{dotted-circle}** No | Which storage shard the repository is on. _(administrators only)_ | | `request_access_enabled` | boolean | **{dotted-circle}** No | Allow users to request member access. | | `resolve_outdated_diff_discussions` | boolean | **{dotted-circle}** No | Automatically resolve merge request diffs discussions on lines changed with a push. | | `service_desk_enabled` | boolean | **{dotted-circle}** No | Enable or disable Service Desk feature. | @@ -1442,7 +1442,7 @@ GET /projects/:id/forks | `starred` | boolean | **{dotted-circle}** No | Limit by projects starred by the current user. | | `statistics` | boolean | **{dotted-circle}** No | Include project statistics. Only available to Reporter or higher level role members. | | `visibility` | string | **{dotted-circle}** No | Limit by visibility `public`, `internal`, or `private`. | -| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(admins only)_ | +| `with_custom_attributes` | boolean | **{dotted-circle}** No | Include [custom attributes](custom_attributes.md) in response. _(administrators only)_ | | `with_issues_enabled` | boolean | **{dotted-circle}** No | Limit by enabled issues feature. | | `with_merge_requests_enabled` | boolean | **{dotted-circle}** No | Limit by enabled merge requests feature. | @@ -2047,7 +2047,7 @@ This endpoint: merge requests). - From [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/220382) on [Premium or higher](https://about.gitlab.com/pricing/) tiers, group - admins can [configure](../user/group/index.md#enable-delayed-project-removal) + administrators can [configure](../user/group/index.md#enable-delayed-project-removal) projects within a group to be deleted after a delayed period. When enabled, actual deletion happens after the number of days specified in the [default deletion delay](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-delay). @@ -2373,7 +2373,7 @@ is returned. ## Fork relationship Allows modification of the forked relationship between existing projects. -Available only for project owners and admins. +Available only for project owners and administrators. ### Create a forked from/to relation between existing projects @@ -2678,13 +2678,21 @@ Read more in the [Project members](members.md) documentation. > - Introduced in GitLab 11. > - Moved to GitLab Premium in 13.9. -Configure pull mirroring while [creating a new project](#create-project) or [updating an existing project](#edit-project) using the API if the remote repository is publicly accessible or via `username/password` authentication. In case your HTTP repository is not publicly accessible, you can add the authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git`, where password is a [personal access token](../user/profile/personal_access_tokens.md) with the API scope enabled. - -The relevant API parameters to update are: - -- `import_url`: URL of remote repository being mirrored (with `username:password` if needed). -- `mirror`: Enables pull mirroring on project when set to `true`. -- `only_mirror_protected_branches`: Set to `true` for protected branches. +Configure pull mirroring while [creating a new project](#create-project) +or [updating an existing project](#edit-project) using the API +if the remote repository is publicly accessible +or via `username:token` authentication. +In case your HTTP repository is not publicly accessible, +you can add the authentication information to the URL: +`https://username:token@gitlab.company.com/group/project.git`, +where `token` is a [personal access token](../user/profile/personal_access_tokens.md) +with the API scope enabled. + +| Attribute | Type | Required | Description | +|--------------|---------|------------------------|-------------| +| `import_url` | string | **{check-circle}** Yes | URL of remote repository being mirrored (with `user:token` if needed). | +| `mirror` | boolean | **{check-circle}** Yes | Enables pull mirroring on project when set to `true`. | +| `only_mirror_protected_branches`| boolean | **{dotted-circle}** No | Limits mirroring to only protected branches when set to `true`. | ## Start the pull mirroring process for a Project **(PREMIUM)** diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 72627783947..ded47b24c12 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -729,3 +729,5 @@ Example response: A release with a `released_at` attribute set to a future date is labeled as an **Upcoming Release** [in the UI](../../user/project/releases/index.md#upcoming-releases). + +Additionally, if a [release is requested from the API](#list-releases), for each release with a `release_at` attribute set to a future date, an additional attribute `upcoming_release` (set to true) will be returned as part of the response. diff --git a/doc/api/remote_mirrors.md b/doc/api/remote_mirrors.md index 799763a7da3..8b584285033 100644 --- a/doc/api/remote_mirrors.md +++ b/doc/api/remote_mirrors.md @@ -7,7 +7,7 @@ type: reference, api # Project remote mirrors API **(FREE)** -[Push mirrors](../user/project/repository/repository_mirroring.md#push-to-a-remote-repository) +[Push mirrors](../user/project/repository/mirror/push.md) defined on a project's repository settings are called "remote mirrors", and the state of these mirrors can be queried and modified via the remote mirror API outlined below. @@ -51,11 +51,15 @@ NOTE: For security reasons, the `url` attribute is always scrubbed of username and password information. -## Create a remote mirror +## Create a pull mirror + +Learn how to [configure a pull mirror](projects.md#configure-pull-mirroring-for-a-project) using the Projects API. + +## Create a push mirror > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24189) in GitLab 12.9. -Create a remote mirror for a project. The mirror is disabled by default. You can enable it by including the optional parameter `enabled` when creating it: +Push mirroring is disabled by default. You can enable it by including the optional parameter `enabled` when creating it: ```plaintext POST /projects/:id/remote_mirrors @@ -63,7 +67,7 @@ POST /projects/:id/remote_mirrors | Attribute | Type | Required | Description | | :---------- | :----- | :--------- | :------------ | -| `url` | String | yes | The URL of the remote repository to be mirrored. | +| `url` | String | yes | The target URL to which the repository is mirrored. | | `enabled` | Boolean | no | Determines if the mirror is enabled. | | `only_protected_branches` | Boolean | no | Determines if only protected branches are mirrored. | | `keep_divergent_refs` | Boolean | no | Determines if divergent refs are skipped. | diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 1c9136d22ac..e93ffbc5e72 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -14,6 +14,12 @@ be accessed without authentication if the repository is publicly accessible. This command provides essentially the same functionality as the `git ls-tree` command. For more information, see the section _Tree Objects_ in the [Git internals documentation](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects/#_tree_objects). +WARNING: +This endpoint is changing to keyset-based pagination. Iterating pages of results +with a number (`?page=2`) [is deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67509). +Support for iterating with a number will become unsupported in GitLab 15.0. Use +the new [keyset pagination system](index.md#keyset-based-pagination) instead. + ```plaintext GET /projects/:id/repository/tree ``` @@ -27,6 +33,8 @@ Supported attributes: | `ref` | string | no | The name of a repository branch or tag or if not given the default branch. | | `recursive` | boolean | no | Boolean value used to get a recursive tree (false by default). | | `per_page` | integer | no | Number of results to show per page. If not specified, defaults to `20`. [Learn more on pagination](index.md#pagination). | +| `pagination` | string | no | If set to `keyset`, use the new keyset pagination method. | +| `page_token` | string | no | The tree record ID at which to fetch the next page. Used only with keyset pagination. | ```json [ @@ -118,6 +126,7 @@ Supported attributes: ## Get file archive > Support for [including Git LFS blobs](../topics/git/lfs/index.md#lfs-objects-in-project-archives) was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15079) in GitLab 13.5. +> Support for downloading a subfolder was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28827) in GitLab 14.4. Get an archive of the repository. This endpoint can be accessed without authentication if the repository is publicly accessible. @@ -139,11 +148,12 @@ Supported attributes: |:------------|:---------------|:---------|:----------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. | +| `path` | string | no | The subpath of the repository to download. This defaults to the whole repository (empty string). | Example request: ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>" +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>&path=<path>" ``` ## Compare branches, tags or commits @@ -640,7 +650,7 @@ In an entry, the following variables are available (here `foo.bar` means that - `author.reference`: a reference to the commit author (for example, `@alice`). - `author.contributor`: a boolean set to `true` when the author is not a project member, otherwise `false`. -- `author.credit`: a boolean set to `true` when `author.contributor` is `true` or +- `author.credit`: a boolean set to `true` when `author.contributor` is `true` or when `include_groups` is configured, and the author is a member of one of the groups. - `merge_request.reference`: a reference to the merge request that first diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index 1e33aadbc1b..4fb1a94e294 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -7,9 +7,11 @@ type: reference, api # Repository files API **(FREE)** -**CRUD for repository files** +You can fetch, create, update, and delete files in your repository with this API. +You can also [configure rate limits](../user/admin_area/settings/files_api_rate_limits.md) +for this API. -**Create, read, update, and delete repository files using this API** +## Available scopes for personal access tokens The different scopes available using [personal access tokens](../user/profile/personal_access_tokens.md) are depicted in the following table. @@ -19,8 +21,6 @@ in the following table. | `read_repository` | Allows read-access to the repository files. | | `api` | Allows read-write access to the repository files. | -> `read_repository` scope was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23534) in GitLab 11.6. - ## Get file from repository Allows you to receive information about file in repository like name, size, diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md new file mode 100644 index 00000000000..ce4fa33d7f2 --- /dev/null +++ b/doc/api/resource_groups.md @@ -0,0 +1,70 @@ +--- +stage: Release +group: Release +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 +type: concepts, howto +--- + +# Resource Groups API + +You can read more about [controling the job concurrency with resource groups](../ci/resource_groups/index.md). + +## Get a specific resource group + +```plaintext +GET /projects/:id/resource_groups/:key +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The key of the resource group | + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/resource_groups/production" +``` + +Example of response + +```json +{ + "id": 3, + "key": "production", + "process_mode": "unordered", + "created_at": "2021-09-01T08:04:59.650Z", + "updated_at": "2021-09-01T08:04:59.650Z" +} +``` + +## Edit an existing resource group + +Updates an existing resource group's properties. + +It returns `200` if the resource group was successfully updated. In case of an error, a status code `400` is returned. + +```plaintext +PUT /projects/:id/resource_groups/:key +``` + +| Attribute | Type | Required | Description | +| --------------- | ------- | --------------------------------- | ------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The key of the resource group | +| `process_mode` | string | no | The process mode of the resource group. One of `unordered`, `oldest_first` or `newest_first`. Read [process modes](../ci/resource_groups/index.md#process-modes) for more information. | + +```shell +curl --request PUT --data "process_mode=oldest_first" \ + --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/resource_groups/production" +``` + +Example response: + +```json +{ + "id": 3, + "key": "production", + "process_mode": "oldest_first", + "created_at": "2021-09-01T08:04:59.650Z", + "updated_at": "2021-09-01T08:13:38.679Z" +} +``` diff --git a/doc/api/runners.md b/doc/api/runners.md index bfdf2d49100..5e84080ecb5 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -15,7 +15,7 @@ There are two tokens to take into account when connecting a runner with GitLab. | Token | Description | | ----- | ----------- | | Registration token | Token used to [register the runner](https://docs.gitlab.com/runner/register/). It can be [obtained through GitLab](../ci/runners/index.md). | -| Authentication token | Token used to authenticate the runner with the GitLab instance. It is obtained either automatically when [registering a runner](https://docs.gitlab.com/runner/register/), or manually when [registering the runner via the Runner API](#register-a-new-runner). | +| Authentication token | Token used to authenticate the runner with the GitLab instance. It is obtained automatically when you [register a runner](https://docs.gitlab.com/runner/register/) or by the Runner API when you manually [register a runner](#register-a-new-runner) or [reset the authentication token](#reset-runners-authentication-token). | Here's an example of how the two tokens are used in runner registration: @@ -86,7 +86,7 @@ Example response: ## List all runners **(FREE SELF)** Get a list of all runners in the GitLab instance (specific and shared). Access -is restricted to users with `admin` privileges. +is restricted to users with the administrator role. ```plaintext GET /runners/all @@ -720,3 +720,28 @@ POST /groups/:id/runners/reset_registration_token curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token" ``` + +## Reset runner's authentication token + +Resets the runner's authentication token. + +```plaintext +POST /runners/:id/reset_authentication_token +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a runner | + +```shell +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ + "https://gitlab.example.com/api/v4/runners/1/reset_authentication_token" +``` + +Example response: + +```json +{ + "token": "6337ff461c94fd3fa32ba3b1ff4125" +} +``` diff --git a/doc/api/search.md b/doc/api/search.md index d3a2f9c41b6..d3f0cba9234 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -1161,7 +1161,7 @@ Blobs searches are performed on both filenames and contents. Search results: times in the content. ```shell -curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation&ref=feature" +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=keyword%20filename:*.py ``` Example response: @@ -1175,7 +1175,7 @@ Example response: "path": "README.md", "filename": "README.md", "id": null, - "ref": "feature", + "ref": "master", "startline": 46, "project_id": 6 } diff --git a/doc/api/services.md b/doc/api/services.md index cf6c5ec511b..7587e53c9db 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -1,1471 +1,9 @@ --- -stage: Ecosystem -group: Integrations -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 +redirect_to: 'integrations.md' +remove_date: '2021-11-09' --- -# Services API **(FREE)** +This file was moved to [another location](integrations.md). -NOTE: -This API requires an access token with the [Maintainer or Owner role](../user/permissions.md). - -## List all active services - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21330) in GitLab 12.7. - -Get a list of all active project services. - -```plaintext -GET /projects/:id/services -``` - -Example response: - -```json -[ - { - "id": 75, - "title": "Jenkins CI", - "slug": "jenkins", - "created_at": "2019-11-20T11:20:25.297Z", - "updated_at": "2019-11-20T12:24:37.498Z", - "active": true, - "commit_events": true, - "push_events": true, - "issues_events": true, - "confidential_issues_events": true, - "merge_requests_events": true, - "tag_push_events": false, - "note_events": true, - "confidential_note_events": true, - "pipeline_events": true, - "wiki_page_events": true, - "job_events": true, - "comment_on_event_enabled": true - }, - { - "id": 76, - "title": "Alerts endpoint", - "slug": "alerts", - "created_at": "2019-11-20T11:20:25.297Z", - "updated_at": "2019-11-20T12:24:37.498Z", - "active": true, - "commit_events": true, - "push_events": true, - "issues_events": true, - "confidential_issues_events": true, - "merge_requests_events": true, - "tag_push_events": true, - "note_events": true, - "confidential_note_events": true, - "pipeline_events": true, - "wiki_page_events": true, - "job_events": true, - "comment_on_event_enabled": true - } -] -``` - -## Asana - -Add commit messages as comments to Asana tasks. - -See also the [Asana service documentation](../user/project/integrations/asana.md). - -### Create/Edit Asana service - -Set Asana service for a project. - -```plaintext -PUT /projects/:id/services/asana -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `api_key` | string | true | User API token. User must have access to task. All comments are attributed to this user. | -| `restrict_to_branch` | string | false | Comma-separated list of branches to be are automatically inspected. Leave blank to include all branches. | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Asana service - -Delete Asana service for a project. - -```plaintext -DELETE /projects/:id/services/asana -``` - -### Get Asana service settings - -Get Asana service settings for a project. - -```plaintext -GET /projects/:id/services/asana -``` - -## Assembla - -Project Management Software (Source Commits Endpoint) - -### Create/Edit Assembla service - -Set Assembla service for a project. - -```plaintext -PUT /projects/:id/services/assembla -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | true | The authentication token -| `subdomain` | string | false | The subdomain setting | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Assembla service - -Delete Assembla service for a project. - -```plaintext -DELETE /projects/:id/services/assembla -``` - -### Get Assembla service settings - -Get Assembla service settings for a project. - -```plaintext -GET /projects/:id/services/assembla -``` - -## Atlassian Bamboo CI - -A continuous integration and build server - -### Create/Edit Atlassian Bamboo CI service - -Set Atlassian Bamboo CI service for a project. - -> You must set up automatic revision labeling and a repository trigger in Bamboo. - -```plaintext -PUT /projects/:id/services/bamboo -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `bamboo_url` | string | true | Bamboo root URL. For example, `https://bamboo.example.com`. | -| `build_key` | string | true | Bamboo build plan key like KEY | -| `username` | string | true | A user with API access, if applicable | -| `password` | string | true | Password of the user | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Atlassian Bamboo CI service - -Delete Atlassian Bamboo CI service for a project. - -```plaintext -DELETE /projects/:id/services/bamboo -``` - -### Get Atlassian Bamboo CI service settings - -Get Atlassian Bamboo CI service settings for a project. - -```plaintext -GET /projects/:id/services/bamboo -``` - -## Bugzilla - -Bugzilla Issue Tracker - -### Create/Edit Bugzilla service - -Set Bugzilla service for a project. - -```plaintext -PUT /projects/:id/services/bugzilla -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `new_issue_url` | string | true | New Issue URL | -| `issues_url` | string | true | Issue URL | -| `project_url` | string | true | Project URL | -| `description` | string | false | Description | -| `title` | string | false | Title | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Bugzilla Service - -Delete Bugzilla service for a project. - -```plaintext -DELETE /projects/:id/services/bugzilla -``` - -### Get Bugzilla Service Settings - -Get Bugzilla service settings for a project. - -```plaintext -GET /projects/:id/services/bugzilla -``` - -## Buildkite - -Continuous integration and deployments - -### Create/Edit Buildkite service - -Set Buildkite service for a project. - -```plaintext -PUT /projects/:id/services/buildkite -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | true | Buildkite project GitLab token | -| `project_url` | string | true | Pipeline URL. For example, `https://buildkite.com/example/pipeline` | -| `enable_ssl_verification` | boolean | false | DEPRECATED: This parameter has no effect since SSL verification is always enabled | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Buildkite service - -Delete Buildkite service for a project. - -```plaintext -DELETE /projects/:id/services/buildkite -``` - -### Get Buildkite service settings - -Get Buildkite service settings for a project. - -```plaintext -GET /projects/:id/services/buildkite -``` - -## Campfire - -Send notifications about push events to Campfire chat rooms. -[New users can no longer sign up for Campfire](https://basecamp.com/retired/campfire). - -### Create/Edit Campfire service - -Set Campfire service for a project. - -```plaintext -PUT /projects/:id/services/campfire -``` - -Parameters: - -| Parameter | Type | Required | Description | -|---------------|---------|----------|---------------------------------------------------------------------------------------------| -| `token` | string | true | Campfire API token. To find it, log into Campfire and select **My info**. | -| `subdomain` | string | false | Campfire subdomain. Text between `https://` and `.campfirenow.com` when you're logged in. | -| `room` | string | false | Campfire room. The last part of the URL when you're in a room. | -| `push_events` | boolean | false | Enable notifications for push events. | - -### Delete Campfire service - -Delete Campfire service for a project. - -```plaintext -DELETE /projects/:id/services/campfire -``` - -### Get Campfire service settings - -Get Campfire service settings for a project. - -```plaintext -GET /projects/:id/services/campfire -``` - -## Unify Circuit - -Unify Circuit RTC and collaboration tool. - -### Create/Edit Unify Circuit service - -Set Unify Circuit service for a project. - -```plaintext -PUT /projects/:id/services/unify-circuit -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `webhook` | string | true | The Unify Circuit webhook. For example, `https://circuit.com/rest/v2/webhooks/incoming/...`. | -| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | -| `push_events` | boolean | false | Enable notifications for push events | -| `issues_events` | boolean | false | Enable notifications for issue events | -| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events | -| `tag_push_events` | boolean | false | Enable notifications for tag push events | -| `note_events` | boolean | false | Enable notifications for note events | -| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | -| `pipeline_events` | boolean | false | Enable notifications for pipeline events | -| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | - -### Delete Unify Circuit service - -Delete Unify Circuit service for a project. - -```plaintext -DELETE /projects/:id/services/unify-circuit -``` - -### Get Unify Circuit service settings - -Get Unify Circuit service settings for a project. - -```plaintext -GET /projects/:id/services/unify-circuit -``` - -## Webex Teams - -Webex Teams collaboration tool. - -### Create/Edit Webex Teams service - -Set Webex Teams service for a project. - -```plaintext -PUT /projects/:id/services/webex-teams -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `webhook` | string | true | The Webex Teams webhook. For example, `https://api.ciscospark.com/v1/webhooks/incoming/...`. | -| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | -| `push_events` | boolean | false | Enable notifications for push events | -| `issues_events` | boolean | false | Enable notifications for issue events | -| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events | -| `tag_push_events` | boolean | false | Enable notifications for tag push events | -| `note_events` | boolean | false | Enable notifications for note events | -| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | -| `pipeline_events` | boolean | false | Enable notifications for pipeline events | -| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | - -### Delete Webex Teams service - -Delete Webex Teams service for a project. - -```plaintext -DELETE /projects/:id/services/webex-teams -``` - -### Get Webex Teams service settings - -Get Webex Teams service settings for a project. - -```plaintext -GET /projects/:id/services/webex-teams -``` - -## Custom Issue Tracker - -Custom issue tracker - -### Create/Edit Custom Issue Tracker service - -Set Custom Issue Tracker service for a project. - -```plaintext -PUT /projects/:id/services/custom-issue-tracker -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `new_issue_url` | string | true | New Issue URL | -| `issues_url` | string | true | Issue URL | -| `project_url` | string | true | Project URL | -| `description` | string | false | Description | -| `title` | string | false | Title | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Custom Issue Tracker service - -Delete Custom Issue Tracker service for a project. - -```plaintext -DELETE /projects/:id/services/custom-issue-tracker -``` - -### Get Custom Issue Tracker service settings - -Get Custom Issue Tracker service settings for a project. - -```plaintext -GET /projects/:id/services/custom-issue-tracker -``` - -## Drone CI - -Drone is a Continuous Integration platform built on Docker, written in Go - -### Create/Edit Drone CI service - -Set Drone CI service for a project. - -```plaintext -PUT /projects/:id/services/drone-ci -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | true | Drone CI project specific token | -| `drone_url` | string | true | `http://drone.example.com` | -| `enable_ssl_verification` | boolean | false | Enable SSL verification | -| `push_events` | boolean | false | Enable notifications for push events | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events | -| `tag_push_events` | boolean | false | Enable notifications for tag push events | - -### Delete Drone CI service - -Delete Drone CI service for a project. - -```plaintext -DELETE /projects/:id/services/drone-ci -``` - -### Get Drone CI service settings - -Get Drone CI service settings for a project. - -```plaintext -GET /projects/:id/services/drone-ci -``` - -## Emails on push - -Email the commits and diff of each push to a list of recipients. - -### Create/Edit Emails on push service - -Set Emails on push service for a project. - -```plaintext -PUT /projects/:id/services/emails-on-push -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `recipients` | string | true | Emails separated by whitespace | -| `disable_diffs` | boolean | false | Disable code diffs | -| `send_from_committer_email` | boolean | false | Send from committer | -| `push_events` | boolean | false | Enable notifications for push events | -| `tag_push_events` | boolean | false | Enable notifications for tag push events | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". Notifications are always fired for tag pushes. The default value is "all" | - -### Delete Emails on push service - -Delete Emails on push service for a project. - -```plaintext -DELETE /projects/:id/services/emails-on-push -``` - -### Get Emails on push service settings - -Get Emails on push service settings for a project. - -```plaintext -GET /projects/:id/services/emails-on-push -``` - -## Confluence service - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220934) in GitLab 13.2. - -Replaces the link to the internal wiki with a link to a Confluence Cloud Workspace. - -### Create/Edit Confluence service - -Set Confluence service for a project. - -```plaintext -PUT /projects/:id/services/confluence -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `confluence_url` | string | true | The URL of the Confluence Cloud Workspace hosted on atlassian.net. | - -### Delete Confluence service - -Delete Confluence service for a project. - -```plaintext -DELETE /projects/:id/services/confluence -``` - -### Get Confluence service settings - -Get Confluence service settings for a project. - -```plaintext -GET /projects/:id/services/confluence -``` - -## External wiki - -Replaces the link to the internal wiki with a link to an external wiki. - -### Create/Edit External wiki service - -Set External wiki service for a project. - -```plaintext -PUT /projects/:id/services/external-wiki -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `external_wiki_url` | string | true | The URL of the external wiki | - -### Delete External wiki service - -Delete External wiki service for a project. - -```plaintext -DELETE /projects/:id/services/external-wiki -``` - -### Get External wiki service settings - -Get External wiki service settings for a project. - -```plaintext -GET /projects/:id/services/external-wiki -``` - -## Flowdock - -Flowdock is a ChatOps application for collaboration in software engineering -companies. You can send notifications from GitLab events to Flowdock flows. -For integration instructions, see the [Flowdock documentation](https://www.flowdock.com/help/gitlab). - -### Create/Edit Flowdock service - -Set Flowdock service for a project. - -```plaintext -PUT /projects/:id/services/flowdock -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | true | Flowdock Git source token | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Flowdock service - -Delete Flowdock service for a project. - -```plaintext -DELETE /projects/:id/services/flowdock -``` - -### Get Flowdock service settings - -Get Flowdock service settings for a project. - -```plaintext -GET /projects/:id/services/flowdock -``` - -## GitHub **(PREMIUM)** - -Code collaboration software. - -### Create/Edit GitHub service - -Set GitHub service for a project. - -```plaintext -PUT /projects/:id/services/github -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | true | GitHub API token with `repo:status` OAuth scope | -| `repository_url` | string | true | GitHub repository URL | -| `static_context` | boolean | false | Append instance name instead of branch to [status check name](../user/project/integrations/github.md#static--dynamic-status-check-names) | - -### Delete GitHub service - -Delete GitHub service for a project. - -```plaintext -DELETE /projects/:id/services/github -``` - -### Get GitHub service settings - -Get GitHub service settings for a project. - -```plaintext -GET /projects/:id/services/github -``` - -## Hangouts Chat - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/20290) in GitLab 11.2. - -Google Workspace team collaboration tool. - -### Create/Edit Hangouts Chat service - -Set Hangouts Chat service for a project. - -```plaintext -PUT /projects/:id/services/hangouts-chat -``` - -NOTE: -Specific event parameters (for example, `push_events` flag) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4. - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `webhook` | string | true | The Hangouts Chat webhook. For example, `https://chat.googleapis.com/v1/spaces...`. | -| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | -| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | -| `push_events` | boolean | false | Enable notifications for push events | -| `issues_events` | boolean | false | Enable notifications for issue events | -| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events | -| `tag_push_events` | boolean | false | Enable notifications for tag push events | -| `note_events` | boolean | false | Enable notifications for note events | -| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | -| `pipeline_events` | boolean | false | Enable notifications for pipeline events | -| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | - -### Delete Hangouts Chat service - -Delete Hangouts Chat service for a project. - -```plaintext -DELETE /projects/:id/services/hangouts-chat -``` - -### Get Hangouts Chat service settings - -Get Hangouts Chat service settings for a project. - -```plaintext -GET /projects/:id/services/hangouts-chat -``` - -## irker (IRC gateway) - -Send IRC messages, on update, to a list of recipients through an irker gateway. - -For more information, see the [irker integration documentation](../user/project/integrations/irker.md). - -### Create/Edit irker (IRC gateway) service - -Set irker (IRC gateway) service for a project. - -```plaintext -PUT /projects/:id/services/irker -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `recipients` | string | true | Recipients/channels separated by whitespaces | -| `default_irc_uri` | string | false | `irc://irc.network.net:6697/` | -| `server_host` | string | false | localhost | -| `server_port` | integer | false | 6659 | -| `colorize_messages` | boolean | false | Colorize messages | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete irker (IRC gateway) service - -Delete irker (IRC gateway) service for a project. - -```plaintext -DELETE /projects/:id/services/irker -``` - -### Get irker (IRC gateway) service settings - -Get irker (IRC gateway) service settings for a project. - -```plaintext -GET /projects/:id/services/irker -``` - -## Jira - -Jira issue tracker. - -### Get Jira service settings - -Get Jira service settings for a project. - -```plaintext -GET /projects/:id/services/jira -``` - -### Create/Edit Jira service - -Set Jira service for a project. - -> Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and -> `project_url` are replaced by `url`. If you are using an -> older version, [follow this documentation](https://gitlab.com/gitlab-org/gitlab/-/blob/8-13-stable-ee/doc/api/services.md#jira). - -```plaintext -PUT /projects/:id/services/jira -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `url` | string | yes | The URL to the Jira project which is being linked to this GitLab project. For example, `https://jira.example.com`. | -| `api_url` | string | no | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. | -| `username` | string | yes | The username of the user created to be used with GitLab/Jira. | -| `password` | string | yes | The password of the user created to be used with GitLab/Jira. | -| `active` | boolean | no | Activates or deactivates the service. Defaults to false (deactivated). | -| `jira_issue_transition_automatic` | boolean | no | Enable [automatic issue transitions](../integration/jira/issues.md#automatic-issue-transitions). Takes precedence over `jira_issue_transition_id` if enabled. Defaults to `false` | -| `jira_issue_transition_id` | string | no | The ID of one or more transitions for [custom issue transitions](../integration/jira/issues.md#custom-issue-transitions). Ignored if `jira_issue_transition_automatic` is enabled. Defaults to a blank string, which disables custom transitions. | -| `commit_events` | boolean | false | Enable notifications for commit events | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events | -| `comment_on_event_enabled` | boolean | false | Enable comments inside Jira issues on each GitLab event (commit / merge request) | - -### Delete Jira service - -Remove all previously Jira settings from a project. - -```plaintext -DELETE /projects/:id/services/jira -``` - -## Slack slash commands - -Ability to receive slash commands from a Slack chat instance. - -### Get Slack slash command service settings - -Get Slack slash command service settings for a project. - -```plaintext -GET /projects/:id/services/slack-slash-commands -``` - -Example response: - -```json -{ - "id": 4, - "title": "Slack slash commands", - "slug": "slack-slash-commands", - "created_at": "2017-06-27T05:51:39-07:00", - "updated_at": "2017-06-27T05:51:39-07:00", - "active": true, - "push_events": true, - "issues_events": true, - "confidential_issues_events": true, - "merge_requests_events": true, - "tag_push_events": true, - "note_events": true, - "job_events": true, - "pipeline_events": true, - "comment_on_event_enabled": false, - "properties": { - "token": "<your_access_token>" - } -} -``` - -### Create/Edit Slack slash command service - -Set Slack slash command for a project. - -```plaintext -PUT /projects/:id/services/slack-slash-commands -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | yes | The Slack token | - -### Delete Slack slash command service - -Delete Slack slash command service for a project. - -```plaintext -DELETE /projects/:id/services/slack-slash-commands -``` - -## Mattermost slash commands - -Ability to receive slash commands from a Mattermost chat instance. - -### Get Mattermost slash command service settings - -Get Mattermost slash command service settings for a project. - -```plaintext -GET /projects/:id/services/mattermost-slash-commands -``` - -### Create/Edit Mattermost slash command service - -Set Mattermost slash command for a project. - -```plaintext -PUT /projects/:id/services/mattermost-slash-commands -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | yes | The Mattermost token | -| `username` | string | no | The username to use to post the message | - -### Delete Mattermost slash command service - -Delete Mattermost slash command service for a project. - -```plaintext -DELETE /projects/:id/services/mattermost-slash-commands -``` - -## Packagist - -Update your project on Packagist (the main Composer repository) when commits or tags are pushed to GitLab. - -### Create/Edit Packagist service - -Set Packagist service for a project. - -```plaintext -PUT /projects/:id/services/packagist -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `username` | string | yes | The username of a Packagist account | -| `token` | string | yes | API token to the Packagist server | -| `server` | boolean | no | URL of the Packagist server. Leave blank for default: <https://packagist.org> | -| `push_events` | boolean | false | Enable notifications for push events | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events | -| `tag_push_events` | boolean | false | Enable notifications for tag push events | - -### Delete Packagist service - -Delete Packagist service for a project. - -```plaintext -DELETE /projects/:id/services/packagist -``` - -### Get Packagist service settings - -Get Packagist service settings for a project. - -```plaintext -GET /projects/:id/services/packagist -``` - -## Pipeline-Emails - -Get emails for GitLab CI/CD pipelines. - -### Create/Edit Pipeline-Emails service - -Set Pipeline-Emails service for a project. - -```plaintext -PUT /projects/:id/services/pipelines-email -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `recipients` | string | yes | Comma-separated list of recipient email addresses | -| `add_pusher` | boolean | no | Add pusher to recipients list | -| `notify_only_broken_pipelines` | boolean | no | Notify only broken pipelines | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected. The default value is "default" | -| `notify_only_default_branch` | boolean | no | Send notifications only for the default branch ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28271)) | -| `pipeline_events` | boolean | false | Enable notifications for pipeline events | - -### Delete Pipeline-Emails service - -Delete Pipeline-Emails service for a project. - -```plaintext -DELETE /projects/:id/services/pipelines-email -``` - -### Get Pipeline-Emails service settings - -Get Pipeline-Emails service settings for a project. - -```plaintext -GET /projects/:id/services/pipelines-email -``` - -## Pivotal Tracker - -Add commit messages as comments to Pivotal Tracker stories. - -See also the [Pivotal Tracker service documentation](../user/project/integrations/pivotal_tracker.md). - -### Create/Edit Pivotal Tracker service - -Set Pivotal Tracker service for a project. - -```plaintext -PUT /projects/:id/services/pivotaltracker -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | true | The Pivotal Tracker token | -| `restrict_to_branch` | boolean | false | Comma-separated list of branches to automatically inspect. Leave blank to include all branches. | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Pivotal Tracker service - -Delete Pivotal Tracker service for a project. - -```plaintext -DELETE /projects/:id/services/pivotaltracker -``` - -### Get Pivotal Tracker service settings - -Get Pivotal Tracker service settings for a project. - -```plaintext -GET /projects/:id/services/pivotaltracker -``` - -## Prometheus - -Prometheus is a powerful time-series monitoring service. - -### Create/Edit Prometheus service - -Set Prometheus service for a project. - -```plaintext -PUT /projects/:id/services/prometheus -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `api_url` | string | true | Prometheus API Base URL. For example, `http://prometheus.example.com/`. | -| `google_iap_audience_client_id` | string | false | Client ID of the IAP secured resource (looks like IAP_CLIENT_ID.apps.googleusercontent.com) | -| `google_iap_service_account_json` | string | false | `credentials.json` file for your service account, like { "type": "service_account", "project_id": ... } | - -### Delete Prometheus service - -Delete Prometheus service for a project. - -```plaintext -DELETE /projects/:id/services/prometheus -``` - -### Get Prometheus service settings - -Get Prometheus service settings for a project. - -```plaintext -GET /projects/:id/services/prometheus -``` - -## Pushover - -Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop. - -### Create/Edit Pushover service - -Set Pushover service for a project. - -```plaintext -PUT /projects/:id/services/pushover -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `api_key` | string | true | Your application key | -| `user_key` | string | true | Your user key | -| `priority` | string | true | The priority | -| `device` | string | false | Leave blank for all active devices | -| `sound` | string | false | The sound of the notification | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Pushover service - -Delete Pushover service for a project. - -```plaintext -DELETE /projects/:id/services/pushover -``` - -### Get Pushover service settings - -Get Pushover service settings for a project. - -```plaintext -GET /projects/:id/services/pushover -``` - -## Redmine - -Redmine issue tracker - -### Create/Edit Redmine service - -Set Redmine service for a project. - -```plaintext -PUT /projects/:id/services/redmine -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `new_issue_url` | string | true | New Issue URL | -| `project_url` | string | true | Project URL | -| `issues_url` | string | true | Issue URL | -| `description` | string | false | Description | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete Redmine service - -Delete Redmine service for a project. - -```plaintext -DELETE /projects/:id/services/redmine -``` - -### Get Redmine service settings - -Get Redmine service settings for a project. - -```plaintext -GET /projects/:id/services/redmine -``` - -## Slack notifications - -Receive event notifications in Slack - -### Create/Edit Slack service - -Set Slack service for a project. - -```plaintext -PUT /projects/:id/services/slack -``` - -NOTE: -Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4. - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `webhook` | string | true | `https://hooks.slack.com/services/...` | -| `username` | string | false | username | -| `channel` | string | false | Default channel to use if others are not configured | -| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | -| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | -| `commit_events` | boolean | false | Enable notifications for commit events | -| `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications | -| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | -| `confidential_note_channel` | string | false | The name of the channel to receive confidential note events notifications | -| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | -| `deployment_channel` | string | false | The name of the channel to receive deployment events notifications | -| `deployment_events` | boolean | false | Enable notifications for deployment events | -| `issue_channel` | string | false | The name of the channel to receive issues events notifications | -| `issues_events` | boolean | false | Enable notifications for issue events | -| `job_events` | boolean | false | Enable notifications for job events | -| `merge_request_channel` | string | false | The name of the channel to receive merge request events notifications | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events | -| `note_channel` | string | false | The name of the channel to receive note events notifications | -| `note_events` | boolean | false | Enable notifications for note events | -| `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications | -| `pipeline_events` | boolean | false | Enable notifications for pipeline events | -| `push_channel` | string | false | The name of the channel to receive push events notifications | -| `push_events` | boolean | false | Enable notifications for push events | -| `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications | -| `tag_push_events` | boolean | false | Enable notifications for tag push events | -| `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications | -| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | -| `vulnerability_channel` | string | false | **(ULTIMATE)** The name of the channel to receive vulnerability event notifications. | -| `vulnerability_events` | boolean | false | **(ULTIMATE)** Enable notifications for vulnerability events | - -### Delete Slack service - -Delete Slack service for a project. - -```plaintext -DELETE /projects/:id/services/slack -``` - -### Get Slack service settings - -Get Slack service settings for a project. - -```plaintext -GET /projects/:id/services/slack -``` - -## Microsoft Teams - -Group Chat Software - -### Create/Edit Microsoft Teams service - -Set Microsoft Teams service for a project. - -```plaintext -PUT /projects/:id/services/microsoft-teams -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `webhook` | string | true | The Microsoft Teams webhook. For example, `https://outlook.office.com/webhook/...` | -| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | -| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | -| `push_events` | boolean | false | Enable notifications for push events | -| `issues_events` | boolean | false | Enable notifications for issue events | -| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events | -| `tag_push_events` | boolean | false | Enable notifications for tag push events | -| `note_events` | boolean | false | Enable notifications for note events | -| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | -| `pipeline_events` | boolean | false | Enable notifications for pipeline events | -| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | - -### Delete Microsoft Teams service - -Delete Microsoft Teams service for a project. - -```plaintext -DELETE /projects/:id/services/microsoft-teams -``` - -### Get Microsoft Teams service settings - -Get Microsoft Teams service settings for a project. - -```plaintext -GET /projects/:id/services/microsoft-teams -``` - -## Mattermost notifications - -Receive event notifications in Mattermost - -### Create/Edit Mattermost notifications service - -Set Mattermost service for a project. - -```plaintext -PUT /projects/:id/services/mattermost -``` - -NOTE: -Specific event parameters (for example, `push_events` flag and `push_channel`) were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/11435) in GitLab 10.4. - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `webhook` | string | true | The Mattermost webhook. For example, `http://mattermost_host/hooks/...` | -| `username` | string | false | username | -| `channel` | string | false | Default channel to use if others are not configured | -| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines | -| `notify_only_default_branch` | boolean | false | DEPRECATED: This parameter has been replaced with `branches_to_be_notified` | -| `branches_to_be_notified` | string | false | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". The default value is "default" | -| `push_events` | boolean | false | Enable notifications for push events | -| `issues_events` | boolean | false | Enable notifications for issue events | -| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events | -| `tag_push_events` | boolean | false | Enable notifications for tag push events | -| `note_events` | boolean | false | Enable notifications for note events | -| `confidential_note_events` | boolean | false | Enable notifications for confidential note events | -| `pipeline_events` | boolean | false | Enable notifications for pipeline events | -| `wiki_page_events` | boolean | false | Enable notifications for wiki page events | -| `vulnerability_events` | boolean | false | **(ULTIMATE)** Enable notifications for vulnerability events | -| `push_channel` | string | false | The name of the channel to receive push events notifications | -| `issue_channel` | string | false | The name of the channel to receive issues events notifications | -| `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications | -| `merge_request_channel` | string | false | The name of the channel to receive merge request events notifications | -| `note_channel` | string | false | The name of the channel to receive note events notifications | -| `confidential_note_channel` | string | false | The name of the channel to receive confidential note events notifications | -| `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications | -| `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications | -| `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications | -| `vulnerability_channel` | string | false | **(ULTIMATE)** The name of the channel to receive vulnerability events notifications | - -### Delete Mattermost notifications service - -Delete Mattermost Notifications service for a project. - -```plaintext -DELETE /projects/:id/services/mattermost -``` - -### Get Mattermost notifications service settings - -Get Mattermost notifications service settings for a project. - -```plaintext -GET /projects/:id/services/mattermost -``` - -## JetBrains TeamCity CI - -A continuous integration and build server - -### Create/Edit JetBrains TeamCity CI service - -Set JetBrains TeamCity CI service for a project. - -> The build configuration in TeamCity must use the build format number `%build.vcs.number%`. Configure monitoring of all branches so merge requests build. That setting is in the VSC root advanced settings. - -```plaintext -PUT /projects/:id/services/teamcity -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `teamcity_url` | string | true | TeamCity root URL. For example, `https://teamcity.example.com` | -| `build_type` | string | true | Build configuration ID | -| `username` | string | true | A user with permissions to trigger a manual build | -| `password` | string | true | The password of the user | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete JetBrains TeamCity CI service - -Delete JetBrains TeamCity CI service for a project. - -```plaintext -DELETE /projects/:id/services/teamcity -``` - -### Get JetBrains TeamCity CI service settings - -Get JetBrains TeamCity CI service settings for a project. - -```plaintext -GET /projects/:id/services/teamcity -``` - -## Jenkins CI - -A continuous integration and build server - -### Create/Edit Jenkins CI service - -Set Jenkins CI service for a project. - -```plaintext -PUT /projects/:id/services/jenkins -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `jenkins_url` | string | true | Jenkins URL like `http://jenkins.example.com`. | -| `project_name` | string | true | The URL-friendly project name. Example: `my_project_name`. | -| `username` | string | false | Username for authentication with the Jenkins server, if authentication is required by the server. | -| `password` | string | false | Password for authentication with the Jenkins server, if authentication is required by the server. | -| `push_events` | boolean | false | Enable notifications for push events. | -| `merge_requests_events` | boolean | false | Enable notifications for merge request events. | -| `tag_push_events` | boolean | false | Enable notifications for tag push events. | - -### Delete Jenkins CI service - -Delete Jenkins CI service for a project. - -```plaintext -DELETE /projects/:id/services/jenkins -``` - -### Get Jenkins CI service settings - -Get Jenkins CI service settings for a project. - -```plaintext -GET /projects/:id/services/jenkins -``` - -## Jenkins CI (Deprecated) Service - -A continuous integration and build server - -NOTE: -This service was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/1600) in GitLab 13.0. - -### Create/Edit Jenkins CI (Deprecated) service - -Set Jenkins CI (Deprecated) service for a project. - -```plaintext -PUT /projects/:id/services/jenkins-deprecated -``` - -Parameters: - -- `project_url` (**required**) - Jenkins project URL like `http://jenkins.example.com/job/my-project/` -- `multiproject_enabled` (optional) - Multi-project mode is configured in Jenkins GitLab Hook plugin -- `pass_unstable` (optional) - Unstable builds are treated as passing - -### Delete Jenkins CI (Deprecated) service - -Delete Jenkins CI (Deprecated) service for a project. - -```plaintext -DELETE /projects/:id/services/jenkins-deprecated -``` - -### Get Jenkins CI (Deprecated) service settings - -Get Jenkins CI (Deprecated) service settings for a project. - -```plaintext -GET /projects/:id/services/jenkins-deprecated -``` - -## MockCI - -Mock an external CI. See [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service) for an example of a companion mock service. - -This service is only available when your environment is set to development. - -### Create/Edit MockCI service - -Set MockCI service for a project. - -```plaintext -PUT /projects/:id/services/mock-ci -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `mock_service_url` | string | true | `http://localhost:4004` | - -### Delete MockCI service - -Delete MockCI service for a project. - -```plaintext -DELETE /projects/:id/services/mock-ci -``` - -### Get MockCI service settings - -Get MockCI service settings for a project. - -```plaintext -GET /projects/:id/services/mock-ci -``` - -## YouTrack - -YouTrack issue tracker - -### Create/Edit YouTrack service - -Set YouTrack service for a project. - -```plaintext -PUT /projects/:id/services/youtrack -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `issues_url` | string | true | Issue URL | -| `project_url` | string | true | Project URL | -| `description` | string | false | Description | -| `push_events` | boolean | false | Enable notifications for push events | - -### Delete YouTrack Service - -Delete YouTrack service for a project. - -```plaintext -DELETE /projects/:id/services/youtrack -``` - -### Get YouTrack Service Settings - -Get YouTrack service settings for a project. - -```plaintext -GET /projects/:id/services/youtrack -``` +<!-- This redirect file can be deleted after <2021-11-09>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/api/settings.md b/doc/api/settings.md index 6b1faa0402f..7b8778973f2 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -248,7 +248,7 @@ listed in the descriptions of the relevant settings. | `deactivate_dormant_users` | boolean | no | Enable [automatic deactivation of dormant users](../user/admin_area/moderate_users.md#automatically-deactivate-dormant-users). | | `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts. | | `default_branch_name` | string | no | [Instance-level custom initial branch name](../user/project/repository/branches/default.md#instance-level-custom-initial-branch-name) ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225258) in GitLab 13.2). | -| `default_branch_protection` | integer | no | Determine if developers can push to the default branch. Can take: `0` _(not protected, both developers and maintainers can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push, or delete, the branch)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. | +| `default_branch_protection` | integer | no | Determine if developers can push to the default branch. Can take: `0` _(not protected, both developers and maintainers can push new commits and force push)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no one can force push)_ as a parameter. Default is `2`. | | `default_ci_config_path` | string | no | Default CI/CD configuration file and path for new projects (`.gitlab-ci.yml` if not set). | | `default_group_visibility` | string | no | What visibility level new groups receive. Can take `private`, `internal` and `public` as a parameter. Default is `private`. | | `default_project_creation` | integer | no | Default project creation protection. Can take: `0` _(No one)_, `1` _(Maintainers)_ or `2` _(Developers + Maintainers)_| @@ -407,6 +407,7 @@ listed in the descriptions of the relevant settings. | `spam_check_endpoint_enabled` | boolean | no | Enables Spam Check via external API endpoint. Default is `false`. | | `spam_check_endpoint_url` | string | no | URL of the external Spam Check service endpoint. | | `spam_check_api_key` | string | no | The API key used by GitLab for accessing the Spam Check service endpoint. | +| `suggest_pipeline_enabled` | boolean | no | Enable pipeline suggestion banner. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. | | `terms` | text | required by: `enforce_terms` | (**Required by:** `enforce_terms`) Markdown content for the ToS. | | `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (for example, from crawlers or abusive bots). | diff --git a/doc/api/snippet_repository_storage_moves.md b/doc/api/snippet_repository_storage_moves.md index a73542c8505..81473fdff91 100644 --- a/doc/api/snippet_repository_storage_moves.md +++ b/doc/api/snippet_repository_storage_moves.md @@ -10,7 +10,7 @@ type: reference > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49228) in GitLab 13.8. Snippet repositories can be moved between storages. This can be useful when -[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrate-to-gitaly-cluster), for +[migrating to Gitaly Cluster](../administration/gitaly/index.md#migrating-to-gitaly-cluster), for example. As snippet repository storage moves are processed, they transition through different states. Values diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md index f244c681086..4809166f357 100644 --- a/doc/api/usage_data.md +++ b/doc/api/usage_data.md @@ -13,7 +13,7 @@ The Service Data API is associated with [Service Ping](../development/service_pi > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57270) in GitLab 13.11. -Export all metric definitions as a single YAML file, similar to the [Metrics Dictionary](https://gitlab-org.gitlab.io/growth/product-intelligence/metric-dictionary), for easier importing. +Export all metric definitions as a single YAML file, similar to the [Metrics Dictionary](https://metrics.gitlab.com/index.html), for easier importing. ```plaintext GET /usage_data/metric_definitions diff --git a/doc/api/users.md b/doc/api/users.md index 4ec609e62e9..d8effc4d38f 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -987,7 +987,7 @@ error occurs a `400 Bad Request` is returned with a message explaining the error ## Add SSH key for user -Create new key owned by specified user. Available only for admin +Create new key owned by specified user. Available only for administrator. ```plaintext POST /users/:id/keys @@ -1018,7 +1018,7 @@ Parameters: ## Delete SSH key for given user -Deletes key owned by a specified user. Available only for admin. +Deletes key owned by a specified user. Available only for administrator. ```plaintext DELETE /users/:id/keys/:key_id @@ -1165,7 +1165,7 @@ Example response: ## Get a specific GPG key for a given user Get a specific GPG key for a given user. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/43693) -in GitLab 13.5, this endpoint can be accessed without admin authentication. +in GitLab 13.5, this endpoint can be accessed without administrator authentication. ```plaintext GET /users/:id/gpg_keys/:key_id @@ -1194,7 +1194,7 @@ Example response: ## Add a GPG key for a given user -Create new GPG key owned by the specified user. Available only for admins. +Create new GPG key owned by the specified user. Available only for administrator. ```plaintext POST /users/:id/gpg_keys @@ -1226,7 +1226,7 @@ Example response: ## Delete a GPG key for a given user -Delete a GPG key owned by a specified user. Available only for admins. +Delete a GPG key owned by a specified user. Available only for administrator. ```plaintext DELETE /users/:id/gpg_keys/:key_id @@ -1276,7 +1276,7 @@ Parameters: ## List emails for user -Get a list of a specified user's emails. Available only for admin +Get a list of a specified user's emails. Available only for administrator NOTE: Due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/25077) this endpoint currently @@ -1345,7 +1345,7 @@ error occurs a `400 Bad Request` is returned with a message explaining the error ## Add email for user -Create new email owned by specified user. Available only for admin +Create new email owned by specified user. Available only for administrator ```plaintext POST /users/:id/emails @@ -1372,7 +1372,7 @@ Parameters: ## Delete email for given user -Deletes email owned by a specified user. Available only for admin. +Deletes email owned by a specified user. Available only for administrator. ```plaintext DELETE /users/:id/emails/:email_id @@ -1385,7 +1385,7 @@ Parameters: ## Block user -Blocks the specified user. Available only for admin. +Blocks the specified user. Available only for administrator. ```plaintext POST /users/:id/block @@ -1405,7 +1405,7 @@ Returns: ## Unblock user -Unblocks the specified user. Available only for admin. +Unblocks the specified user. Available only for administrator. ```plaintext POST /users/:id/unblock @@ -1422,7 +1422,7 @@ Returns `201 OK` on success, `404 User Not Found` is user cannot be found or > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. -Deactivates the specified user. Available only for admin. +Deactivates the specified user. Available only for administrator. ```plaintext POST /users/:id/deactivate @@ -1437,7 +1437,7 @@ Returns: - `201 OK` on success. - `404 User Not Found` if user cannot be found. - `403 Forbidden` when trying to deactivate a user: - - Blocked by admin or by LDAP synchronization. + - Blocked by administrator or by LDAP synchronization. - That has any activity in past 90 days. These users cannot be deactivated. - That is internal. @@ -1445,7 +1445,7 @@ Returns: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22257) in GitLab 12.4. -Activates the specified user. Available only for admin. +Activates the specified user. Available only for administrator. ```plaintext POST /users/:id/activate @@ -1465,7 +1465,7 @@ Returns: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327354) in GitLab 14.3. -Bans the specified user. Available only for admin. +Bans the specified user. Available only for administrator. ```plaintext POST /users/:id/ban @@ -1485,7 +1485,7 @@ Returns: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327354) in GitLab 14.3. -Unbans the specified user. Available only for admin. +Unbans the specified user. Available only for administrator. ```plaintext POST /users/:id/unban @@ -1507,7 +1507,7 @@ Please refer to the [Events API documentation](events.md#get-user-contribution-e ## Get all impersonation tokens of a user -> Requires admin permissions. +> Requires administrator permissions. It retrieves every impersonation token of the user. Use the pagination parameters `page` and `per_page` to restrict the list of impersonation tokens. @@ -1639,7 +1639,7 @@ Example Responses: ## Get an impersonation token of a user -> Requires admin permissions. +> Requires administrators permissions. It shows a user's impersonation token. @@ -1678,7 +1678,7 @@ Example response: ## Create an impersonation token -> Requires admin permissions. +> Requires administrator permissions. > Token values are returned once. Make sure you save it - you can't access it again. It creates a new impersonation token. Only administrators can do this. @@ -1723,7 +1723,7 @@ Example response: ## Revoke an impersonation token -> Requires admin permissions. +> Requires administrator permissions. It revokes an impersonation token. @@ -1845,7 +1845,7 @@ Example response: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20532) in GitLab 12.8. -Lists all projects and groups a user is a member of. This endpoint is available for admins only. +Lists all projects and groups a user is a member of. This endpoint is available for administrators only. It returns the `source_id`, `source_name`, `source_type` and `access_level` of a membership. Source can be of type `Namespace` (representing a group) or `Project`. The response represents only direct memberships. Inherited memberships, for example in subgroups, are not included. Access levels are represented by an integer value. For more details, read about the meaning of [access level values](access_requests.md#valid-access-levels). @@ -1865,7 +1865,7 @@ Returns: - `200 OK` on success. - `404 User Not Found` if user can't be found. -- `403 Forbidden` when not requested by an admin. +- `403 Forbidden` when not requested by an administrator. - `400 Bad Request` when requested type is not supported. ```shell diff --git a/doc/api/version.md b/doc/api/version.md index b076993f00e..80269bc5697 100644 --- a/doc/api/version.md +++ b/doc/api/version.md @@ -6,8 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Version API **(FREE)** -> Introduced in GitLab 8.13. - Retrieve version information for this GitLab instance. Responds `200 OK` for authenticated users. diff --git a/doc/api/vulnerability_findings.md b/doc/api/vulnerability_findings.md index dfc6074a1aa..36604ebf87d 100644 --- a/doc/api/vulnerability_findings.md +++ b/doc/api/vulnerability_findings.md @@ -74,77 +74,66 @@ Example response: [ { "id": null, - "report_type": "dependency_scanning", - "name": "Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js", - "severity": "unknown", - "confidence": "undefined", + "report_type": "sast", + "name": "Possible command injection", + "severity": "high", + "confidence": "high", "scanner": { - "external_id": "gemnasium", - "name": "Gemnasium" + "external_id": "brakeman", + "name": "Brakeman", + "vendor": "GitLab" }, "identifiers": [ { - "external_type": "gemnasium", - "external_id": "9952e574-7b5b-46fa-a270-aeb694198a98", - "name": "Gemnasium-9952e574-7b5b-46fa-a270-aeb694198a98", - "url": "https://deps.sec.gitlab.com/packages/npm/saml2-js/versions/1.5.0/advisories" - }, - { - "external_type": "cve", - "external_id": "CVE-2017-11429", - "name": "CVE-2017-11429", - "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-11429" + "external_type": "brakeman_warning_code", + "external_id": "14", + "name": "Brakeman Warning Code 14", + "url": "https://brakemanscanner.org/docs/warning_types/command_injection/" } ], - "project_fingerprint": "fa6f5b6c5d240b834ac5e901dc69f9484cef89ec", - "uuid": "31f483bc-bfc0-586d-9b92-f1015c4535b8", - "create_vulnerability_feedback_issue_path": "/tests/yarn-remediation-test/vulnerability_feedback", - "create_vulnerability_feedback_merge_request_path": "/tests/yarn-remediation-test/vulnerability_feedback", - "create_vulnerability_feedback_dismissal_path": "/tests/yarn-remediation-test/vulnerability_feedback", + "project_fingerprint": "ac218b1770af030cfeef967752ab803c55afb36d", + "uuid": "ad5e3be3-a193-55f5-a200-bc12865fb09c", + "create_jira_issue_url": null, + "false_positive": true, + "create_vulnerability_feedback_issue_path": "/root/test-false-positive/-/vulnerability_feedback", + "create_vulnerability_feedback_merge_request_path": "/root/test-false-positive/-/vulnerability_feedback", + "create_vulnerability_feedback_dismissal_path": "/root/test-false-positive/-/vulnerability_feedback", "project": { - "id": 31, - "name": "yarn-remediation-test", - "full_path": "/tests/yarn-remediation-test", - "full_name": "tests / yarn-remediation-test" + "id": 2, + "name": "Test False Positive", + "full_path": "/root/test-false-positive", + "full_name": "Administrator / Test False Positive" }, "dismissal_feedback": null, "issue_feedback": null, "merge_request_feedback": null, - "description": "Some XML DOM traversal and canonicalization APIs may be inconsistent in handling of comments within XML nodes. Incorrect use of these APIs by some SAML libraries results in incorrect parsing of the inner text of XML nodes such that any inner text after the comment is lost prior to cryptographically signing the SAML message. Text after the comment therefore has no impact on the signature on the SAML message.\r\n\r\nA remote attacker can modify SAML content for a SAML service provider without invalidating the cryptographic signature, which may allow attackers to bypass primary authentication for the affected SAML service provider.", - "links": [ - { - "url": "https://github.com/Clever/saml2/commit/3546cb61fd541f219abda364c5b919633609ef3d#diff-af730f9f738de1c9ad87596df3f6de84R279" - }, - { - "url": "https://www.kb.cert.org/vuls/id/475445" - }, - { - "url": "https://github.com/Clever/saml2/issues/127" - } - ], + "description": null, + "links": [], "location": { - "file": "yarn.lock", - "dependency": { - "package": { - "name": "saml2-js" - }, - "version": "1.5.0" - } + "file": "app/controllers/users_controller.rb", + "start_line": 42, + "class": "UsersController", + "method": "list_users" }, - "details": { - "custom_field": { - "name": "URLs", - "type": "list", - "items": [ - { - "type": "url", - "href": "http://site.com/page/1" - } - ] - } + "remediations": [ + null + ], + "solution": null, + "evidence": null, + "request": null, + "response": null, + "evidence_source": null, + "supporting_messages": [], + "assets": [], + "details": {}, + "state": "detected", + "scan": { + "type": "sast", + "status": "success", + "start_time": "2021-09-02T20:55:48", + "end_time": "2021-09-02T20:55:48" }, - "solution": "Upgrade to fixed version.\r\n", - "blob_path": "/tests/yarn-remediation-test/blob/cc6c4a0778460455ae5d16ca7025ca9ca1ca75ac/yarn.lock" + "blob_path": "/root/test-false-positive/-/blob/dfd75607752a839bbc9c7362d111effaa470fecd/app/controllers/users_controller.rb#L42" } ] ``` |