diff options
Diffstat (limited to 'doc/user/project/integrations')
| -rw-r--r-- | doc/user/project/integrations/github.md | 2 | ||||
| -rw-r--r-- | doc/user/project/integrations/img/slack_setup.png | bin | 86314 -> 65156 bytes | |||
| -rw-r--r-- | doc/user/project/integrations/img/zentao_product_id.png | bin | 0 -> 40486 bytes | |||
| -rw-r--r-- | doc/user/project/integrations/index.md | 4 | ||||
| -rw-r--r-- | doc/user/project/integrations/mattermost_slash_commands.md | 4 | ||||
| -rw-r--r-- | doc/user/project/integrations/overview.md | 7 | ||||
| -rw-r--r-- | doc/user/project/integrations/services_templates.md | 9 | ||||
| -rw-r--r-- | doc/user/project/integrations/slack.md | 104 | ||||
| -rw-r--r-- | doc/user/project/integrations/slack_slash_commands.md | 41 | ||||
| -rw-r--r-- | doc/user/project/integrations/webex_teams.md | 2 | ||||
| -rw-r--r-- | doc/user/project/integrations/zentao.md | 40 |
11 files changed, 130 insertions, 83 deletions
diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 6b342392bdf..4908d21e764 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab provides an integration for updating the pipeline statuses on GitHub. This is especially useful if using GitLab for CI/CD only. -This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirroring-and-pipeline-status-sharing) +This project integration is separate from the [instance wide GitHub integration](../import/github.md#mirror-a-repository-and-share-pipeline-status) and is automatically configured on [GitHub import](../../../integration/github.md).  diff --git a/doc/user/project/integrations/img/slack_setup.png b/doc/user/project/integrations/img/slack_setup.png Binary files differindex 7928fb7d495..8acae659fb4 100644 --- a/doc/user/project/integrations/img/slack_setup.png +++ b/doc/user/project/integrations/img/slack_setup.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/index.md b/doc/user/project/integrations/index.md index 6f86098b33d..ac6e18e8e6a 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -17,8 +17,8 @@ For more information, read the [overview of integrations](overview.md) or learn how to manage your integrations: - *For GitLab 13.3 and later,* read [Project integration management](../../admin_area/settings/project_integration_management.md). -- *For GitLab 13.2 and earlier,* read [Service Templates](services_templates.md), - which are deprecated and [scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) +- *For GitLab 13.2 and earlier,* read [Integration Management](../../admin_area/settings/project_integration_management.md), + which replaced the deprecated Service Templates [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) in GitLab 14.0. ## Project webhooks diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index 5b5feb73b69..8027cc1c61e 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -22,7 +22,7 @@ on your configuration: - **Omnibus GitLab installations**: Mattermost is bundled with [Omnibus GitLab](https://docs.gitlab.com/omnibus/). To configure Mattermost for Omnibus GitLab, read the - [Omnibus GitLab Mattermost documentation](https://docs.gitlab.com/omnibus/gitlab-mattermost/). + [Omnibus GitLab Mattermost documentation](../../../integration/mattermost/index.md). - **If Mattermost is installed on the same server as GitLab**, use the [automated configuration](#automated-configuration). - **For all other installations**, use the [manual configuration](#manual-configuration). @@ -68,7 +68,7 @@ information from GitLab. To get this information: 1. In a different browser tab than your current Mattermost session, sign in to GitLab as a user with [Administrator role](../../permissions.md). -1. On the top bar, select **Menu >** **{admin}** **Admin**. +1. On the top bar, select **Menu > Admin**. 1. In the left menu, select **Settings > Integrations**, then select **Mattermost slash commands**. 1. GitLab displays potential values for Mattermost settings. Copy the **Request URL** diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 13def74450c..a6f739c6408 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -12,8 +12,10 @@ functionality to GitLab. ## Accessing integrations -You can find the available integrations under your project's -**Settings > Integrations** page. +To find the available integrations for your project: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. There are more than 20 integrations to integrate with. Select the one that you want to configure. @@ -60,6 +62,7 @@ Click on the service links to see further configuration instructions and details | [Unify Circuit](unify_circuit.md) | Receive events notifications. | **{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/services_templates.md b/doc/user/project/integrations/services_templates.md deleted file mode 100644 index 37df48c75f8..00000000000 --- a/doc/user/project/integrations/services_templates.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: '../../admin_area/settings/project_integration_management.md' -remove_date: '2021-09-09' ---- - -This document was moved to [another location](../../admin_area/settings/project_integration_management.md). - -<!-- This redirect file can be deleted after <2021-09-09>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 5db4e839b54..a38d2157699 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -10,27 +10,27 @@ The Slack notifications service enables your GitLab project to send events (such as issue creation) to your existing Slack team as notifications. Setting up Slack notifications requires configuration changes for both Slack and GitLab. -You can also use Slack slash commands to control GitLab inside Slack. This is the -separately configured [Slack slash commands](slack_slash_commands.md). +You can also use [Slack slash commands](slack_slash_commands.md) +to control GitLab from Slack. Slash commands are configured separately. -## Slack configuration +## Configure Slack 1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). 1. Identify the Slack channel where notifications should be sent to by default. Select **Add Incoming WebHooks integration** to add the configuration. -1. Copy the **Webhook URL**, which is used later in the GitLab configuration. +1. Copy the **Webhook URL** to use later when you configure GitLab. -## GitLab configuration +## Configure GitLab 1. On the top bar, select **Menu > Projects** and find your project. 1. On the left sidebar, select **Settings > Integrations**. -1. Select the **Slack notifications** integration to configure it. +1. Select **Slack notifications**. 1. In the **Enable integration** section, select the **Active** checkbox. 1. In the **Trigger** section, select the checkboxes for each type of GitLab event to send to Slack as a notification. For a full list, see - [Triggers available for Slack notifications](#triggers-available-for-slack-notifications). + [Triggers for Slack notifications](#triggers-for-slack-notifications). By default, messages are sent to the channel you configured during - [Slack integration](#slack-configuration). + [Slack configuration](#configure-slack). 1. (Optional) To send messages to a different channel, multiple channels, or as a direct message: - *To send messages to channels,* enter the Slack channel names, separated by @@ -40,38 +40,39 @@ separately configured [Slack slash commands](slack_slash_commands.md). NOTE: Usernames and private channels are not supported. -1. In **Webhook**, enter the webhook URL you copied from the previous - [Slack integration](#slack-configuration) step. +1. In **Webhook**, enter the webhook URL you copied in the + [Slack configuration](#configure-slack) step. 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 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 in order to trigger a +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 notification. 1. Select **Test settings** to verify your information, and then select **Save changes**. Your Slack team now starts receiving GitLab event notifications as configured. -### Triggers available for Slack notifications +## Triggers for Slack notifications The following triggers are available for Slack notifications: -| Trigger | Description | -|------------------------|-------------| -| **Push** | Triggered by a push to the repository. | -| **Issue** | Triggered when an issue is created, updated, or closed. | -| **Confidential issue** | Triggered when a confidential issue is created, updated, or closed. | -| **Merge request** | Triggered when a merge request is created, updated, or merged. | -| **Note** | Triggered when someone adds a comment. | -| **Confidential note** | Triggered when someone adds a confidential note. | -| **Tag push** | Triggered when a new tag is pushed to the repository. | -| **Pipeline** | Triggered when a pipeline status changes. | -| **Wiki page** | Triggered when a wiki page is created or updated. | -| **Deployment** | Triggered when a deployment starts or finishes. | -| **Alert** | Triggered when a new, unique alert is recorded. | +| Trigger name | Trigger event | +| ------------------------ | ------------------------------------------------------ | +| **Push** | A push to the repository. | +| **Issue** | An issue is created, updated, or closed. | +| **Confidential issue** | A confidential issue is created, updated, or closed. | +| **Merge request** | A merge request is created, updated, or merged. | +| **Note** | A comment is added. | +| **Confidential note** | A confidential note is added. | +| **Tag push** | A new tag is pushed to the repository. | +| **Pipeline** | A pipeline status changed. | +| **Wiki page** | A wiki page is created or updated. | +| **Deployment** | A deployment starts or finishes. | +| **Alert** | A new, unique alert is recorded. | +| **Vulnerability** | **(ULTIMATE)** A new, unique vulnerability is recorded. | ## Troubleshooting @@ -81,45 +82,48 @@ for errors relating to your Slack service. ### Something went wrong on our end -This is a generic error shown in the GitLab UI and does not mean much by itself. +You might get this generic error message in the GitLab UI. Review [the logs](../../../administration/logs.md#productionlog) to find -an error message and keep troubleshooting from there. +the error message and keep troubleshooting from there. ### `certificate verify failed` -You may see an entry similar to the following in your Sidekiq log: +You might see an entry like the following in your Sidekiq log: ```plaintext 2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg ProjectServiceWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"ProjectServiceWorker", :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"} ``` -This is probably a problem either with GitLab communicating with Slack, or GitLab -communicating with itself. The former is less likely, as Slack's security certificates -should _hopefully_ always be trusted. We can establish which we're dealing with by using -the below rails console script. +This issue occurs when there is a problem with GitLab communicating with Slack, +or GitLab communicating with itself. +The former is less likely, as Slack security certificates should always be trusted. -```shell -# start a rails console: -sudo gitlab-rails console -e production +To view which of these problems is the cause of the issue: -# or for source installs: -bundle exec rails console -e production -``` +1. Start a Rails console: -```ruby -# run this in the Rails console -# replace <SLACK URL> with your actual Slack URL -result = Net::HTTP.get(URI('https://<SLACK URL>'));0 + ```shell + sudo gitlab-rails console -e production -# replace <GITLAB URL> with your actual GitLab URL -result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 -``` + # for source installs: + bundle exec rails console -e production + ``` + +1. Run the following commands: + + ```ruby + # replace <SLACK URL> with your actual Slack URL + result = Net::HTTP.get(URI('https://<SLACK URL>'));0 + + # replace <GITLAB URL> with your actual GitLab URL + result = Net::HTTP.get(URI('https://<GITLAB URL>'));0 + ``` -If GitLab is not trusting HTTPS connections to itself, then you may -need to [add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +If GitLab does not trust HTTPS connections to itself, +[add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -If GitLab is not trusting connections to Slack, then the GitLab -OpenSSL trust store is incorrect. Some typical causes: +If GitLab does not trust connections to Slack, +the GitLab OpenSSL trust store is incorrect. Typical causes are: - Overriding the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}`. - Accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem`. diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index dfebf9a1123..066a2f83753 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -8,27 +8,36 @@ info: To determine the technical writer assigned to the Stage/Group associated w > Introduced in GitLab 8.15. -Slack slash commands allow you to control GitLab and view content right inside -Slack, without having to leave it. This requires configurations in both Slack and GitLab. +If you want to control and view GitLab content while you're +working in Slack, you can use Slack slash commands. +To use Slack slash commands, you must configure both Slack and GitLab. -GitLab can also send events (e.g., `issue created`) to Slack as notifications. -This is the separately configured [Slack Notifications Service](slack.md). +GitLab can also send events (for example, `issue created`) to Slack as notifications. +The [Slack notifications service](slack.md) is configured separately. NOTE: -For GitLab.com, use the [Slack app](gitlab_slack_application.md) instead. +For GitLab.com, use the [GitLab Slack app](gitlab_slack_application.md) instead. -## Configuration +## Configure GitLab and Slack -1. Slack slash commands are scoped to a project. Navigate to the [Integrations page](overview.md#accessing-integrations) in your project's settings, i.e. **Project > Settings > Integrations**. -1. Select the **Slack slash commands** integration to configure it. This page contains required information to complete the configuration in Slack. Leave this browser tab open. -1. Open a new browser tab and sign in to your Slack team. [Start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). -1. Enter a trigger term. We suggest you use the project name. Click **Add Slash Command Integration**. -1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. In particular, the URL needs to be copied and pasted. Click **Save Integration** to complete the configuration in Slack. -1. While still on the Slack configuration page, copy the **token**. Go back to the GitLab browser tab and paste in the **token**. -1. Ensure that the **Active** toggle is enabled and click **Save changes** to complete the configuration in GitLab. +Slack slash command [integrations](overview.md#accessing-integrations) +are scoped to a project. - +1. In GitLab, on the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Slack slash commands**. Leave this browser tab open. +1. Open a new browser tab, sign in to your Slack team, and [start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). +1. Enter a trigger command. We suggest you use the project name. + Select **Add Slash Command Integration**. +1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. + In particular, make sure you copy and paste the **URL**. -## Usage +  -You can now use the [Slack slash commands](../../../integration/slash_commands.md). +1. On the Slack configuration page, select **Save Integration** and copy the **Token**. +1. Go back to the GitLab configuration page and paste in the **Token**. +1. Ensure the **Active** checkbox is selected and select **Save changes**. + +## Slash commands + +You can now use the available [Slack slash commands](../../../integration/slash_commands.md). diff --git a/doc/user/project/integrations/webex_teams.md b/doc/user/project/integrations/webex_teams.md index 3632fdf0e0c..de152aabde5 100644 --- a/doc/user/project/integrations/webex_teams.md +++ b/doc/user/project/integrations/webex_teams.md @@ -27,7 +27,7 @@ notifications: 1. Navigate to: - **Settings > Integrations** in a project to enable the integration at the project level. - **Settings > Integrations** in a group to enable the integration at the group level. - - On the top bar, select **Menu >** **{admin}** **Admin**. Then, in the left sidebar, + - On the top bar, select **Menu > Admin**. Then, in the left sidebar, select **Settings > Integrations** to enable an instance-level integration. 1. Select the **Webex Teams** integration. 1. Ensure that the **Active** toggle is enabled. diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md new file mode 100644 index 00000000000..ab8a7829139 --- /dev/null +++ b/doc/user/project/integrations/zentao.md @@ -0,0 +1,40 @@ +--- +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)** + +[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**. + +  + +1. To verify the ZenTao connection is working, select **Test settings**. +1. Select **Save changes**. |
