diff options
Diffstat (limited to 'doc/user/project/integrations')
44 files changed, 289 insertions, 699 deletions
diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md new file mode 100644 index 00000000000..b9552fff110 --- /dev/null +++ b/doc/user/project/integrations/asana.md @@ -0,0 +1,44 @@ +--- +stage: Create +group: Ecosystem +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 +--- + +# Asana service **(FREE)** + +This service adds commit messages as comments to Asana tasks. +Once enabled, commit messages are checked for Asana task URLs (for example, +`https://app.asana.com/0/123456/987654`) or task IDs starting with `#` +(for example, `#987654`). Every task ID found gets the commit comment added to it. + +You can also close a task with a message containing: `fix #123456`. +You can use either of these words: + +- `fix` +- `fixed` +- `fixes` +- `fixing` +- `close` +- `closes` +- `closed` +- `closing` + +See also the [Asana service API documentation](../../../api/services.md#asana). + +## Setup + +In Asana, create a Personal Access Token. +[Learn about Personal Access Tokens in Asana](https://developers.asana.com/docs/personal-access-token). + +Complete these steps in GitLab: + +1. Go to the project you want to configure. +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Asana**. +1. Ensure that the **Active** toggle is enabled. +1. Paste the token you generated in Asana. +1. (Optional) To restrict this setting to specific branches, list them in the **Restrict to branch** + field, separated with commas. +1. Select **Save changes** or optionally select **Test settings**. + +<!-- ## Troubleshooting --> diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 3b012ab4430..1eb8a8c60e0 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -4,11 +4,11 @@ group: Ecosystem 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 --- -# Atlassian Bamboo CI Service **(FREE)** +# Atlassian Bamboo Service **(FREE)** GitLab provides integration with Atlassian Bamboo for continuous integration. When configured, pushes to a project trigger a build in Bamboo automatically. -Merge requests also display CI status showing whether the build is pending, +Merge requests also display CI/CD status showing whether the build is pending, failed, or completed successfully. It also provides a link to the Bamboo build page for more information. @@ -20,21 +20,21 @@ need to be configured in a Bamboo build plan before GitLab can integrate. ### Complete these steps in Bamboo -1. Navigate to a Bamboo build plan and choose 'Configure plan' from the 'Actions' +1. Navigate to a Bamboo build plan and choose **Configure plan** from the **Actions** dropdown. -1. Select the 'Triggers' tab. -1. Click 'Add trigger'. -1. Enter a description such as 'GitLab trigger' -1. Choose 'Repository triggers the build when changes are committed' -1. Check one or more repositories checkboxes -1. Enter the GitLab IP address in the 'Trigger IP addresses' box. This is a +1. Select the **Triggers** tab. +1. Click **Add trigger**. +1. Enter a description such as **GitLab trigger**. +1. Choose **Repository triggers the build when changes are committed**. +1. Select the checkbox for one or more repositories. +1. Enter the GitLab IP address in the **Trigger IP addresses** box. This is a list of IP addresses that are allowed to trigger Bamboo builds. 1. Save the trigger. 1. In the left pane, select a build stage. If you have multiple build stages you want to select the last stage that contains the Git checkout task. -1. Select the 'Miscellaneous' tab. -1. Under 'Pattern Match Labeling' put `${bamboo.repository.revision.number}` - in the 'Labels' box. +1. Select the **Miscellaneous** tab. +1. Under **Pattern Match Labeling** put `${bamboo.repository.revision.number}` + in the **Labels** box. 1. Save Bamboo is now ready to accept triggers from GitLab. Next, set up the Bamboo @@ -44,18 +44,18 @@ service in GitLab. 1. Navigate to the project you want to configure to trigger builds. 1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click 'Atlassian Bamboo CI' +1. Click **Atlassian Bamboo**. 1. Ensure that the **Active** toggle is enabled. 1. Enter the base URL of your Bamboo server. `https://bamboo.example.com` 1. Enter the build key from your Bamboo build plan. Build keys are typically made up from the Project Key and Plan Key that are set on project/plan creation and - separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all + separated with a dash (`-`), for example **PROJ-PLAN**. This is a short, all uppercase identifier that is unique. When viewing a plan in Bamboo, the build key is also shown in the browser URL, for example `https://bamboo.example.com/browse/PROJ-PLAN`. 1. If necessary, enter username and password for a Bamboo user that has 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' +1. Save or optionally click **Test Settings**. Please note that **Test Settings** actually triggers a build in Bamboo. ## Troubleshooting @@ -63,7 +63,7 @@ service in GitLab. ### Builds not triggered If builds are not triggered, ensure you entered the right GitLab IP address in -Bamboo under 'Trigger IP addresses'. Also check [service hook logs](overview.md#troubleshooting-integrations) for request failures. +Bamboo under **Trigger IP addresses**. Also check [service hook logs](overview.md#troubleshooting-integrations) for request failures. ### Advanced Atlassian Bamboo features not available in GitLab UI diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index 624c0252f23..2ec657eec22 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -10,7 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. -To send GitLab event notifications to a Discord channel, create a webhook in Discord and configure it in GitLab. +To send GitLab event notifications to a Discord channel, [create a webhook in Discord](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) +and configure it in GitLab. ## Create webhook diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 4970e20974b..3ef4a4e5004 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -18,9 +18,9 @@ The following options are available: - **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`). +- **Send from committer** - Send notifications from the committer's email address if the domain matches the domain used by your GitLab instance (such as `user@gitlab.com`). - **Disable code diffs** - Don't include possibly sensitive code diffs in notification body. | Settings | Notification | | --- | --- | -|  |  | +|  |  | diff --git a/doc/user/project/integrations/github.md b/doc/user/project/integrations/github.md index 1c0309cab87..4f5640d9fff 100644 --- a/doc/user/project/integrations/github.md +++ b/doc/user/project/integrations/github.md @@ -18,38 +18,39 @@ and is automatically configured on [GitHub import](../../../integration/github.m ## Configuration -### Complete these steps on GitHub - This integration requires a [GitHub API token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) -with `repo:status` access granted: +with `repo:status` access granted. + +Complete these steps on GitHub: -1. Go to your "Personal access tokens" page at <https://github.com/settings/tokens> -1. Click "Generate New Token" -1. Ensure that `repo:status` is checked and click "Generate token" -1. Copy the generated token to use on GitLab +1. Go to your **Personal access tokens** page at <https://github.com/settings/tokens>. +1. Select **Generate new token**. +1. Under **Note**, enter a name for the new token. +1. Ensure that `repo:status` is checked and select **Generate token**. +1. Copy the generated token to use in GitLab. -### Complete these steps on GitLab +Complete these steps in GitLab: -1. Navigate to the project you want to configure. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click "GitHub". +1. Go to the project you want to configure. +1. Go to the [Integrations page](overview.md#accessing-integrations) +1. Select **GitHub**. 1. Ensure that the **Active** toggle is enabled. -1. Paste the token you've generated on GitHub -1. Enter the path to your project on GitHub, such as `https://github.com/username/repository` -1. Optionally uncheck **Static status check names** checkbox to disable static status check names. -1. Save or optionally click "Test Settings". +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. Select **Save changes** or optionally select **Test settings**. -Once the integration is configured, see [Pipelines for external pull requests](../../../ci/ci_cd_for_external_repos/#pipelines-for-external-pull-requests) +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 / 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. -With **Static status check names** enabled on the integration page, your -GitLab instance host name is appended to a status check name, -whereas in case of dynamic status check names, a branch name is appended. +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 +GitLab instance host name is appended to a status check name. - +When disabled, it uses dynamic status check names and appends the branch name. diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md index 9c0eb571f66..63772936fd4 100644 --- a/doc/user/project/integrations/hipchat.md +++ b/doc/user/project/integrations/hipchat.md @@ -1,64 +1,7 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'index.md' --- -# Atlassian HipChat (Deprecated) **(FREE)** - -As of [GitLab -13.11](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57434), the -HipChat integration will not send any notifications to HipChat. This -integration is also deprecated. - -GitLab provides a way to send HipChat notifications upon a number of events, -such as when a user pushes code, creates a branch or tag, adds a comment, and -creates a merge request. - -## Setup - -GitLab requires the use of a HipChat v2 API token to work. v1 tokens are -not supported at this time. Note the differences between v1 and v2 tokens: - -HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1 -token is allowed to send messages to *any* room. - -HipChat v2 API has tokens that are can be created using the Integrations tab -in the Group or Room administration page. By design, these are lightweight tokens that -allow GitLab to send messages only to *one* room. - -### Complete these steps in HipChat - -1. Go to: `https://admin.hipchat.com/admin` -1. Click on "Group Admin" -> "Integrations". -1. Find "Build Your Own!" and click "Create". -1. Select the desired room, name the integration "GitLab", and click "Create". -1. In the "Send messages to this room by posting this URL" column, you should - see a URL in the format: - -```plaintext -https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token> -``` - -HipChat is now ready to accept messages from GitLab. Next, set up the HipChat -service in GitLab. - -### Complete these steps in GitLab - -1. Navigate to the project you want to configure for notifications. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) -1. Click "HipChat". -1. Ensure that the **Active** toggle is enabled. -1. Insert the `token` field from the URL into the `Token` field on the Web page. -1. Insert the `room` field from the URL into the `Room` field on the Web page. -1. Save or optionally click "Test Settings". - -## Troubleshooting - -If you do not see notifications, make sure you are using a HipChat v2 API -token, not a v1 token. - -Note that the v2 token is tied to a specific room. If you want to be able to -specify arbitrary rooms, you can create an API token for a specific user in -HipChat under "Account settings" and "API access". Use the `XXX` value under -`auth_token=XXX`. +This document was moved to [another location](index.md). +<!-- This redirect file can be deleted after 2021-06-30. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/img/emails_on_push_service_v13_11.png b/doc/user/project/integrations/img/emails_on_push_service_v13_11.png Binary files differnew file mode 100644 index 00000000000..e895b4b771f --- /dev/null +++ b/doc/user/project/integrations/img/emails_on_push_service_v13_11.png diff --git a/doc/user/project/integrations/img/github_configuration.png b/doc/user/project/integrations/img/github_configuration.png Binary files differdeleted file mode 100644 index 5798b826681..00000000000 --- a/doc/user/project/integrations/img/github_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira/open_jira_issues_list_v13.2.png b/doc/user/project/integrations/img/jira/open_jira_issues_list_v13.2.png Binary files differdeleted file mode 100644 index 0cf58433b25..00000000000 --- a/doc/user/project/integrations/img/jira/open_jira_issues_list_v13.2.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_add_user_to_group.png b/doc/user/project/integrations/img/jira_add_user_to_group.png Binary files differdeleted file mode 100644 index b63a851a987..00000000000 --- a/doc/user/project/integrations/img/jira_add_user_to_group.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_added_user_to_group.png b/doc/user/project/integrations/img/jira_added_user_to_group.png Binary files differdeleted file mode 100644 index f5120a8d42e..00000000000 --- a/doc/user/project/integrations/img/jira_added_user_to_group.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_api_token.png b/doc/user/project/integrations/img/jira_api_token.png Binary files differdeleted file mode 100644 index d9d37713a4d..00000000000 --- a/doc/user/project/integrations/img/jira_api_token.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_api_token_menu.png b/doc/user/project/integrations/img/jira_api_token_menu.png Binary files differdeleted file mode 100644 index a10a59a243d..00000000000 --- a/doc/user/project/integrations/img/jira_api_token_menu.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_create_new_group.png b/doc/user/project/integrations/img/jira_create_new_group.png Binary files differdeleted file mode 100644 index 4ab7a5eae4e..00000000000 --- a/doc/user/project/integrations/img/jira_create_new_group.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_create_new_user.png b/doc/user/project/integrations/img/jira_create_new_user.png Binary files differdeleted file mode 100644 index c74933298e3..00000000000 --- a/doc/user/project/integrations/img/jira_create_new_user.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_group_access.png b/doc/user/project/integrations/img/jira_group_access.png Binary files differdeleted file mode 100644 index e33f2eed242..00000000000 --- a/doc/user/project/integrations/img/jira_group_access.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_issue_reference.png b/doc/user/project/integrations/img/jira_issue_reference.png Binary files differdeleted file mode 100644 index db8bc4f0bb9..00000000000 --- a/doc/user/project/integrations/img/jira_issue_reference.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_merge_request_close.png b/doc/user/project/integrations/img/jira_merge_request_close.png Binary files differdeleted file mode 100644 index 9a176daf5f4..00000000000 --- a/doc/user/project/integrations/img/jira_merge_request_close.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_project_settings.png b/doc/user/project/integrations/img/jira_project_settings.png Binary files differdeleted file mode 100644 index d96002b7db8..00000000000 --- a/doc/user/project/integrations/img/jira_project_settings.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_service_close_issue.png b/doc/user/project/integrations/img/jira_service_close_issue.png Binary files differdeleted file mode 100644 index 73d6498192c..00000000000 --- a/doc/user/project/integrations/img/jira_service_close_issue.png +++ /dev/null diff --git a/doc/user/project/integrations/img/jira_user_management_link.png b/doc/user/project/integrations/img/jira_user_management_link.png Binary files differdeleted file mode 100644 index caecd1d71fc..00000000000 --- a/doc/user/project/integrations/img/jira_user_management_link.png +++ /dev/null diff --git a/doc/user/project/integrations/img/mattermost_configuration_v2.png b/doc/user/project/integrations/img/mattermost_configuration_v2.png Binary files differdeleted file mode 100644 index 0470869c4f7..00000000000 --- a/doc/user/project/integrations/img/mattermost_configuration_v2.png +++ /dev/null diff --git a/doc/user/project/integrations/img/microsoft_teams_configuration.png b/doc/user/project/integrations/img/microsoft_teams_configuration.png Binary files differdeleted file mode 100644 index 22ad28e3f73..00000000000 --- a/doc/user/project/integrations/img/microsoft_teams_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/img/redmine_configuration.png b/doc/user/project/integrations/img/redmine_configuration.png Binary files differdeleted file mode 100644 index eb392b848b5..00000000000 --- a/doc/user/project/integrations/img/redmine_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 5628a9bc5e5..c7772ac2238 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -12,11 +12,14 @@ You can find the available integrations under your project's ## Integrations -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). +Like plugins, integrations allow you to integrate GitLab with other applications, adding additional features. +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) + in GitLab 14.0. ## Project webhooks diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index e75561b3ddb..295300fb55d 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -23,7 +23,7 @@ git clone https://gitlab.com/esr/irker.git Once you have downloaded the code, you can run the Python script named `irkerd`. 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 +messages to an IRC server, 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 diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 0878e1c9386..b91a8a1fb3b 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -1,306 +1,8 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../../integration/jira/index.md' --- -# GitLab Jira integration **(FREE)** +This document was moved to [another location](../../../integration/jira/index.md). -You can use Jira to track work implemented in GitLab. The Jira integration with GitLab makes the -process of working across these systems more efficient. - -The GitLab Jira integration, available in every GitLab project by default, allows you to connect -to any Jira instance, whether on Atlassian cloud or self-managed. - -You can also install the [Jira Development Panel integration](../../../integration/jira_development_panel.md). -For more information about the differences between the two integrations, see -[Jira integrations](jira_integrations.md). - -After you set up this integration, you can cross-reference activity in the GitLab project with any -of your projects in Jira. This includes the ability to close or transition Jira issues when work is -completed in GitLab and: - -- Mention a Jira issue ID in a commit message or MR (merge request) and: - - 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: - - The GitLab 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. -- Run a pipeline on an MR linked to a Jira issue: - - The Jira issue shows the current pipeline status (in the sidebar as "builds"). -- Deploy to an environment from an MR linked to a Jira issue: - - The Jira issue shows the status of the deployment (in the sidebar as "deployments"). -- Create or modify a feature flag that mentions a Jira issue in its description: - - The Jira issue shows the details of the feature-flag (in the sidebar as "feature flags"). -- View a list of Jira issues directly in GitLab. **(PREMIUM)** -- Create a Jira issue from a vulnerability. **(ULTIMATE)** - -Additional features provided by the Jira Development Panel integration include: - -- In a Jira issue, display relevant GitLab information in the [development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/), including related branches, commits, and merge requests. -- Use Jira [Smart Commits](https://confluence.atlassian.com/fisheye/using-smart-commits-960155400.html) in GitLab to add Jira comments, log time spent on the issue, or apply any issue transition. -- Showing pipeline, deployment, and feature flags in Jira issues. - -## Configuration - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Agile Management - GitLab-Jira Basic Integration](https://www.youtube.com/watch?v=fWvwkx5_00E&feature=youtu.be). - -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. For: - -- The [view Jira issues](#view-jira-issues) feature, you must associate a GitLab project with a - specific Jira project. -- Other features, 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. For more information, see the -documentation for: - -- [Project integration management](../../admin_area/settings/project_integration_management.md). -- [Services Templates](services_templates.md). - -To enable the Jira service in GitLab, you must: - -1. Configure the project in Jira. -1. Enter the correct values in GitLab. - -### Configure Jira - -The process for configuring Jira depends on whether you host Jira on your own server or on -[Atlassian cloud](https://www.atlassian.com/cloud). - -#### Jira Server - -Jira Server supports basic authentication. When connecting, a **username and password** are -required. Connecting to Jira Server via CAS is not possible. For more information, see -[set up a user in Jira Server](jira_server_configuration.md). - -#### Jira on Atlassian cloud - -Jira on Atlassian cloud supports authentication through an API token. When connecting to Jira on -Atlassian cloud, an **email and API token** are required. For more information, see -[set up a user in Jira on Atlassian cloud](jira_cloud_configuration.md). - -### Configure GitLab - -> **Notes:** -> -> - The supported Jira versions are `v6.x`, `v7.x`, and `v8.x`. -> - 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`. - -To enable the Jira integration in a project: - -1. Go to the project's [Integrations page](overview.md#accessing-integrations) and select the - **Jira** service. - -1. Select **Enable integration**. - -1. Select **Trigger** actions. - This determines whether a mention of a Jira issue in GitLab commits, merge requests, or both, - should link the Jira issue back to that source commit/MR and transition the Jira issue, if - indicated. - -1. To include a comment on the Jira issue when the above reference is made in GitLab, select - **Enable comments**. - - 1. Select the **Comment detail**: **Standard** or **All details**. - -1. 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. For example, `https://jira.example.com`. | - | `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 on Atlassian cloud**. | - | `Username or Email` | Created in [configure Jira](#configure-jira) step. Use `username` for **Jira Server** or `email` for **Jira on Atlassian cloud**. | - | `Password/API token` | Created in [configure Jira](#configure-jira) step. Use `password` for **Jira Server** or `API token` for **Jira on Atlassian cloud**. | - | `Jira workflow transition IDs` | Required for closing Jira issues via commits or merge requests. These are the IDs of transitions in Jira that move issues to a particular 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. In GitLab 13.6 and earlier, field was called `Transition ID`. | - -1. To enable users to view Jira issues inside the GitLab project, select **Enable Jira issues** and - enter a Jira project key. **(PREMIUM)** - - You can only display issues from a single Jira project within a given GitLab project. - - WARNING: - 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. - -1. To enable creation of issues for vulnerabilities, select **Enable Jira issues creation from vulnerabilities**. - - 1. Select the **Jira issue type**. If the dropdown is empty, select refresh (**{retry}**) and try again. - -1. To verify the Jira connection is working, select **Test settings**. - -1. Select **Save changes**. - -Your GitLab project can now interact with all Jira projects in your instance and the project now -displays a Jira link that opens the Jira project. - -#### Obtaining a transition ID - -In the most recent Jira user interface, you can no longer see transition IDs in the workflow -administration UI. You can get the ID you need in either of the following ways: - -1. By using the API, with a request like `https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-123/transitions` - using an issue that is in the appropriate "open" state -1. By mousing over the link for the transition you want and looking for the - "action" parameter in the URL - -Note that the transition ID may vary between workflows (for example, bug vs. story), -even if the status you are changing to is the same. - -#### Disabling comments on Jira issues - -You can continue to have GitLab cross-link a source commit/MR with a Jira issue while disabling the comment added to the issue. - -See the [Configure GitLab](#configure-gitlab) section and uncheck the **Enable comments** setting. - -## Jira issues - -By now you should have [configured Jira](#configure-jira) and enabled the -[Jira service in GitLab](#configure-gitlab). If everything is set up correctly -you should be able to reference and close Jira issues by just mentioning their -ID in GitLab commits and merge requests. - -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 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, `PROJECT-7` for example, adds a comment in Jira issue in the -format: - -```plaintext -USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: -ENTITY_TITLE -``` - -- `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. -- `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where Jira issue was mentioned. -- `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. -- `PROJECT_NAME` GitLab project name. -- `ENTITY_TITLE` Merge request title or commit message first line. - - - -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" -``` - -### Close Jira issues - -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 -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 -the same goal: - -- `Resolves PROJECT-1` -- `Closes PROJECT-1` -- `Fixes PROJECT-1` - -where `PROJECT-1` is the ID of the Jira issue. - -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: - -1. For the project named `PROJECT` in Jira, we implemented a new feature - and created a merge request in GitLab. -1. This feature was requested in Jira issue `PROJECT-7` and the merge request - 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 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 -issue look like. - - - -Once this merge request is merged, the Jira issue is automatically closed -with a link to the commit that resolved the issue. - - - -### View Jira issues **(PREMIUM)** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3622) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -You can browse and search issues from a selected Jira project directly in GitLab. This requires [configuration](#configure-gitlab) in GitLab by an administrator. - - - -From the **Jira Issues** menu, click **Issues List**. The issue list defaults to sort by **Created date**, with the newest issues listed at the top. You can change this to **Last updated**. - -Issues are grouped into tabs based on their [Jira status](https://confluence.atlassian.com/adminjiraserver070/defining-status-field-values-749382903.html). - -- The **Open** tab displays all issues with a Jira status in any category other than Done. -- The **Closed** tab displays all issues with a Jira status categorized as Done. -- The **All** tab displays all issues of any status. - -Click an issue title to open its original Jira issue page for full details. - -#### Search and filter the issues list - -To refine the list of issues, use the search bar to search for any text -contained in an issue summary (title) or description. - -You can also filter by labels, status, reporter, and assignee using URL parameters. -Enhancements to be able to use these through the user interface are [planned](https://gitlab.com/groups/gitlab-org/-/epics/3622). - -- To filter issues by `labels`, specify one or more labels as part of the `labels[]` -parameter in the URL. When using multiple labels, only issues that contain all specified -labels are listed. `/-/integrations/jira/issues?labels[]=backend&labels[]=feature&labels[]=QA` - -- To filter issues by `status`, specify the `status` parameter in the URL. -`/-/integrations/jira/issues?status=In Progress` - -- To filter issues by `reporter`, specify a reporter's Jira display name for the -`author_username` parameter in the URL. `/-/integrations/jira/issues?author_username=John Smith` - -- To filter issues by `assignee`, specify their Jira display name for the -`assignee_username` parameter in the URL. `/-/integrations/jira/issues?assignee_username=John Smith` - -## Troubleshooting - -If these features do not work as expected, it is likely due to a problem with the way the integration settings were configured. - -### GitLab is unable to comment on a Jira issue - -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 do not work if the GitLab issue tracker is disabled. - -### GitLab is unable to close a Jira issue - -Make sure the `Transition ID` you set within the Jira settings matches the one -your project needs to close an issue. - -Make sure that the Jira issue is not already marked as resolved; that is, -the Jira issue resolution field is not set. (It should not be struck through in -Jira lists.) - -### CAPTCHA - -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 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. +<!-- This redirect file can be deleted after 2021-07-07. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 8e25af3f884..b3091275835 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -1,27 +1,8 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../../integration/jira/jira_cloud_configuration.md' --- -# Create an API token in Jira on Atlassian cloud **(FREE)** +This document was moved to [another location](../../../integration/jira/jira_cloud_configuration.md). -For [integrations with Jira](jira.md), an API token is needed when integrating with Jira -on Atlassian cloud. To create an API token: - -1. Log in to [`id.atlassian.com`](https://id.atlassian.com/manage-profile/security/api-tokens) with your email address. - - NOTE: - It is important that the user associated with this email address has *write* access - to projects in Jira. - -1. Click **Create API token**. - -  - -1. Click **Copy**, or click **View** and write down the new API token. It is required when [configuring GitLab](jira.md#configure-gitlab). - -  - -The Jira configuration is complete. You need the newly created token, and the associated email -address, when [configuring GitLab](jira.md#configure-gitlab). +<!-- This redirect file can be deleted after <2021-06-18>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/jira_integrations.md b/doc/user/project/integrations/jira_integrations.md index 6b938238320..485b48df01b 100644 --- a/doc/user/project/integrations/jira_integrations.md +++ b/doc/user/project/integrations/jira_integrations.md @@ -1,56 +1,8 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../../integration/jira/index.md' --- -# Jira integrations **(FREE)** +This document was moved to [another location](../../../integration/jira/index.md). -GitLab can be integrated with [Jira](https://www.atlassian.com/software/jira). - -[Issues](../issues/index.md) are a tool for discussing ideas, and planning and tracking work. -However, your organization may already use Jira for these purposes, with extensive, established data -and business processes they rely on. - -Although you can [migrate](../../../user/project/import/jira.md) your Jira issues and work -exclusively in GitLab, you can also continue to use Jira by using the GitLab Jira integrations. - -## Integration types - -There are two different Jira integrations that allow different types of cross-referencing between -GitLab activity and Jira issues, with additional features: - -- [Jira integration](jira.md), built in to GitLab. In a given GitLab project, it can be configured - to connect to any Jira instance, either hosted by you or hosted in - [Atlassian cloud](https://www.atlassian.com/cloud). -- [Jira development panel integration](../../../integration/jira_development_panel.md). Connects all - GitLab projects under a specified group or personal namespace. - -Jira development panel integration configuration depends on whether: - -- You're using GitLab.com or a self-managed GitLab instance. -- You're using Jira on [Atlassian cloud](https://www.atlassian.com/cloud) or on your own server. - -| You use Jira on: | For the Jira development panel integration, GitLab.com customers need: | For the Jira development panel integration, GitLab self-managed customers need: | -|:-------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Atlassian cloud | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview) application installed from the [Atlassian Marketplace](https://marketplace.atlassian.com). | The [GitLab.com for Jira Cloud](https://marketplace.atlassian.com/apps/1221011/gitlab-com-for-jira-cloud?hosting=cloud&tab=overview), using a workaround process. See a [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/268278) for more information. | -| Your own server | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | The [Jira DVCS connector](../../../integration/jira_development_panel.md). | - -NOTE: -DVCS means distributed version control system. - -## Feature comparison - -The integration to use depends on the capabilities your require. You can install both at the same -time. - -| Capability | Jira integration | Jira Development Panel integration | -|:----------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------| -| Mention of Jira issue ID in GitLab is automatically linked to that issue | Yes | No | -| Mention of Jira issue ID in GitLab issue/MR is reflected in the Jira issue | Yes, as a Jira comment with the GitLab issue/MR title and a link back to it. Its first mention also adds the GitLab page to the Jira issue under “Web links”. | Yes, in the issue’s Development panel | -| Mention of Jira issue ID in GitLab commit message is reflected in the issue | Yes. The entire commit message is added to the Jira issue as a comment and under “Web links”, each with a link back to the commit in GitLab. | Yes, in the issue’s Development panel and optionally with a custom comment on the Jira issue using Jira Smart Commits. | -| Mention of Jira issue ID in GitLab branch names is reflected in Jira issue | No | Yes, in the issue’s Development panel | -| Record Jira time tracking information against an issue | No | Yes. Time can be specified via Jira Smart Commits. | -| Transition or close a Jira issue with a Git commit or merge request | Yes. Only a single transition type, typically configured to close the issue by setting it to Done. | Yes. Transition to any state using Jira Smart Commits. | -| Display a list of Jira issues | Yes **(PREMIUM)** | No | -| Create a Jira issue from a vulnerability or finding **(ULTIMATE)** | Yes | No | +<!-- This redirect file can be deleted after <2021-07-13>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index b1ab2076dc0..191b8f207a1 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,68 +1,8 @@ --- -stage: Create -group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: '../../../integration/jira/jira_server_configuration.md' --- -# Create Jira Server username and password **(FREE)** +This document was moved to [another location](../../../integration/jira/jira_server_configuration.md). -For [integrations with Jira](jira.md), you must create a user account in Jira to have access to -all projects that need to integrate with GitLab. - -The Jira user account created for the integration must have write access to -your Jira projects. - -As an example, the following process creates a user named `gitlab` and that's a -member of a new group named `gitlab-developers`: - -1. Sign in to your Jira instance as an administrator, and - then go to the gear icon and select **User Management**. - -  - -1. Create a new user account (for example, `gitlab`) with write access to - projects in Jira. Enter the user account's name and a valid e-mail address, - because Jira sends a verification email to set up the password. - - Jira creates the username by using the email prefix. You can change the - username later, if needed. The GitLab integration doesn't 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. - -  - -1. From the sidebar, select **Groups**. - -  - -1. In the **Add group** section, enter a **Name** for the group (for example, - `gitlab-developers`), and then select **Add group**. - -1. Add the `gitlab` user to the `gitlab-developers` group by selecting **Edit members**. - The `gitlab-developers` group should be listed in the leftmost box as a - selected group. In the **Add members to selected group(s)** area, enter `gitlab`. - -  - - Select **Add selected users**, and `gitlab` should appear in the **Group member(s)** - area. This membership is saved automatically. - -  - -1. To give the newly-created group 'write' access, you must create a permission - scheme. To do this, in the admin menu, go to the gear icon and select **Issues**. - -1. From the sidebar, select **Permission Schemes**. - -1. Select **Add Permission Scheme**, enter a **Name** and (optionally) a - **Description**, and then select **Add**. - -1. In the permissions scheme list, locate your new permissions scheme, and - select **Permissions**. Next to **Administer Projects**, select **Edit**. In - the **Group** list, select `gitlab-developers`. - -  - -The Jira configuration is complete. Write down the new Jira username and its -password, as you need them when [configuring GitLab](jira.md#configure-gitlab). +<!-- This redirect file can be deleted after <2021-06-18>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 6a93fc0fb06..0a32119d572 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,18 +4,23 @@ group: Ecosystem 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 --- -# Mattermost Notifications Service **(FREE)** +# Mattermost notifications service **(FREE)** -The Mattermost Notifications Service allows your GitLab project to send events (e.g., `issue created`) to your existing Mattermost team as notifications. This requires configurations in both Mattermost and GitLab. +Use the Mattermost notifications service to send notifications for GitLab events +(for example, `issue created`) to Mattermost. You must configure both [Mattermost](#configure-mattermost-to-receive-gitlab-notifications) +and [GitLab](#configure-gitlab-to-send-notifications-to-mattermost). -You can also use Mattermost slash commands to control GitLab inside Mattermost. This is the separately configured [Mattermost slash commands](mattermost_slash_commands.md). +You can also use [Mattermost slash commands](mattermost_slash_commands.md) to control +GitLab inside Mattermost. -## On Mattermost +## Configure Mattermost to receive GitLab notifications -To enable Mattermost integration you must create an incoming webhook integration: +To use the Mattermost integration you must create an incoming webhook integration +in Mattermost: 1. Sign in to your Mattermost instance. -1. Visit incoming webhooks, that is something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. +1. [Enable incoming webhooks](https://docs.mattermost.com/developer/webhooks-incoming.html#enabling-incoming-webhooks). +1. [Add an incoming webhook](https://docs.mattermost.com/developer/webhooks-incoming.html#creating-integrations-using-incoming-webhooks). 1. Choose a display name, description and channel, those can be overridden on GitLab. 1. Save it and copy the **Webhook URL** because we need this later for GitLab. @@ -29,36 +34,24 @@ to enable it on: Display name override is not enabled by default, you need to ask your administrator to enable it on that same section. -## On GitLab +## Configure GitLab to send notifications to Mattermost -After you set up Mattermost, it's time to set up GitLab. +After the Mattermost instance has an incoming webhook set up, you can set up GitLab +to send the notifications. Navigate to the [Integrations page](overview.md#accessing-integrations) -and select the **Mattermost notifications** service to configure it. -There, you see a checkbox with the following events that can be triggered: +and select the **Mattermost notifications** service. Select the GitLab events +you want to generate notifications for. -- Push -- Issue -- Confidential issue -- Merge request -- Note -- Confidential note -- Tag push -- Pipeline -- Wiki page -- Deployment +For each event you select, input the Mattermost channel you want to receive the +notification. You do not need to add the hash sign (`#`). -Below each of these event checkboxes, you have an input field to enter -which Mattermost channel you want to send that event message. Enter your preferred channel handle (the hash sign `#` is optional). - -At the end, fill in your Mattermost details: +Then fill in the integration configuration: | Field | Description | | ----- | ----------- | -| **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. | -| **Branches to be notified** | Select which types of branches to send notifications for. | -| **Labels to be notified** | Optional labels that the issue or merge request must have in order to trigger a notification. Leave blank to get all notifications. | - - +| **Webhook** | The incoming webhook URL on Mattermost, similar to: `http://mattermost.example/hooks/5xo…`. | +| **Username** | (Optional) The username to show on messages sent to Mattermost. Fill this in to change the username of the bot. | +| **Notify only broken pipelines** | If you enable the **Pipeline** event and you want to be notified about failed pipelines only. | +| **Branches to be notified** | Select which branches to send notifications for. | +| **Labels to be notified** | (Optional) Labels that the issue or merge request must have to trigger a notification. Leave blank to get notifications for all issues and merge requests. | diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index 41e0938fc3b..795ead573f2 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -6,49 +6,55 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Microsoft Teams service **(FREE)** -## On Microsoft Teams +You can integrate Microsoft Teams with GitLab, and display notifications about GitLab projects +in Microsoft Teams. To integrate the services, you must: -To enable Microsoft Teams integration you must create an incoming webhook integration on Microsoft -Teams by following the steps below: +1. [Configure Microsoft Teams](#configure-microsoft-teams) to enable a webhook + to listen for changes. +1. [Configure your GitLab project](#configure-your-gitlab-project) to push notifications + to the Microsoft Teams webhook. -1. Search for "incoming webhook" on the search bar in Microsoft Teams and select the - **Incoming Webhook** item. +## Configure Microsoft Teams + +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. Click the **Add to a team** button. +1. Select **Add to a team**. 1. Select the team and channel you want to add the integration to. 1. Add a name for the webhook. The name is displayed next to every message that comes in through the webhook. -1. Copy the webhook URL for the next steps. - -Learn more about -[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). - -## On GitLab - -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 see a checkbox with the following events that can be triggered: - -- Push -- Issue -- Confidential issue -- Merge request -- Note -- Tag push -- Pipeline -- Wiki page - -At the end fill in your Microsoft Teams details: - -| Field | Description | -| ----- | ----------- | -| **Webhook** | The incoming webhook URL which you have to set up on Microsoft Teams. | -| **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | - -After you are all done, click **Save changes** for the changes to take effect. - - +1. Copy the webhook URL, as you need it to configure GitLab. + +## Configure your GitLab project + +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 check box next to each **Trigger** to enable: + - Push + - Issue + - Confidential issue + - Merge request + - 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. + - 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 + **Notify only broken pipelines** check box to push notifications only when pipelines break. +1. Select the branches you want to send notifications for. +1. Click **Save changes**. + +## Resources + +- [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 f6590b6ba2f..ef1f492bfbf 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -24,45 +24,43 @@ want to configure. Click on the service links to see further configuration instructions and details. -| Service | Description | Service Hooks | -| ------- | ----------- | ------------- | -| Asana | Asana - Teamwork without email | No | -| Assembla | Project Management Software (Source Commits Endpoint) | No | -| [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server | Yes | -| Buildkite | Continuous integration and deployments | Yes | -| [Bugzilla](bugzilla.md) | Bugzilla issue tracker | No | -| Campfire | Simple web-based real-time group chat | No | -| [Confluence](../../../api/services.md#confluence-service) | Replaces the link to the internal wiki with a link to a Confluence Cloud Workspace | No | -| Custom Issue Tracker | Custom issue tracker | No | -| [Discord Notifications](discord_notifications.md) | Receive event notifications in Discord | No | -| Drone CI | Continuous Integration platform built on Docker, written in Go | Yes | -| [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | No | -| External Wiki | Replaces the link to the internal wiki with a link to an external wiki | No | -| Flowdock | Flowdock is a collaboration web app for technical teams | No | -| [Generic alerts](../../../operations/incident_management/integrations.md) **(ULTIMATE)** | Receive alerts on GitLab from any source | No | -| [GitHub](github.md) **(PREMIUM)** | Sends pipeline notifications to GitHub | No | -| [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | No | -| [HipChat](hipchat.md) | Private group chat and IM | No | -| [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | No | -| [Jira](jira.md) | Jira issue tracker | No | -| [Jenkins](../../../integration/jenkins.md) **(STARTER)** | An extendable open source continuous integration server | Yes | -| JetBrains TeamCity CI | A continuous integration and build server | Yes | -| [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | No | -| [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | No | -| [Microsoft teams](microsoft_teams.md) | Receive notifications for actions that happen on GitLab into a room on Microsoft Teams using Office 365 Connectors | No | -| Packagist | Update your projects on Packagist, the main Composer repository | Yes | -| Pipelines emails | Email the pipeline status to a list of recipients | No | -| [Slack Notifications](slack.md) | Send GitLab events (for example, an issue was created) to Slack as notifications | No | -| [Slack slash commands](slack_slash_commands.md) **(FREE SELF)** | Use slash commands in Slack to control GitLab | No | -| [GitLab Slack application](gitlab_slack_application.md) **(FREE SAAS)** | Use Slack's official application | No | -| PivotalTracker | Project Management Software (Source Commits Endpoint) | No | -| [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | No | -| Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | No | -| [Redmine](redmine.md) | Redmine issue tracker | No | -| [EWM](ewm.md) | EWM work item tracker | No | -| [Unify Circuit](unify_circuit.md) | Receive events notifications in Unify Circuit | No | -| [Webex Teams](webex_teams.md) | Receive events notifications in Webex Teams | No | -| [YouTrack](youtrack.md) | YouTrack issue tracker | No | +| Service | Description | Service hooks | +| --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | +| [Asana](asana.md) | Add commit messages as comments to Asana tasks. | **{dotted-circle}** No | +| Assembla | Manage projects. | **{dotted-circle}** No | +| [Atlassian Bamboo CI](bamboo.md) | Run CI/CD pipelines with Atlassian Bamboo. | **{check-circle}** Yes | +| [Bugzilla](bugzilla.md) | Use Bugzilla as the issue tracker. | **{dotted-circle}** No | +| Buildkite | Run CI/CD pipelines with Buildkite. | **{check-circle}** Yes | +| Campfire | Connect to chat. | **{dotted-circle}** No | +| [Confluence Workspace](../../../api/services.md#confluence-service) | Replace the link to the internal wiki with a link to a Confluence Cloud Workspace. | **{dotted-circle}** No | +| [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | **{dotted-circle}** No | +| [Discord Notifications](discord_notifications.md) | Send notifications about project events to a Discord channel. | **{dotted-circle}** No | +| Drone CI | Run CI/CD pipelines with Drone. | **{check-circle}** Yes | +| [Emails on push](emails_on_push.md) | Send commits and diff of each push by email. | **{dotted-circle}** No | +| [EWM](ewm.md) | Use IBM Engineering Workflow Management as the issue tracker. | **{dotted-circle}** No | +| [External wiki](../wiki/index.md#link-an-external-wiki) | Link an external wiki. | **{dotted-circle}** No | +| Flowdock | Use Flowdock with GitLab. | **{dotted-circle}** No | +| [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | +| [Hangouts Chat](hangouts_chat.md) | Receive events notifications. | **{dotted-circle}** No | +| [Irker (IRC gateway)](irker.md) | Send IRC messages. | **{dotted-circle}** No | +| [Jenkins](../../../integration/jenkins.md) | Run CI/CD pipelines with Jenkins. | **{check-circle}** Yes | +| JetBrains TeamCity CI | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | +| [Jira](jira.md) | Use Jira as the issue tracker. | **{dotted-circle}** No | +| [Mattermost notifications](mattermost.md) | Send notifications about project events to Mattermost channels. | **{dotted-circle}** No | +| [Mattermost slash commands](mattermost_slash_commands.md) | Perform common tasks with slash commands. | **{dotted-circle}** No | +| [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications. | **{dotted-circle}** No | +| Packagist | Update your projects. | **{check-circle}** Yes | +| Pipelines emails | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | +| PivotalTracker | Use PivotalTracker as the issue tracker. | **{dotted-circle}** No | +| [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | +| Pushover | Get real-time notifications on your device. | **{dotted-circle}** No | +| [Redmine](redmine.md) | Use Redmine as the issue tracker. | **{dotted-circle}** No | +| [Slack application](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | +| [Slack notifications](slack.md) | Send notifications about project events to Slack. | **{dotted-circle}** No | +| [Slack slash commands](slack_slash_commands.md) | Enable slash commands in workspace. | **{dotted-circle}** No | +| [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 | ## Push hooks limit @@ -74,13 +72,6 @@ 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). -## Service templates - -Service templates are a way to set predefined values for a project integration across -all new projects on the instance. - -Read more about [Service templates](services_templates.md). - ## Project integration management Project integration management lets you control integration settings across all projects @@ -89,6 +80,19 @@ instance configuration or provide custom settings. Read more about [Project integration management](../../admin_area/settings/project_integration_management.md). +### Service templates + +[Service templates](services_templates.md) were a way to set predefined values for +a project integration across all new projects on the instance. They are deprecated and +[scheduled to be removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) +in GitLab 14.0. + +GitLab recommends you use [project integration management](../../admin_area/settings/project_integration_management.md) +instead of service templates. GitLab versions 13.3 and later provide +[instance-level integrations](../../admin_area/settings/project_integration_management.md#project-integration-management) +you can use. +instead. + ## Troubleshooting integrations Some integrations use service hooks for integration with external applications. To confirm which ones use service hooks, see the [integrations listing](#integrations-listing) above. GitLab stores details of service hook requests made within the last 2 days. To view details of the requests, go to that integration's configuration page. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index c307fd8d628..4922c8d9b62 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor 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 --- @@ -31,6 +31,10 @@ Once enabled, GitLab detects metrics from known services in the > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/28916) in GitLab 10.5. +**Deprecated:** Managed Prometheus on Kubernetes is deprecated, and +scheduled for removal in [GitLab +14.0](https://gitlab.com/groups/gitlab-org/-/epics/4280). + GitLab can seamlessly deploy and manage Prometheus on a [connected Kubernetes cluster](../clusters/index.md), to help you monitor your apps. diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index 04abb922175..0eaa9cae7c0 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor 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 --- diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 290313ac1af..11b74c35a74 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor 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 --- diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 998300e255f..584c0898fec 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor 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 --- diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 2a6bc810f71..e14c1c0f6fd 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor 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 --- diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index dcaef1e2ae6..3f888a89b1b 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor 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 --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index f7e6b6e76d6..8846aadd420 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor 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 --- diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 0c86c4921b3..4752fec976c 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -1,6 +1,6 @@ --- stage: Monitor -group: Health +group: Monitor 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 --- diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 256ffe84ee2..77e6eb75b9f 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -4,37 +4,52 @@ group: Ecosystem 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 --- -# Redmine Service **(FREE)** +# Redmine service **(FREE)** -1. To enable the Redmine integration in a project, navigate to the - [Integrations page](overview.md#accessing-integrations), click - the **Redmine** service, and fill in the required details on the page as described - in the table below. +Use [Redmine](https://www.redmine.org/) as the issue tracker. - | Field | Description | - | ----- | ----------- | - | `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 is planned be removed in a future release.** | +To enable the Redmine integration in a 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. +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Redmine**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: - As an example, below is a configuration for a project named `gitlab-ci`. + - **Project URL**: The URL to the Redmine project to link to this GitLab project. + - **Issue URL**: The URL to the Redmine project issue to link to this GitLab project. + The URL must contain `:id`. GitLab replaces this ID with the issue number. + - **New issue URL**: The URL to use to create a new issue in the Redmine project linked to + this GitLab project. + <!-- 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.** + For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). -  +1. Select **Save changes** or optionally select **Test settings**. -1. To disable the internal issue tracking system in a project, navigate to the General page, expand the [permissions](../settings/index.md#sharing-and-permissions) section and switch the **Issues** toggle to disabled. +After you have configured and enabled Redmine, you see the Redmine link on the GitLab project pages, +which takes you to your Redmine project. -## Referencing issues in Redmine +For example, this is a configuration for a project named `gitlab-ci`: -Issues in Redmine can be referenced in two alternative ways: +- Project URL: `https://redmine.example.com/projects/gitlab-ci` +- Issue URL: `https://redmine.example.com/issues/:id` +- New issue URL: `https://redmine.example.com/projects/gitlab-ci/issues/new` -- `#<ID>` where `<ID>` is a number (example `#143`). -- `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is - then followed by capital letters, numbers or underscores, and `<ID>` is - a number (example `API_32-143`). +You can also disable [GitLab internal issue tracking](../issues/index.md) in this project. +Learn more about the steps and consequences of disabling GitLab issues in +[Sharing and permissions](../settings/index.md#sharing-and-permissions). -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. +## Reference Redmine issues in GitLab -Please note that `<PROJECT>` part is ignored and links always point to the -address specified in `issues_url`. +You can reference your Redmine issues using: + +- `#<ID>`, where `<ID>` is a number (example `#143`). +- `<PROJECT>-<ID>`, for example `API_32-143`, where: + - `<PROJECT>` starts with a capital letter, followed by capital letters, numbers, or underscores. + - `<ID>` is a number. + +In links, the `<PROJECT>` part is ignored, and they always point to the address specified in **Issue URL**. + +We suggest using the longer format (`<PROJECT>-<ID>`) 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. diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index 66810d8a01b..93ce74eb735 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -36,10 +36,11 @@ does not provide central administration of integration settings. ## Central administration of project integrations A new set of features is being introduced in GitLab to provide more control over -how integrations are configured at the instance, group, and project level. +how integrations are configured at the instance, group, and project level. For +more information, read more about: -[Read more about setting up project integration management](../../admin_area/settings/project_integration_management.md) -(introduced in GitLab 13.3) and [our plans for managing integrations](https://gitlab.com/groups/gitlab-org/-/epics/2137). +- [Setting up project integration management](../../admin_area/settings/project_integration_management.md) (introduced in GitLab 13.3) +- [Our plans for managing integrations](https://gitlab.com/groups/gitlab-org/-/epics/2137). ## Enable a service template diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index bf289c9707c..56a339e02d2 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1297,6 +1297,7 @@ X-Gitlab-Event: Job Hook "build_name": "test", "build_stage": "test", "build_status": "created", + "build_created_at": "2021-02-23T02:41:37.886Z", "build_started_at": null, "build_finished_at": null, "build_duration": null, @@ -1310,7 +1311,6 @@ X-Gitlab-Event: Job Hook "name": "User", "email": "user@gitlab.com", "avatar_url": "http://www.gravatar.com/avatar/e32bd13e2add097461cb96824b7a829c?s=80\u0026d=identicon", - "email": "admin@example.com" }, "commit": { "id": 2366, |
