diff options
Diffstat (limited to 'doc/user/project/integrations')
28 files changed, 171 insertions, 114 deletions
diff --git a/doc/user/project/integrations/asana.md b/doc/user/project/integrations/asana.md index b4d7790df1d..a10e261f10e 100644 --- a/doc/user/project/integrations/asana.md +++ b/doc/user/project/integrations/asana.md @@ -32,8 +32,8 @@ In Asana, create a 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. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Asana**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Asana. diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index a54a3adc408..4a9a8d62098 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -14,7 +14,8 @@ You can configure Bugzilla as an To enable the Bugzilla integration in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Bugzilla**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md index ad7719f0e5b..b7e25b815fc 100644 --- a/doc/user/project/integrations/discord_notifications.md +++ b/doc/user/project/integrations/discord_notifications.md @@ -26,8 +26,9 @@ and configure it in GitLab. With the webhook URL created in the Discord channel, you can set up the Discord Notifications service in GitLab. -1. Navigate to the [Integrations page](overview.md#accessing-integrations) in your project's settings. That is, **Project > Settings > Integrations**. -1. Select the **Discord Notifications** integration to configure it. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Discord Notifications**. 1. Ensure that the **Active** toggle is enabled. 1. Check the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. 1. Paste the webhook URL that you copied from the create Discord webhook step. diff --git a/doc/user/project/integrations/emails_on_push.md b/doc/user/project/integrations/emails_on_push.md index 33c197b962e..c1c48c7fb12 100644 --- a/doc/user/project/integrations/emails_on_push.md +++ b/doc/user/project/integrations/emails_on_push.md @@ -9,17 +9,18 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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) -select **Emails on push** service to activate and configure it. +To enable emails on push: -In the _Recipients_ area, provide a list of emails separated by spaces or newlines. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Emails on push**. +1. In the **Recipients** section, provide a list of emails separated by spaces or newlines. +1. Configure the following options: -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 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. + - **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 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/ewm.md b/doc/user/project/integrations/ewm.md index bc9b2d59db3..b02f1a06e96 100644 --- a/doc/user/project/integrations/ewm.md +++ b/doc/user/project/integrations/ewm.md @@ -14,7 +14,8 @@ This IBM product was [formerly named Rational Team Concert](https://jazz.net/blo To enable the EWM integration, in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **EWM**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 7e8de776619..2dae02dc093 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -25,8 +25,6 @@ the [Slack App Directory](https://slack.com/apps). 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. - - ## Configuration Alternatively, you can configure the Slack application with a project's diff --git a/doc/user/project/integrations/harbor.md b/doc/user/project/integrations/harbor.md index d66e2222538..2a1b12057aa 100644 --- a/doc/user/project/integrations/harbor.md +++ b/doc/user/project/integrations/harbor.md @@ -6,6 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Harbor container registry integration **(FREE)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80999) in GitLab 14.9. + Use Harbor as the container registry for your GitLab project. [Harbor](https://goharbor.io/) is an open source registry that can help you manage artifacts across cloud native compute platforms, like Kubernetes and Docker. @@ -43,7 +45,7 @@ After the Harbor integration is activated: ## Secure your requests to the Harbor APIs For each API request through the Harbor integration, the credentials for your connection to the Harbor API use -the `username:password` combination. The following are suggestions for safe use: +the `username:password` combination. The following are suggestions for safe use: - Use TLS on the Harbor APIs you connect to. - Follow the principle of least privilege (for access on Harbor) with your credentials. diff --git a/doc/user/project/integrations/img/failed_badges.png b/doc/user/project/integrations/img/failed_badges.png Binary files differindex d44415a8687..5a1f481e54c 100644 --- a/doc/user/project/integrations/img/failed_badges.png +++ b/doc/user/project/integrations/img/failed_badges.png diff --git a/doc/user/project/integrations/img/failed_banner.png b/doc/user/project/integrations/img/failed_banner.png Binary files differindex ba40c1301d6..4384ce07873 100644 --- a/doc/user/project/integrations/img/failed_banner.png +++ b/doc/user/project/integrations/img/failed_banner.png diff --git a/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png b/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png Binary files differdeleted file mode 100644 index 57cd35c9f5d..00000000000 --- a/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png +++ /dev/null diff --git a/doc/user/project/integrations/irker.md b/doc/user/project/integrations/irker.md index 279b139bacd..b2c2aea2c2b 100644 --- a/doc/user/project/integrations/irker.md +++ b/doc/user/project/integrations/irker.md @@ -39,9 +39,8 @@ network. For more details, read ## Complete these steps in GitLab -1. On the top bar, select **Menu > Projects** and find the project you want to - configure for notifications. -1. Navigate to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **irker (IRC gateway)**. 1. Ensure that the **Active** toggle is enabled. 1. Optional. Under **Server host**, enter the server host address where `irkerd` runs. If empty, diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index f3f8d900e12..7dd4c1d1a8b 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -37,27 +37,25 @@ Display name override is not enabled by default, you need to ask your administra ## Configure GitLab to send notifications to Mattermost 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. Select the GitLab events -you want to generate notifications for. - -For each event you select, input the Mattermost channel you want to receive the -notification. You do not need to add the hash sign (`#`). - -Then fill in the integration configuration: - -- **Webhook**: The incoming webhook URL on Mattermost, similar to - `http://mattermost.example/hooks/5xo…`. -- **Username**: Optional. The username shown in messages sent to Mattermost. - To change the bot's username, provide a value. -- **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want - notifications about failed pipelines only. -- **Branches for which notifications are to be sent**: The branches to send notifications for. -- **Labels to be notified**: Optional. Labels required for the issue or merge request - to trigger a notification. Leave blank to notify for all issues and merge requests. -- **Labels to be notified behavior**: When you use the **Labels to be notified** filter, - messages are sent when an issue or merge request contains _any_ of the labels specified - in the filter. You can also choose to trigger messages only when the issue or merge request - contains _all_ the labels defined in the filter. +to send the notifications: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Mattermost notifications**. +1. Select the GitLab events to generate notifications for. For each event you select, input the Mattermost channel + to receive the notification. You do not need to add the hash sign (`#`). +1. Fill in the integration configuration: + + - **Webhook**: The incoming webhook URL on Mattermost, similar to + `http://mattermost.example/hooks/5xo…`. + - **Username**: Optional. The username shown in messages sent to Mattermost. + To change the bot's username, provide a value. + - **Notify only broken pipelines**: If you enable the **Pipeline** event, and you want + notifications about failed pipelines only. + - **Branches for which notifications are to be sent**: The branches to send notifications for. + - **Labels to be notified**: Optional. Labels required for the issue or merge request + to trigger a notification. Leave blank to notify for all issues and merge requests. + - **Labels to be notified behavior**: When you use the **Labels to be notified** filter, + messages are sent when an issue or merge request contains _any_ of the labels specified + in the filter. You can also choose to trigger messages only when the issue or merge request + contains _all_ the labels defined in the filter. diff --git a/doc/user/project/integrations/overview.md b/doc/user/project/integrations/overview.md index 2cb62b8924e..081780e6277 100644 --- a/doc/user/project/integrations/overview.md +++ b/doc/user/project/integrations/overview.md @@ -22,9 +22,9 @@ want to configure. ## Integrations listing -Click on the service links to see further configuration instructions and details. +Click on the integration links to see further configuration instructions and details. -| Service | Description | Service hooks | +| Integration | Description | Integration hooks | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | | [Asana](asana.md) | Add commit messages as comments to Asana tasks. | **{dotted-circle}** No | | Assembla | Manage projects. | **{dotted-circle}** No | @@ -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 +If a single push includes changes to more than three branches or tags, integrations supported by `push_hooks` and `tag_push_hooks` events aren't executed. The number of branches or tags supported can be changed via @@ -89,12 +89,12 @@ By default, the SSL certificate for outgoing HTTP requests is verified based on an internal list of Certificate Authorities. This means the certificate cannot be self-signed. -You can turn off SSL verification in the configuration settings for [webhooks](webhooks.md#configure-a-webhook) +You can turn off SSL verification in the configuration settings for [webhooks](webhooks.md#configure-a-webhook-in-gitlab) and some integrations. ## 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. Learn more about [troubleshooting service hooks](webhooks.md#troubleshoot-webhooks). +Some integrations use hooks for integration with external applications. To confirm which ones use integration hooks, see the [integrations listing](#integrations-listing) above. Learn more about [troubleshooting integration hooks](webhooks.md#troubleshoot-webhooks). ### Uninitialized repositories diff --git a/doc/user/project/integrations/pivotal_tracker.md b/doc/user/project/integrations/pivotal_tracker.md index 8b17f4afaa8..7f5414b86de 100644 --- a/doc/user/project/integrations/pivotal_tracker.md +++ b/doc/user/project/integrations/pivotal_tracker.md @@ -37,8 +37,8 @@ In Pivotal Tracker, [create an API token](https://www.pivotaltracker.com/help/ar 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. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Pivotal Tracker**. 1. Ensure that the **Active** toggle is enabled. 1. Paste the token you generated in Pivotal Tracker. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 760b5030416..068a2810a53 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -62,9 +62,9 @@ GitLab can use these to access the resource. More information about authenticati service account can be found at Google's documentation for [Authenticating from a service account](https://cloud.google.com/iap/docs/authentication-howto#authenticating_from_a_service_account). -1. Navigate to the [Integrations page](overview.md#accessing-integrations) at - **Settings > Integrations**. -1. Click the **Prometheus** service. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Prometheus**. 1. For **API URL**, provide the domain name or IP address of your server, such as `http://prometheus.example.com/` or `http://192.0.2.1/`. 1. (Optional) In **Google IAP Audience Client ID**, provide the Client ID of the @@ -73,7 +73,7 @@ service account can be found at Google's documentation for Service Account credentials file that is authorized to access the Prometheus resource. The JSON key `token_credential_uri` is discarded to prevent [Server-side Request Forgery (SSRF)](https://www.hackerone.com/application-security/how-server-side-request-forgery-ssrf). -1. Click **Save changes**. +1. Select **Save changes**.  @@ -83,11 +83,12 @@ You can configure [Thanos](https://thanos.io/) as a drop-in replacement for Prom with GitLab. Use the domain name or IP address of the Thanos server you'd like to integrate with. -1. Navigate to the [Integrations page](overview.md#accessing-integrations). -1. Click the **Prometheus** service. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. +1. Select **Prometheus**. 1. Provide the domain name or IP address of your server, for example `http://thanos.example.com/` or `http://192.0.2.1/`. -1. Click **Save changes**. +1. Select **Save changes**. ### Precedence with multiple Prometheus configurations diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index e8d611af30d..08488c33ac7 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab supports automatically detecting and monitoring AWS resources, starting with the [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/) (ELB). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index 76d13d5487c..ad2cb2681b9 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab has support for automatically detecting and monitoring HAProxy. This is provided by leveraging the [HAProxy Exporter](https://github.com/prometheus/haproxy_exporter), which translates HAProxy statistics into a Prometheus readable form. diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md index 9bdd4945f5d..aba14e1f3e9 100644 --- a/doc/user/project/integrations/prometheus_library/index.md +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 33a06958e0c..9a9880a0cb6 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab has support for automatically detecting and monitoring Kubernetes metrics. diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index ecf75d7b17a..2825066b8b0 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab has support for automatically detecting and monitoring NGINX. This is provided by leveraging the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter), which translates [VTS statistics](https://github.com/vozlt/nginx-module-vts) into a Prometheus readable form. diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index e123000e0c5..6e751b907eb 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. GitLab has support for automatically detecting and monitoring the Kubernetes NGINX Ingress controller. This is provided by leveraging the built-in Prometheus metrics included with Kubernetes NGINX Ingress controller [version 0.16.0](https://github.com/kubernetes/ingress-nginx/blob/master/Changelog.md#0160) onward. 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 fda7744e847..e1eee649f0a 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 15.0. +in GitLab 14.7, and is planned for removal in GitLab 16.0. NOTE: [NGINX Ingress version 0.16](nginx_ingress.md) and above have built-in Prometheus metrics, which are different than the VTS based metrics. diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index 05d7c31a288..bcab8d05f69 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -10,7 +10,8 @@ Use [Redmine](https://www.redmine.org/) as the issue tracker. To enable the Redmine integration in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Redmine**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index cddb72a83b2..5ad344a7d8e 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -18,7 +18,7 @@ For GitLab.com, use the [GitLab Slack app](gitlab_slack_application.md) instead. ## Configure GitLab and Slack -Slack slash command [integrations](overview.md#accessing-integrations) +Slack slash command integrations are scoped to a project. 1. In GitLab, on the top bar, select **Menu > Projects** and find your project. diff --git a/doc/user/project/integrations/unify_circuit.md b/doc/user/project/integrations/unify_circuit.md index daab24a8ab9..1e607d89e80 100644 --- a/doc/user/project/integrations/unify_circuit.md +++ b/doc/user/project/integrations/unify_circuit.md @@ -15,7 +15,8 @@ copy its URL. In GitLab: -1. Go to the [Integrations page](overview.md#accessing-integrations) in your project's settings. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **Unify Circuit**. 1. Turn on the **Active** toggle. 1. Select the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit. diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index d37196ec114..2bf6b4bbe01 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -203,7 +203,7 @@ The `assignee` and `assignee_id` keys are deprecated and contain the first assignee only. The `escalation_status` and `escalation_policy` fields are -only available for issue types which support escalations, +only available for issue types which [support escalations](../../../operations/incident_management/paging.md#paging), such as incidents. Request header: @@ -538,6 +538,32 @@ Payload example: "iid": 1, "description": "Et voluptas corrupti assumenda temporibus. Architecto cum animi eveniet amet asperiores. Vitae numquam voluptate est natus sit et ad id.", "position": 0, + "labels": [ + { + "id": 25, + "title": "Afterpod", + "color": "#3e8068", + "project_id": null, + "created_at": "2019-06-05T14:32:20.211Z", + "updated_at": "2019-06-05T14:32:20.211Z", + "template": false, + "description": null, + "type": "GroupLabel", + "group_id": 4 + }, + { + "id": 86, + "title": "Element", + "color": "#231afe", + "project_id": 4, + "created_at": "2019-06-05T14:32:20.637Z", + "updated_at": "2019-06-05T14:32:20.637Z", + "template": false, + "description": null, + "type": "ProjectLabel", + "group_id": null + } + ], "source":{ "name":"Gitlab Test", "description":"Aut reprehenderit ut est.", diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index e823391401d..f4f5b3f545b 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -48,7 +48,7 @@ specific to a group, including: - [Group member events](webhook_events.md#group-member-events) - [Subgroup events](webhook_events.md#subgroup-events) -## Configure a webhook +## Configure a webhook in GitLab You can configure a webhook for a group or a project. @@ -60,6 +60,72 @@ You can configure a webhook for a group or a project. 1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](overview.md#ssl-verification). 1. Select **Add webhook**. +## Configure your webhook receiver endpoint + +Webhook receivers should be *fast* and *stable*. +Slow and unstable receivers may be disabled temporarily to ensure system reliability. +If you are writing your own endpoint (web server) to receive GitLab webhooks, keep in mind the following: + +- Your endpoint should send its HTTP response as fast as possible. + You should aim for sub-second response times in all circumstances. + If the response takes longer than the configured timeout, GitLab assumes the + hook failed, which can lead to retries and potentially cause duplicate + events. + To customize the timeout, see + [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). +- Your endpoint should ALWAYS return a valid HTTP response. If not, + GitLab assumes the hook failed and retries it. + Most HTTP libraries take care of the response for you automatically but if + you are writing a low-level hook, this is important to remember. +- GitLab usually ignores the HTTP status code returned by your endpoint, + unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks). + +Best practices for a webhook receiver: + +- Prefer to return `200` or `201` status responses. + Only return error statuses (in the `4xx` range) to + indicate that the webhook has been misconfigured. For example, if your receiver + only supports push events, it is acceptable to return `400` if sent an issue + payload, since that is an indication that the hook has been set up + incorrectly. Alternatively, it is acceptable to ignore unrecognized event + payloads. Never return `500` status responses if the event has been handled. +- Your service should be idempotent. In some circumstances (including + timeouts), the same event may be sent twice. Be prepared to handle duplicate + events. You can reduce the chances of this by ensuring that your endpoint is + reliably fast and stable. +- Keep response payloads as short as possible. Empty responses are + fine. GitLab does not examine the response body, and it is only + stored so you can examine it later in the logs. +- Limit the number and size of response headers. Only send headers that would + help you diagnose problems when examining the web hook logs. +- To support fast response times, perform I/O or computationally intensive + operations asynchronously. You may indicate that the webhook is + asynchronous by returning `201`. + +### Failing webhooks + +> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. +The feature is not ready for production use. + +If a webhook fails repeatedly, it may be disabled automatically. + +Webhooks that return response codes in the `5xx` range are understood to be failing +intermittently, and are temporarily disabled. This lasts initially +for 10 minutes. If the hook continues to fail, the back-off period is +extended on each retry, up to a maximum disabled period of 24 hours. + +Webhooks that return failure codes in the `4xx` range are understood to be +misconfigured, and these are disabled until you manually re-enable +them. These webhooks are not automatically retried. + +See [troubleshooting](#troubleshoot-webhooks) for information on +how to see if a webhook is disabled, and how to re-enable it. + ## Test a webhook You can trigger a webhook manually, to ensure it's working properly. You can also send @@ -131,47 +197,7 @@ that the request is legitimate. Push events can be filtered by branch using a branch name or wildcard pattern to limit which push events are sent to your webhook endpoint. By default, all push events are sent to your webhook endpoint. You can configure branch filtering -in the [webhook settings](#configure-a-webhook) in your project. - -## HTTP responses for your endpoint - -If you are writing your own endpoint (web server) to receive -GitLab webhooks, keep in mind the following: - -- Your endpoint should send its HTTP response as fast as possible. If the response - takes longer than the configured timeout, GitLab assumes the hook failed and retries it. - To customize the timeout, see - [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). -- Your endpoint should ALWAYS return a valid HTTP response. If not, - GitLab assumes the hook failed and retries it. - Most HTTP libraries take care of the response for you automatically but if - you are writing a low-level hook, this is important to remember. -- GitLab usually ignores the HTTP status code returned by your endpoint, - unless the [`web_hooks_disable_failed` feature flag is set](#failing-webhooks). - -### Failing webhooks - -> - Introduced in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) in GitLab 14.9. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `web_hooks_disable_failed`. -The feature is not ready for production use. - -If a webhook fails repeatedly, it may be disabled automatically. - -Webhooks that return response codes in the `5xx` range are understood to be failing -intermittently, and are temporarily disabled. This lasts initially -for 10 minutes. If the hook continues to fail, the back-off period is -extended on each retry, up to a maximum disabled period of 24 hours. - -Webhooks that return failure codes in the `4xx` range are understood to be -misconfigured, and these are disabled until you manually re-enable -them. These webhooks are not automatically retried. - -See [troubleshooting](#troubleshoot-webhooks) for information on -how to see if a webhook is disabled, and how to re-enable it. +in the [webhook settings](#configure-a-webhook-in-gitlab) in your project. ## How image URLs are displayed in the webhook body @@ -220,7 +246,7 @@ To view the table: - **Fails to connect** if it is temporarily disabled and will retry later.  - + 1. Select **Edit** for the webhook you want to view. The table includes the following details about each request: diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index eda0874ac08..6c70a5e679b 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -14,7 +14,8 @@ You can configure YouTrack as an To enable the YouTrack integration in a project: -1. Go to the [Integrations page](overview.md#accessing-integrations). +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Integrations**. 1. Select **YouTrack**. 1. Select the checkbox under **Enable integration**. 1. Fill in the required fields: |
