diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-01 21:09:42 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-12-01 21:09:42 +0300 |
commit | 102255f6d4209b9ee54c6f36d9391aae0a4b0dfb (patch) | |
tree | 12f8bdb3ce84444f0948b1d00f49457975a129b5 /doc/user/project/integrations | |
parent | 893ba862a7808ac7099c0d5c6d6ad618ae4e2665 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/user/project/integrations')
22 files changed, 122 insertions, 123 deletions
diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 92a660a3b93..ad62e783edc 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -7,8 +7,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Atlassian Bamboo CI Service GitLab provides integration with Atlassian Bamboo for continuous integration. -When configured, pushes to a project will trigger a build in Bamboo automatically. -Merge requests will also display CI status showing whether the build is pending, +When configured, pushes to a project trigger a build in Bamboo automatically. +Merge requests also display CI status showing whether the build is pending, failed, or completed successfully. It also provides a link to the Bamboo build page for more information. @@ -56,7 +56,7 @@ service in GitLab. access to trigger the build plan. Leave these fields blank if you do not require authentication. 1. Save or optionally click 'Test Settings'. Please note that 'Test Settings' - will actually trigger a build in Bamboo. + actually triggers a build in Bamboo. ## Troubleshooting diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 0f93b479294..4e2ee9b3662 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -16,7 +16,7 @@ in the table below. | `issues_url` | The URL to the issue in Bugzilla project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | | `new_issue_url` | This is the URL to create a new issue in Bugzilla for the project linked to this GitLab project. Note that the `new_issue_url` requires PRODUCT_NAME to be updated with the product/project name in Bugzilla. | -Once you have configured and enabled Bugzilla you'll see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. +Once you have configured and enabled Bugzilla, you see the Bugzilla link on the GitLab project pages that takes you to the appropriate Bugzilla project. ## Referencing issues in Bugzilla @@ -27,7 +27,7 @@ Issues in Bugzilla can be referenced in two alternative ways: then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker the internal issue will be linked. +We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. Please note that `<PROJECT>` part is ignored and links always point to the address specified in `issues_url`. diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 8ba4c6d2f2e..143f0e2a25d 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -11,7 +11,7 @@ To enable the Custom Issue Tracker integration in a project: 1. Go to **Settings > Integrations**. 1. Click **Custom Issue Tracker** 1. Fill in the tracker's details, such as title, description, and URLs. - You will be able to edit these fields later as well. + You can edit these fields later as well. These are some of the required fields: @@ -19,11 +19,11 @@ To enable the Custom Issue Tracker integration in a project: | --------------- | ----------- | | **Project URL** | The URL to the project in the custom issue tracker. | | **Issues URL** | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | - | **New issue URL** | Currently unused. Will be changed in a future release. | + | **New issue URL** | Currently unused. Planned to be changed in a future release. | 1. Click **Test settings and save changes**. -After you configure and enable the Custom Issue Tracker service, you'll see a link on the GitLab +After you configure and enable the Custom Issue Tracker service, you see a link on the GitLab project pages that takes you to that custom issue tracker. ## Referencing issues diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index c2e0b0527c0..8e0a167a968 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -17,7 +17,7 @@ To send GitLab event notifications to a Discord channel, create a webhook in Dis 1. Open the Discord channel you want to receive GitLab event notifications. 1. From the channel menu, select **Edit channel**. 1. Click on **Webhooks** menu item. -1. Click the **Create Webhook** button and fill in the name of the bot that will post the messages. Optionally, edit the avatar. +1. Click the **Create Webhook** button and fill in the name of the bot to post the messages. Optionally, edit the avatar. 1. Note the URL from the **WEBHOOK URL** field. 1. Click the **Save** button. @@ -32,4 +32,4 @@ With the webhook URL created in the Discord channel, you can set up the Discord 1. Paste the webhook URL that you copied from the create Discord webhook step. 1. Configure the remaining options and click the **Save changes** button. -The Discord channel you created the webhook for will now receive notification of the GitLab events that were configured. +The Discord channel you created the webhook for now receives notification of the GitLab events that were configured. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 5c0d61b4d8c..2274913d349 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Enabling emails on push -By enabling this service, you will receive email notifications for every change +By enabling this service, you receive email notifications for every change that is pushed to your project. From the [Integrations page](overview.md#accessing-integrations) @@ -16,8 +16,8 @@ In the _Recipients_ area, provide a list of emails separated by spaces or newlin The following options are available: -- **Push events** - Email will be triggered when a push event is received. -- **Tag push events** - Email will be triggered when a tag is created and pushed. +- **Push events** - Email is triggered when a push event is received. +- **Tag push events** - Email is triggered when a tag is created and pushed. - **Send from committer** - Send notifications from the committer's email address if the domain is part of the domain GitLab is running on (e.g. `user@gitlab.com`). - **Disable code diffs** - Don't include possibly sensitive code diffs in notification body. diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 7aae897ce53..1c0309cab87 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -49,8 +49,7 @@ to configure pipelines to run for open pull requests. This makes it possible to mark these status checks as _Required_ on GitHub. With **Static status check names** enabled on the integration page, your -GitLab instance host name is going to be appended to a status check name, -whereas in case of dynamic status check names, a branch name is going to be -appended. +GitLab instance host name is appended to a status check name, +whereas in case of dynamic status check names, a branch name is appended. ![Configure GitHub Project Integration](img/github_configuration.png) diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 2d8bc2e64eb..3756343c6b3 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -25,8 +25,7 @@ The simplest way to enable the GitLab Slack application for your workspace is to install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) from the [Slack App Directory](https://slack.com/apps). -Clicking install will take you to the -[GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) +Clicking install takes you to the [GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) where you can select a project to enable the GitLab Slack application for. ![GitLab Slack application landing page](img/gitlab_slack_app_landing_page.png) @@ -71,7 +70,7 @@ GitLab error: project or alias not found After confirming the installation, you, and everyone else in your Slack team, can use all the [slash commands](../../../integration/slash_commands.md). -When you perform your first slash command you will be asked to authorize your +When you perform your first slash command, you are asked to authorize your Slack user on GitLab.com. The only difference with the [manually configurable Slack slash commands](slack_slash_commands.md) diff --git a/doc/user/project/integrations/hangouts_chat.md b/doc/user/project/integrations/hangouts_chat.md index 9492486a2cf..06dcca6eb44 100644 --- a/doc/user/project/integrations/hangouts_chat.md +++ b/doc/user/project/integrations/hangouts_chat.md @@ -14,7 +14,7 @@ The Hangouts Chat service sends notifications from GitLab to the room for which 1. Open the chat room in which you want to see the notifications. 1. From the chat room menu, select **Configure Webhooks**. -1. Click on **ADD WEBHOOK** and fill in the name of the bot that will post the messages. Optionally define avatar. +1. Click on **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally define an avatar. 1. Click **SAVE** and copy the **Webhook URL** of your webhook. See also [the Hangouts Chat documentation for configuring incoming webhooks](https://developers.google.com/hangouts/chat/how-tos/webhooks) @@ -30,6 +30,6 @@ When you have the **Webhook URL** for your Hangouts Chat room webhook, you can s 1. Paste the **Webhook URL** that you copied from the Hangouts Chat configuration step. 1. Configure the remaining options and click `Save changes`. -Your Hangouts Chat room will now start receiving GitLab event notifications as configured. +Your Hangouts Chat room now starts receiving GitLab event notifications as configured. ![Hangouts Chat configuration](img/hangouts_chat_configuration.png) diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 764104b9068..0e5163e992a 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Project integrations You can find the available integrations under your project's -**Settings ➔ Integrations** page. You need to have at least +**Settings > Integrations** page. You need to have at least [maintainer permission](../../permissions.md) on the project. ## Integrations @@ -16,13 +16,13 @@ Integrations allow you to integrate GitLab with other applications. They are a bit like plugins in that they allow a lot of freedom in adding functionality to GitLab. -[Learn more about integrations.](overview.md) +Learn more [about integrations](overview.md). ## Project webhooks Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events -like pushes, issues or merge requests. GitLab will send a POST request with data +like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. -[Learn more about webhooks.](webhooks.md) +Learn more [about webhooks](webhooks.md). diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 3d136341226..8dd7e4309b4 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -7,14 +7,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Irker IRC Gateway GitLab provides a way to push update messages to an Irker server. When -configured, pushes to a project will trigger the service to send data directly +configured, pushes to a project trigger the service to send data directly to the Irker server. See the project homepage for further information: <https://gitlab.com/esr/irker> ## Needed setup -You will first need an Irker daemon. You can download the Irker code +You first need an Irker daemon. You can download the Irker code [from its repository](https://gitlab.com/esr/irker): ```shell @@ -26,8 +26,8 @@ This script is the gateway script, it acts both as an IRC client, for sending messages to an IRC server obviously, and as a TCP server, for receiving messages from the GitLab service. -If the Irker server runs on the same machine, you are done. If not, you will -need to follow the firsts steps of the next section. +If the Irker server runs on the same machine, you are done. If not, you +need to follow the first steps of the next section. ## Complete these steps in GitLab @@ -40,7 +40,7 @@ need to follow the firsts steps of the next section. 1. Enter the server port of `irkerd` (e.g. defaults to 6659) in the `Server port` field on the Web page. 1. Optional: if `Default IRC URI` is set, it has to be in the format - `irc[s]://domain.name` and will be prepend to each and every channel provided + `irc[s]://domain.name` and is prepended to each and every channel provided by the user which is not a full URI. 1. Specify the recipients (e.g. #channel1, user1, etc.) 1. Save or optionally click "Test Settings". @@ -48,13 +48,13 @@ need to follow the firsts steps of the next section. ## Note on Irker recipients Irker accepts channel names of the form `chan` and `#chan`, both for the -`#chan` channel. If you want to send messages in query, you will need to add +`#chan` channel. If you want to send messages in query, you need to add `,isnick` after the channel name, in this form: `Aorimn,isnick`. In this latter case, `Aorimn` is treated as a nick and no more as a channel name. Irker can also join password-protected channels. Users need to append `?key=thesecretpassword` to the channel name. When using this feature remember to -**not** put the `#` sign in front of the channel name; failing to do so will -result on Irker joining a channel literally named `#chan?key=password` henceforth +**not** put the `#` sign in front of the channel name; failing to do so +results in Irker joining a channel literally named `#chan?key=password` henceforth leaking the channel key through the `/whois` IRC command (depending on IRC server configuration). This is due to a long standing Irker bug. diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 3513fdbda11..924b7439d3b 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -18,7 +18,7 @@ Features include: - GitLab links to the Jira issue. - The Jira issue adds a comment with details and a link back to the activity in GitLab. - **Mention that a commit or MR resolves or closes a specific Jira issue** and when it's merged to the default branch: - - GitLab's MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they will close. + - GitLab's MR displays a note that it closed the Jira issue. Prior to the merge, MRs indicate which issue they close. - The Jira issue shows the activity and is closed or otherwise transitioned as specified in your GitLab settings. - **View a list of Jira issues directly in GitLab** **(PREMIUM)** @@ -38,7 +38,7 @@ For an overview, see [Agile Management - GitLab-Jira Basic Integration](https:// Each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab project can interact with _all_ Jira projects in that instance, once -configured. Therefore, you will not have to explicitly associate +configured. Therefore, you do not have to explicitly associate a GitLab project with any single Jira project. If you have one Jira instance, you can pre-fill the settings page with a default @@ -61,7 +61,7 @@ In order to enable the Jira service in GitLab, you need to first configure the p > **Notes:** > > - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. -> - In order to support Oracle's Access Manager, GitLab will send additional cookies +> - In order to support Oracle's Access Manager, GitLab sends additional cookies > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. @@ -80,7 +80,7 @@ Enter the further details on the page as described in the following table. | Field | Description | | ----- | ----------- | | `Web URL` | The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., `https://jira.example.com`. | -| `Jira API URL` | The base URL to the Jira instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | +| `Jira API URL` | The base URL to the Jira instance API. Web URL value is used if not set. For example, `https://jira-api.example.com`. Leave this field blank (or use the same value of `Web URL`) if using **Jira Cloud**. | | `Username or Email` | Created in [configuring Jira](#configuring-jira) step. Use `username` for **Jira Server** or `email` for **Jira Cloud**. | | `Password/API token` |Created in [configuring Jira](#configuring-jira) step. Use `password` for **Jira Server** or `API token` for **Jira Cloud**. | | `Transition ID` | Required for closing Jira issues via commits or merge requests. This is the ID of a transition in Jira that moves issues to a desired state. (See [Obtaining a transition ID](#obtaining-a-transition-id).) If you insert multiple transition IDs separated by `,` or `;`, the issue is moved to each state, one after another, using the given order. | @@ -90,7 +90,8 @@ To enable users to view Jira issues inside the GitLab project, select **Enable J You can only display issues from a single Jira project within a given GitLab project. CAUTION: **Caution:** -If you enable Jira issues with the setting above, all users that have access to this GitLab project will be able to view all issues from the specified Jira project. +If you enable Jira issues with the setting above, all users that have access to this GitLab project +are able to view all issues from the specified Jira project. When you have configured all settings, click **Test settings and save changes**. @@ -127,9 +128,9 @@ Jira issue IDs must be formatted in uppercase for the integration to work. ### Reference Jira issues When GitLab project has Jira issue tracker configured and enabled, mentioning -Jira issue in GitLab will automatically add a comment in Jira issue with the +Jira issues in GitLab automatically adds a comment in Jira issue with the link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, e.g., `PROJECT-7`, will add a comment in Jira issue in the +referencing an issue, `PROJECT-7` for example, adds a comment in Jira issue in the format: ```plaintext @@ -145,7 +146,7 @@ ENTITY_TITLE ![example of mentioning or closing the Jira issue](img/jira_issue_reference.png) -For example, the following commit will reference the Jira issue with `PROJECT-1` as its ID: +For example, the following commit references the Jira issue with `PROJECT-1` as its ID: ```shell git commit -m "PROJECT-1 Fix spelling and grammar" @@ -155,8 +156,8 @@ git commit -m "PROJECT-1 Fix spelling and grammar" Jira issues can be closed directly from GitLab by using trigger words in commits and merge requests. When a commit which contains the trigger word -followed by the Jira issue ID in the commit message is pushed, GitLab will -add a comment in the mentioned Jira issue and immediately close it (provided +followed by the Jira issue ID in the commit message is pushed, GitLab +adds a comment in the mentioned Jira issue and immediately closes it (provided the transition ID was set up correctly). There are currently three trigger words, and you can use either one to achieve @@ -168,12 +169,12 @@ the same goal: where `PROJECT-1` is the ID of the Jira issue. -> **Notes:** -> -> - Only commits and merges into the project's default branch (usually **master**) will -> close an issue in Jira. You can change your projects default branch under -> [project settings](img/jira_project_settings.png). -> - The Jira issue will not be transitioned if it has a resolution. +Note the following: + +- Only commits and merges into the project's default branch (usually `master`) + close an issue in Jira. You can change your project's default branch under + [project settings](img/jira_project_settings.png). +- The Jira issue is not transitioned if it has a resolution. Let's consider the following example: @@ -183,7 +184,7 @@ Let's consider the following example: in GitLab contains the improvement 1. In the merge request description we use the issue closing trigger `Closes PROJECT-7`. -1. Once the merge request is merged, the Jira issue will be automatically closed +1. Once the merge request is merged, the Jira issue is automatically closed with a comment and an associated link to the commit that resolved the issue. In the following screenshot you can see what the link references to the Jira @@ -191,7 +192,7 @@ issue look like. ![A Git commit that causes the Jira issue to be closed](img/jira_merge_request_close.png) -Once this merge request is merged, the Jira issue will be automatically closed +Once this merge request is merged, the Jira issue is automatically closed with a link to the commit that resolved the issue. ![The GitLab integration closes Jira issue](img/jira_service_close_issue.png) @@ -244,7 +245,7 @@ If these features do not work as expected, it is likely due to a problem with th Make sure that the Jira user you set up for the integration has the correct access permission to post comments on a Jira issue and also to transition the issue, if you'd like GitLab to also be able to do so. -Jira issue references and update comments will not work if the GitLab issue tracker is disabled. +Jira issue references and update comments do not work if the GitLab issue tracker is disabled. ### GitLab is unable to close a Jira issue @@ -259,6 +260,6 @@ Jira lists.) CAPTCHA may be triggered after several consecutive failed login attempts which may lead to a `401 unauthorized` error when testing your Jira integration. -If CAPTCHA has been triggered, you will not be able to use Jira's REST API to -authenticate with the Jira site. You will need to log in to your Jira instance +If CAPTCHA has been triggered, you can't use Jira's REST API to +authenticate with the Jira site. You need to log in to your Jira instance and complete the CAPTCHA. diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 7894a7c1cda..39370f8a84e 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -6,10 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Creating a username and password for Jira Server -We need to create a user in Jira which will have access to all projects that -need to integrate with GitLab. +We need to create a user in Jira to have access to all projects that need to integrate with GitLab. -As an example, we'll create a user named `gitlab` and add it to a new group +As an example, we create a user named `gitlab` and add it to a new group named `gitlab-developers`. NOTE: **Note:** @@ -24,15 +23,16 @@ access to your Jira projects. This is covered in the process below. 1. The next step is to create a new user (e.g., `gitlab`) who has write access to projects in Jira. Enter the user's name and a _valid_ e-mail address since Jira sends a verification e-mail to set up the password. - _**Note:** Jira creates the username automatically by using the e-mail - prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create - an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password._ + + Jira creates the username automatically by using the e-mail + prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You + need to create an HTTP basic authentication password. You can do this by visiting the user + profile, looking up the username, and setting a password. ![Jira create new user](img/jira_create_new_user.png) -1. Create a `gitlab-developers` group. (We will give this group write access to Jira - projects in a later step). Go to the **Groups** tab on the left, and select **Add group**. +1. Create a `gitlab-developers` group (we give this group write access to Jira + projects in a later step.) Go to the **Groups** tab on the left, and select **Add group**. ![Jira create new user](img/jira_create_new_group.png) @@ -53,7 +53,7 @@ access to your Jira projects. This is covered in the process below. To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. -1. Once your permission scheme is created, you'll be taken back to the permissions scheme list. +1. Once your permission scheme is created, you are taken back to the permissions scheme list. Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` from the dropdown. @@ -61,4 +61,4 @@ access to your Jira projects. This is covered in the process below. ![Jira group access](img/jira_group_access.png) The Jira configuration is complete. Write down the new Jira username and its -password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). +password as they are needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 8d288b4378c..8538199cacb 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -15,9 +15,9 @@ You can also use Mattermost slash commands to control GitLab inside Mattermost. To enable Mattermost integration you must create an incoming webhook integration: 1. Sign in to your Mattermost instance. -1. Visit incoming webhooks, that will be something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. +1. Visit incoming webhooks, that is something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. 1. Choose a display name, description and channel, those can be overridden on GitLab. -1. Save it, copy the **Webhook URL**, we'll need this later for GitLab. +1. Save it and copy the **Webhook URL** because we need this later for GitLab. Incoming Webhooks might be blocked on your Mattermost instance. Ask your Mattermost admin to enable it on: @@ -35,7 +35,7 @@ After you set up Mattermost, it's time to set up GitLab. Navigate to the [Integrations page](overview.md#accessing-integrations) and select the **Mattermost notifications** service to configure it. -There, you will see a checkbox with the following events that can be triggered: +There, you see a checkbox with the following events that can be triggered: - Push - Issue @@ -55,7 +55,7 @@ At the end, fill in your Mattermost details: | Field | Description | | ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, it will be something like: `http://mattermost.example/hooks/5xo…` | +| **Webhook** | The incoming webhook URL which you have to set up on Mattermost, similar to: `http://mattermost.example/hooks/5xo…` | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index acb10f636b0..df510a1abf4 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -37,7 +37,7 @@ commands in Mattermost and then enable the service in GitLab. ### Step 1. Enable custom slash commands in Mattermost -This step is only required when using a source install, Omnibus installs will be +This step is only required when using a source install. Omnibus installs are preconfigured with the right settings. The first thing to do in Mattermost is to enable custom slash commands from @@ -61,13 +61,12 @@ the administrator console. 1. Open a new tab for GitLab, go to your project's [Integrations page](overview.md#accessing-integrations) and select the **Mattermost command** service to configure it. - A screen will appear with all the values you need to copy in Mattermost as + A screen appears with all the values you need to copy in Mattermost as described in the next step. Leave the window open. NOTE: **Note:** - GitLab will propose some values for the Mattermost settings. The only one - required to copy-paste as-is is the **Request URL**, all the others are just - suggestions. + GitLab offers some values for the Mattermost settings. Only **Request URL** is required + as offered, all the others are just suggestions. ![Mattermost setup instructions](img/mattermost_config_help.png) @@ -96,12 +95,12 @@ in a new slash command. NOTE: **Note:** If you plan on connecting multiple projects, pick a slash command trigger word that relates to your projects such as `/gitlab-project-name` or even - just `/project-name`. Only use `/gitlab` if you will only connect a single + just `/project-name`. Only use `/gitlab` if you plan to only connect a single project to your Mattermost team. ![Mattermost add command configuration](img/mattermost_slash_command_configuration.png) -1. After you set up all the values, copy the token (we will use it below) and +1. After you set up all the values, copy the token (we use it below) and click **Done**. ![Mattermost slash command token](img/mattermost_slash_command_token.png) @@ -120,12 +119,12 @@ GitLab project you configured. ## Authorizing Mattermost to interact with GitLab -The first time a user will interact with the newly created slash commands, -Mattermost will trigger an authorization process. +The first time a user interacts with the newly created slash commands, +Mattermost triggers an authorization process. ![Mattermost bot authorize](img/mattermost_bot_auth.png) -This will connect your Mattermost user with your GitLab user. You can +This connects your Mattermost user with your GitLab user. You can see all authorized chat accounts in your profile's page under **Chat**. When the authorization process is complete, you can start interacting with @@ -158,7 +157,7 @@ Mattermost webhooks do not have access to private channels. If a private channel is required, you can edit the webhook's channel in Mattermost and select a private channel. It is not possible to use different channels for -different types of notifications - all events will be sent to the specified channel. +different types of notifications. All events are sent to the specified channel. ## Further reading diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 5a8d699ab11..136da05d0e8 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -31,7 +31,7 @@ After you set up Microsoft Teams, it's time to set up GitLab. Navigate to the [Integrations page](overview.md#accessing-integrations) and select the **Microsoft Teams Notification** service to configure it. -There, you will see a checkbox with the following events that can be triggered: +There, you see a checkbox with the following events that can be triggered: - Push - Issue diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index c2368bea3ad..7c13a6a5a53 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -69,7 +69,7 @@ Click on the service links to see further configuration instructions and details > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17874) in GitLab 12.4. If a single push includes changes to more than three branches or tags, services -supported by `push_hooks` and `tag_push_hooks` events won't be executed. +supported by `push_hooks` and `tag_push_hooks` events aren't executed. The number of branches or tags supported can be changed via [`push_event_hooks_limit` application setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 885a440c549..38d6194b390 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -15,9 +15,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w | ----- | ----------- | | `project_url` | The URL to the project in Redmine which is being linked to this GitLab project | | `issues_url` | The URL to the issue in Redmine project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | - | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and will be removed in a future release.** | + | `new_issue_url` | This is the URL to create a new issue in Redmine for the project linked to this GitLab project. **This is currently not being used and is planned be removed in a future release.** | - Once you have configured and enabled Redmine you'll see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. + Once you have configured and enabled Redmine, you see the Redmine link on the GitLab project pages that takes you to the appropriate Redmine project. As an example, below is a configuration for a project named `gitlab-ci`. @@ -34,7 +34,7 @@ Issues in Redmine can be referenced in two alternative ways: then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). -We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker the internal issue will be linked. +We suggest using the longer format if you have both internal and external issue trackers enabled. If you use the shorter format and an issue with the same ID exists in the internal issue tracker, the internal issue is linked. Please note that `<PROJECT>` part is ignored and links always point to the address specified in `issues_url`. diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 01685c689ce..a60af93a899 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -24,8 +24,7 @@ If you disable the template: - GitLab default values again become the default values for integrations on new projects. -- Projects previously configured using the template will continue to use - those settings. +- Projects previously configured using the template continue to use those settings. If you change the template, the revised values are applied to new projects. This feature does not provide central administration of integration settings. @@ -49,7 +48,7 @@ Recommendation: - Copy the working settings from a project to the template. There is no "Test settings" option when enabling templates. If the settings do not work, -these incorrect settings will be applied to all existing projects that do not already have +these incorrect settings are applied to all existing projects that do not already have the integration configured. Fixing the integration then needs to be done project-by-project. ## Service for external issue trackers @@ -58,6 +57,6 @@ The following image shows an example service template for Redmine. ![Redmine service template](img/services_templates_redmine_example.png) -For each project, you will still need to configure the issue tracking +For each project, you still need to configure the issue tracking URLs by replacing `:issues_tracker_id` in the above screenshot with the ID used by your external issue tracker. diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 87e47b739a7..df1150f4b07 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -17,9 +17,9 @@ separately configured [Slack slash commands](slack_slash_commands.md). ## Slack configuration 1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook). -1. Select the Slack channel where notifications will be sent to by default. +1. Select the Slack channel where notifications should be sent to by default. Click the **Add Incoming WebHooks integration** button to add the configuration. -1. Copy the **Webhook URL**, which we will use later in the GitLab configuration. +1. Copy the **Webhook URL**, which we use later in the GitLab configuration. ## GitLab configuration @@ -47,7 +47,7 @@ separately configured [Slack slash commands](slack_slash_commands.md). to send notifications for. 1. Click **Test settings and save changes**. -Your Slack team will now start receiving GitLab event notifications as configured. +Your Slack team now starts receiving GitLab event notifications as configured. ### Triggers available for Slack notifications diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index 9de245da59c..e8dcb577aba 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -12,7 +12,8 @@ The Unify Circuit service sends notifications from GitLab to the conversation fo 1. Open the conversation in which you want to see the notifications. 1. From the conversation menu, select **Configure Webhooks**. -1. Click **ADD WEBHOOK** and fill in the name of the bot that will post the messages. Optionally define avatar. +1. Click **ADD WEBHOOK** and fill in the name of the bot to post the messages. Optionally + define an avatar. 1. Click **SAVE** and copy the **Webhook URL** of your webhook. For more information, see the [Unify Circuit documentation for configuring incoming webhooks](https://www.circuit.com/unifyportalfaqdetail?articleId=164448). @@ -28,6 +29,6 @@ When you have the **Webhook URL** for your Unify Circuit conversation webhook, y 1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step. 1. Configure the remaining options and click `Save changes`. -Your Unify Circuit conversation will now start receiving GitLab event notifications as configured. +Your Unify Circuit conversation now starts receiving GitLab event notifications as configured. ![Unify Circuit configuration](img/unify_circuit_configuration.png) diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 6e85ea207ef..2aca15e04b9 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -8,10 +8,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w Project webhooks allow you to trigger a URL if for example new code is pushed or a new issue is created. You can configure webhooks to listen for specific events -like pushes, issues or merge requests. GitLab will send a POST request with data +like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. -In most cases, you'll need to set up your own [webhook receiver](#example-webhook-receiver) +In most cases, you need to set up your own [webhook receiver](#example-webhook-receiver) to receive information from GitLab, and send it to another app, according to your needs. We already have a [built-in receiver](slack.md) for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_. @@ -31,8 +31,7 @@ update a backup mirror, or even deploy to your production server. They are available **per project** for GitLab Community Edition, and **per project and per group** for **GitLab Enterprise Edition**. -Navigate to the webhooks page by going to your project's -**Settings ➔ Webhooks**. +Navigate to the webhooks page at your project's **Settings > Webhooks**. NOTE: **Note:** On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. @@ -65,20 +64,20 @@ Starting from GitLab 11.2: ## Webhook endpoint tips -If you are writing your own endpoint (web server) that will receive -GitLab webhooks keep in mind the following things: +If you are writing your own endpoint (web server) to receive +GitLab webhooks, keep in mind the following things: - Your endpoint should send its HTTP response as fast as possible. If you wait too long, GitLab may decide the hook failed and retry it. - Your endpoint should ALWAYS return a valid HTTP response. If you do - not do this then GitLab will think the hook failed and retry it. + not do this then GitLab thinks the hook failed and retries it. Most HTTP libraries take care of this for you automatically but if you are writing a low-level hook this is important to remember. - GitLab ignores the HTTP status code returned by your endpoint. ## Secret token -If you specify a secret token, it will be sent with the hook request in the +If you specify a secret token, it is sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify that the request is legitimate. @@ -110,13 +109,13 @@ Triggered when you push to the repository except when pushing tags. NOTE: **Note:** When more than 20 commits are pushed at once, the `commits` webhook -attribute will only contain the first 20 for performance reasons. Loading +attribute only contains the first 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 will -contain the actual total. +present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. 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 won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +branches, this hook isn't executed. **Request header**: @@ -205,7 +204,8 @@ Triggered when you create (or delete) tags to the repository. NOTE: **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 won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +tags, this hook is not executed. **Request header**: @@ -412,9 +412,9 @@ X-Gitlab-Event: Issue Hook ### Comment events Triggered when a new comment is made on commits, merge requests, issues, and code snippets. -The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The -payload will also include information about the target of the comment. For example, -a comment on an issue will include the specific issue information under the `issue` key. +The note data is stored in `object_attributes` (e.g. `note`, `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: - `commit` @@ -1502,21 +1502,22 @@ its description: ![image](/uploads/$sha/image.png) ``` -It will appear in the webhook body as the below (assuming that GitLab is -installed at `gitlab.example.com`, and the project is at -`example-group/example-project`): +It appears in the webhook body as follows assuming that: + +- GitLab is installed at `gitlab.example.com`. +- The project is at `example-group/example-project`. ```markdown ![image](https://gitlab.example.com/example-group/example-project/uploads/$sha/image.png) ``` -This will not rewrite URLs that already are pointing to HTTP, HTTPS, or -protocol-relative URLs. It will also not rewrite image URLs using advanced +This doesn't rewrite URLs that already are pointing to HTTP, HTTPS, or +protocol-relative URLs. It also doesn't rewrite image URLs using advanced Markdown features, like link labels. ## Testing webhooks -You can trigger the webhook manually. Sample data from the project will be used. +You can trigger the webhook manually. Sample data from the project is used. > For example: for triggering `Push Events` your project should have at least one commit. ![Webhook testing](img/webhook_testing.png) @@ -1536,11 +1537,11 @@ On this page, you can see data that GitLab sends (request headers and body) and From this page, you can repeat delivery with the same data by clicking `Resend Request` button. NOTE: **Note:** -If URL or secret token of the webhook were updated, data will be delivered to the new address. +If URL or secret token of the webhook were updated, data is delivered to the new address. ### Receiving duplicate or multiple webhook requests triggered by one event -When GitLab sends a webhook it expects a response in 10 seconds (set default value). If it does not receive one, it'll retry the webhook. +When GitLab sends a webhook, it expects a response in 10 seconds (set default value). If it does not receive one, it retries the webhook. If the endpoint doesn't send its HTTP response within those 10 seconds, GitLab may decide the hook failed and retry it. If you are receiving multiple requests, you can try increasing the default value to wait for the HTTP response after sending the webhook diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index 1afa78514bd..f9b3c083a54 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -17,14 +17,14 @@ To enable YouTrack integration in a project: 1. Navigate to the project's **Settings > [Integrations](overview.md#accessing-integrations)** page. 1. Click the **YouTrack** service, ensure it's active, and enter the required details on the page as described in the table below. - | Field | Description | - |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| - | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | - | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | + | Field | Description | + |:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | **Project URL** | URL to the project in YouTrack which is being linked to this GitLab project. | + | **Issues URL** | URL to the issue in YouTrack project that is linked to this GitLab project. Note that the **Issues URL** requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. | 1. Click the **Save changes** button. -Once you have configured and enabled YouTrack, you'll see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. +Once you have configured and enabled YouTrack, you see the YouTrack link on the GitLab project pages that takes you to the appropriate YouTrack project. ## Disable the internal issue tracker |