diff options
Diffstat (limited to 'doc/user/project/integrations')
-rw-r--r-- | doc/user/project/integrations/custom_issue_tracker.md | 33 | ||||
-rw-r--r-- | doc/user/project/integrations/github.md | 8 | ||||
-rw-r--r-- | doc/user/project/integrations/img/custom_issue_tracker_v14_5.png | bin | 0 -> 6636 bytes | |||
-rw-r--r-- | doc/user/project/integrations/img/zentao_product_id.png | bin | 0 -> 40486 bytes | |||
-rw-r--r-- | doc/user/project/integrations/mattermost.md | 2 | ||||
-rw-r--r-- | doc/user/project/integrations/microsoft_teams.md | 23 | ||||
-rw-r--r-- | doc/user/project/integrations/overview.md | 1 | ||||
-rw-r--r-- | doc/user/project/integrations/slack.md | 2 | ||||
-rw-r--r-- | doc/user/project/integrations/unify_circuit.md | 2 | ||||
-rw-r--r-- | doc/user/project/integrations/webhook_events.md | 254 | ||||
-rw-r--r-- | doc/user/project/integrations/webhooks.md | 10 | ||||
-rw-r--r-- | doc/user/project/integrations/zentao.md | 42 |
12 files changed, 229 insertions, 148 deletions
diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index eaab1933b79..d155f91e40b 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,31 +4,40 @@ 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 --- -# Custom issue tracker service **(FREE)** +# Custom issue tracker **(FREE)** -Use a custom issue tracker that is not in the integration list. +You can integrate an [external issue tracker](../../../integration/external-issue-tracker.md) +with GitLab. If your preferred issue tracker is not listed in the +[integrations list](../../../integration/external-issue-tracker.md#integration), +you can enable a custom issue tracker. + +After you enable the custom issue tracker, a link to the issue tracker displays +on the left sidebar in your project. + +![Custom issue tracker link](img/custom_issue_tracker_v14_5.png) + +## Enable a custom issue tracker To enable a custom issue tracker in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Custom issue tracker**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: - **Project URL**: The URL to view all the issues in the custom issue tracker. - **Issue URL**: The URL to view an issue in the custom issue tracker. The URL must contain `:id`. - GitLab replaces `:id` with the issue number (for example, - `https://customissuetracker.com/project-name/:id`, which becomes `https://customissuetracker.com/project-name/123`). + GitLab replaces `:id` with the issue number (for example, + `https://customissuetracker.com/project-name/:id`, which becomes + `https://customissuetracker.com/project-name/123`). - **New issue URL**: <!-- The line below was originally added in January 2018: https://gitlab.com/gitlab-org/gitlab/-/commit/778b231f3a5dd42ebe195d4719a26bf675093350 --> - **This URL is not used and removal is planned in a future release.** - Enter any URL here. - For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). - -1. Select **Save changes** or optionally select **Test settings**. + **This URL is not used and an [issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/327503) to remove it.** + Enter any URL. -After you configure and enable the custom issue tracker service, a link appears on the GitLab -project pages. This link takes you to the custom issue tracker. +1. Optional. Select **Test settings**. +1. Select **Save changes**. ## Reference issues in a custom issue tracker diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 3177aaefb75..47a81594ca9 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -37,20 +37,20 @@ Complete these steps in GitLab: 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated on GitHub. 1. Enter the path to your project on GitHub, such as `https://github.com/username/repository`. -1. (Optional) To disable static status check names, clear the **Static status check names** checkbox. +1. (Optional) To disable static status check names, clear the **Enable static status check names** checkbox. 1. Select **Save changes** or optionally select **Test settings**. After configuring the integration, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) to configure pipelines to run for open pull requests. -### Static / dynamic status check names +### Static or dynamic status check names > - Introduced in GitLab 11.5: using static status check names as opt-in option. > - [In GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/issues/9931), static status check names is default behavior for new projects. This makes it possible to mark these status checks as **Required** on GitHub. -When **Static status check names** is enabled on the integration page, your +When **Enable static status check names** is checked on the integration page, your GitLab instance host name is appended to a status check name. -When disabled, it uses dynamic status check names and appends the branch name. +When unchecked, it uses dynamic status check names and appends the branch name. diff --git a/doc/user/project/integrations/img/custom_issue_tracker_v14_5.png b/doc/user/project/integrations/img/custom_issue_tracker_v14_5.png Binary files differnew file mode 100644 index 00000000000..e316a2acc39 --- /dev/null +++ b/doc/user/project/integrations/img/custom_issue_tracker_v14_5.png diff --git a/doc/user/project/integrations/img/zentao_product_id.png b/doc/user/project/integrations/img/zentao_product_id.png Binary files differnew file mode 100644 index 00000000000..a91b4c3f82d --- /dev/null +++ b/doc/user/project/integrations/img/zentao_product_id.png diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 92e5feefb73..119f219499c 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -54,7 +54,7 @@ Then fill in the integration configuration: To change the bot's username, provide a value. - **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want notifications about failed pipelines only. -- **Branches to be notified**: The branches to send notifications for. +- **Branches for which notifications are to be sent**: The branches to send notifications for. - **Labels to be notified**: (Optional) Labels required for the issue or merge request to trigger a notification. Leave blank to notify for all issues and merge requests. - **Labels to be notified behavior**: When you use the **Labels to be notified** filter, diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index fac26f8e70c..6679bab745b 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -18,8 +18,8 @@ in Microsoft Teams. To integrate the services, you must: To configure Microsoft Teams to listen for notifications from GitLab: -1. In Microsoft Teams, search for "incoming webhook" in the search bar, and select the - **Incoming Webhook** item: +1. In Microsoft Teams, type `incoming webhook` in the search bar, and select + **Incoming Webhook**: ![Select Incoming Webhook](img/microsoft_teams_select_incoming_webhook.png) @@ -34,11 +34,12 @@ To configure Microsoft Teams to listen for notifications from GitLab: After you configure Microsoft Teams to receive notifications, you must configure GitLab to send the notifications: -1. Sign in to GitLab as a user with [Administrator](../../permissions.md) and go - to your project's page. -1. Go to **Settings > Integrations** and select **Microsoft Teams Notification**. -1. Select **Active** to enable the integration. -1. Select the checkbox next to each **Trigger** to enable: +1. Sign in to GitLab as an administrator. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Microsoft Teams notifications**. +1. To enable the integration, select **Active**. +1. In the **Trigger** section, select the checkbox next to each event to enable it: - Push - Issue - Confidential issue @@ -46,15 +47,15 @@ GitLab to send the notifications: - Note - Confidential note - Tag push - - Pipeline - If you enable this trigger, you can also select **Notify only broken pipelines** to be notified only about failed pipelines. + - Pipeline - Wiki page 1. In **Webhook**, paste the URL you copied when you [configured Microsoft Teams](#configure-microsoft-teams). -1. (Optional) If you enabled the pipeline trigger, you can select the +1. Optional. If you enable the pipeline trigger, select the **Notify only broken pipelines** checkbox to push notifications only when pipelines break. 1. Select the branches you want to send notifications for. -1. Click **Save changes**. +1. Select **Save changes**. -## Resources +## Related topics - [Setting up an incoming webhook on Microsoft Teams](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using#setting-up-a-custom-incoming-webhook). diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 2c154467115..819c17c12fd 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -62,6 +62,7 @@ Click on the service links to see further configuration instructions and details | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | | [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | | [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | +| [ZenTao](zentao.md) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | ## Push hooks limit diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index a38d2157699..d399c7f2901 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -45,7 +45,7 @@ to control GitLab from Slack. Slash commands are configured separately. 1. (Optional) In **Username**, enter the username of the Slack bot that sends the notifications. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. -1. In the **Branches to be notified** dropdown, select which types of branches +1. In the **Branches for which notifications are to be sent** dropdown, select which types of branches to send notifications for. 1. Leave the **Labels to be notified** field blank to get all notifications, or add labels that the issue or merge request must have to trigger a diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 814c64d8140..daab24a8ab9 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -21,7 +21,7 @@ In GitLab: 1. Select the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit. 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. 1. Select the **Notify only broken pipelines** checkbox to notify only on failures. -1. In the **Branches to be notified** dropdown, select which types of branches to send notifications for. +1. In the **Branches for which notifications are to be sent** dropdown, select which types of branches to send notifications for. 1. Select `Save changes` or optionally select **Test settings**. Your Unify Circuit conversation now starts receiving GitLab event notifications. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 9b07e6322bc..ab70a2d43f4 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -9,31 +9,50 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can configure a [webhook](webhooks.md) in your project that triggers when an event occurs. The following events are supported. +Event type | Trigger +---------------------------------------------|----------------------------------------------------------------------------- +[Push event](#push-events) | A push is made to the repository. +[Tag event](#tag-events) | Tags are created or deleted in the repository. +[Issue event](#issue-events) | A new issue is created or an existing issue is updated, closed, or reopened. +[Comment event](#comment-events) | A new comment is made on commits, merge requests, issues, and code snippets. +[Merge request event](#merge-request-events) | A merge request is created, updated, merged, or closed, or a commit is added in the source branch. +[Wiki page event](#wiki-page-events) | A wiki page is created, updated, or deleted. +[Pipeline event](#pipeline-events) | A pipeline status changes. +[Job event](#job-events) | A job status changes. +[Deployment event](#deployment-events) | A deployment starts, succeeds, fails, or is canceled. +[Group member event](#group-member-events) | A user is added or removed from a group, or a user's access level or access expiration date changes. +[Subgroup event](#subgroup-events) | A subgroup is created or removed from a group. +[Feature flag event](#feature-flag-events) | A feature flag is turned on or off. +[Release event](#release-events) | A release is created or updated. + +NOTE: +If an author has no public email listed in their +[GitLab profile](https://gitlab.com/-/profile), the `email` attribute in the +webhook payload displays a value of `[REDACTED]`. + ## Push events -Triggered when you push to the repository except when pushing tags. +Push events are triggered when you push to the repository, except when: -NOTE: -When more than 20 commits are pushed at once, the `commits` webhook -attribute only contains the newest 20 for performance reasons. Loading -detailed commit data is expensive. Note that despite only 20 commits being -present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. +- You push tags. +- A single push includes changes for more than three branches by default + (depending on the [`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)). -NOTE: -If a branch creation push event is generated without new commits being introduced, the -`commits` attribute in the payload is empty. +If you push more than 20 commits at once, the `commits` +attribute in the payload contains information about the newest 20 commits only. +Loading detailed commit data is expensive, so this restriction exists for performance reasons. +The `total_commits_count` attribute contains the actual number of commits. -Also, if a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) -branches, this hook isn't executed. +If you create and push a branch without any new commits, the +`commits` attribute in the payload is empty. -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Push Hook ``` -**Payload example:** +Payload example: ```json { @@ -111,20 +130,19 @@ X-Gitlab-Event: Push Hook ## Tag events -Triggered when you create (or delete) tags to the repository. +Tag events are triggered when you create or delete tags in the repository. -NOTE: -If a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) -tags, this hook is not executed. +This hook is not executed if a single push includes changes for more than three +tags by default (depending on the +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)). -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Tag Push Hook ``` -**Payload example:** +Payload example: ```json { @@ -171,22 +189,26 @@ X-Gitlab-Event: Tag Push Hook ## Issue events -Triggered when a new issue is created or an existing issue was updated/closed/reopened. +Issue events are triggered when a new issue is created or +an existing issue is updated, closed, or reopened. -**Request header**: - -```plaintext -X-Gitlab-Event: Issue Hook -``` - -**Available `object_attributes.action`:** +The available values for `object_attributes.action` in the payload are: - `open` - `close` - `reopen` - `update` -**Payload example:** +The `assignee` and `assignee_id` keys are deprecated +and contain the first assignee only. + +Request header: + +```plaintext +X-Gitlab-Event: Issue Hook +``` + +Payload example: ```json { @@ -329,31 +351,31 @@ X-Gitlab-Event: Issue Hook } ``` -NOTE: -`assignee` and `assignee_id` keys are deprecated and now show the first assignee only. - ## Comment events -Triggered when a new comment is made on commits, merge requests, issues, and code snippets. -The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The -payload also includes information about the target of the comment. For example, -a comment on an issue includes the specific issue information under the `issue` key. -Valid target types: +Comment events are triggered when a new comment is made on commits, +merge requests, issues, and code snippets. + +The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). +The payload includes information about the target of the comment. For example, +a comment on an issue includes specific issue information under the `issue` key. + +The valid target types are: - `commit` - `merge_request` - `issue` - `snippet` -### Comment on commit +### Comment on a commit -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -428,15 +450,15 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on merge request +### Comment on a merge request -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -558,15 +580,18 @@ X-Gitlab-Event: Note Hook } ``` -### Comment on issue +### Comment on an issue + +- The `assignee_id` field is deprecated and shows the first assignee only. +- The `event_type` is set to `confidential_note` for confidential issues. -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -664,21 +689,15 @@ X-Gitlab-Event: Note Hook } ``` -NOTE: -`assignee_id` field is deprecated and now shows the first assignee only. - -NOTE: -`event_type` is set to `confidential_note` for confidential issues. - -### Comment on code snippet +### Comment on a code snippet -**Request header**: +Request header: ```plaintext X-Gitlab-Event: Note Hook ``` -**Payload example:** +Payload example: ```json { @@ -749,15 +768,13 @@ X-Gitlab-Event: Note Hook ## Merge request events -Triggered when a new merge request is created, an existing merge request was updated/merged/closed or a commit is added in the source branch. +Merge request events are triggered when: -**Request header**: +- A new merge request is created. +- An existing merge request is updated, approved, unapproved, merged, or closed. +- A commit is added in the source branch. -```plaintext -X-Gitlab-Event: Merge Request Hook -``` - -**Available `object_attributes.action`:** +The available values for `object_attributes.action` in the payload are: - `open` - `close` @@ -767,7 +784,13 @@ X-Gitlab-Event: Merge Request Hook - `unapproved` - `merge` -**Payload example:** +Request header: + +```plaintext +X-Gitlab-Event: Merge Request Hook +``` + +Payload example: ```json { @@ -921,17 +944,17 @@ X-Gitlab-Event: Merge Request Hook } ``` -## Wiki Page events +## Wiki page events -Triggered when a wiki page is created, updated or deleted. +Wiki page events are triggered when a wiki page is created, updated, or deleted. -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Wiki Page Hook ``` -**Payload example**: +Payload example: ```json { @@ -981,18 +1004,18 @@ X-Gitlab-Event: Wiki Page Hook ## Pipeline events +Pipeline events are triggered when the status of a pipeline changes. + In [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53159) and later, the pipeline webhook returns only the latest jobs. -Triggered on status change of Pipeline. - -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Pipeline Hook ``` -**Payload example**: +Payload example: ```json { @@ -1233,15 +1256,17 @@ X-Gitlab-Event: Pipeline Hook ## Job events -Triggered on status change of a job. +Job events are triggered when the status of a job changes. + +The `commit.id` in the payload is the ID of the pipeline, not the ID of the commit. -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Job Hook ``` -**Payload example**: +Payload example: ```json { @@ -1303,24 +1328,24 @@ X-Gitlab-Event: Job Hook } ``` -Note that `commit.id` is the ID of the pipeline, not the ID of the commit. - ## Deployment events -Triggered when a deployment: +Deployment events are triggered when a deployment: -- Starts ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5.) +- Starts ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41214) in GitLab 13.5) - Succeeds - Fails - Is cancelled -**Request Header**: +The `deployable_id` in the payload is the ID of the CI/CD job. + +Request header: ```plaintext X-Gitlab-Event: Deployment Hook ``` -**Payload example**: +Payload example: ```json { @@ -1363,28 +1388,26 @@ X-Gitlab-Event: Deployment Hook } ``` -Note that `deployable_id` is the ID of the CI job. - ## Group member events **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. Member events are triggered when: -- A user is added as a group member -- The access level of a user has changed -- The expiration date for user access has been updated -- A user has been removed from the group +- A user is added as a group member. +- The access level of a user changes. +- The expiration date for user access is updated. +- A user is removed from the group. ### Add member to group -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Member Hook ``` -**Payload example**: +Payload example: ```json { @@ -1406,13 +1429,13 @@ X-Gitlab-Event: Member Hook ### Update member access level or expiration date -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Member Hook ``` -**Payload example**: +Payload example: ```json { @@ -1434,13 +1457,13 @@ X-Gitlab-Event: Member Hook ### Remove member from group -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Member Hook ``` -**Payload example**: +Payload example: ```json { @@ -1466,18 +1489,18 @@ X-Gitlab-Event: Member Hook Subgroup events are triggered when: -- A [subgroup is created in a group](#subgroup-created-in-a-group) -- A [subgroup is removed from a group](#subgroup-removed-from-a-group) +- A [subgroup is created in a group](#create-a-subgroup-in-a-group). +- A [subgroup is removed from a group](#remove-a-subgroup-from-a-group). -### Subgroup created in a group +### Create a subgroup in a group -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Subgroup Hook ``` -**Payload example**: +Payload example: ```json { @@ -1497,15 +1520,17 @@ X-Gitlab-Event: Subgroup Hook } ``` -### Subgroup removed from a group +### Remove a subgroup from a group -**Request Header**: +This webhook is not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group). + +Request header: ```plaintext X-Gitlab-Event: Subgroup Hook ``` -**Payload example**: +Payload example: ```json { @@ -1525,20 +1550,17 @@ X-Gitlab-Event: Subgroup Hook } ``` -NOTE: -Webhooks for when a [subgroup is removed from a group](#subgroup-removed-from-a-group) are not triggered when a [subgroup is transferred to a new parent group](../../group/index.md#transfer-a-group) +## Feature flag events -## Feature Flag events +Feature flag events are triggered when a feature flag is turned on or off. -Triggered when a feature flag is turned on or off. - -**Request Header**: +Request header: ```plaintext X-Gitlab-Event: Feature Flag Hook ``` -**Payload example**: +Payload example: ```json { @@ -1580,20 +1602,20 @@ X-Gitlab-Event: Feature Flag Hook ## Release events -Triggered when a release is created or updated. +Release events are triggered when a release is created or updated. -**Request Header**: +The available values for `object_attributes.action` in the payload are: + +- `create` +- `update` + +Request header: ```plaintext X-Gitlab-Event: Release Hook ``` -**Available `object_attributes.action`:** - -- `create` -- `update` - -**Payload example**: +Payload example: ```json { diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 0891d48c038..e0405955d3d 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -40,8 +40,14 @@ including: ## Group webhooks **(PREMIUM)** -You can configure a webhook for a group to ensure all projects in the group -receive the same webhook settings. +You can configure a group webhook, which is triggered by events +that occur across all projects in the group. + +Group webhooks can also be configured to listen for events that are +specific to a group, including: + +- [Group member events](webhook_events.md#group-member-events) +- [Subgroup events](webhook_events.md#subgroup-events) ## Configure a webhook diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md new file mode 100644 index 00000000000..67125c3ebbf --- /dev/null +++ b/doc/user/project/integrations/zentao.md @@ -0,0 +1,42 @@ +--- +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 +--- + +# ZenTao product integration **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338178) in GitLab 14.5. + +[ZenTao](https://www.zentao.net/) is a web-based project management platform. + +## Configure ZenTao + +This integration requires a ZenTao API secret key. + +Complete these steps in ZenTao: + +1. Go to your **Admin** page and select **Develop > Application**. +1. Select **Add Application**. +1. Under **Name** and **Code**, enter a name and a code for the new secret key. +1. Under **Account**, select an existing account name. +1. Select **Save**. +1. Copy the generated key to use in GitLab. + +## Configure GitLab + +Complete these steps in GitLab: + +1. Go to your project and select **Settings > Integrations**. +1. Select **ZenTao**. +1. Turn on the **Active** toggle under **Enable Integration**. +1. Provide the ZenTao configuration information: + - **ZenTao Web URL**: The base URL of the ZenTao instance web interface you're linking to this GitLab project (for example, `example.zentao.net`). + - **ZenTao API URL** (optional): The base URL to the ZenTao instance API. Defaults to the Web URL value if not set. + - **ZenTao API token**: Use the key you generated when you [configured ZenTao](#configure-zentao). + - **ZenTao Product ID**: To display issues from a single ZenTao product in a given GitLab project. The Product ID can be found in the ZenTao product page under **Settings > Overview**. + + ![ZenTao settings page](img/zentao_product_id.png) + +1. To verify the ZenTao connection is working, select **Test settings**. +1. Select **Save changes**. |