diff options
Diffstat (limited to 'doc/user/project/integrations')
| -rw-r--r-- | doc/user/project/integrations/gitlab_slack_application.md | 151 | ||||
| -rw-r--r-- | doc/user/project/integrations/index.md | 1 | ||||
| -rw-r--r-- | doc/user/project/integrations/mattermost_slash_commands.md | 23 | ||||
| -rw-r--r-- | doc/user/project/integrations/mlflow_client.md | 107 | ||||
| -rw-r--r-- | doc/user/project/integrations/slack.md | 2 | ||||
| -rw-r--r-- | doc/user/project/integrations/slack_slash_commands.md | 20 | ||||
| -rw-r--r-- | doc/user/project/integrations/webhook_events.md | 158 | ||||
| -rw-r--r-- | doc/user/project/integrations/webhooks.md | 4 |
8 files changed, 260 insertions, 206 deletions
diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 8790c7213e5..bfa8a905699 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -4,95 +4,110 @@ group: Import and Integrate info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab for Slack app **(FREE SAAS)** +# GitLab for Slack app **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/358872) for self-managed instances in GitLab 16.2. NOTE: -This feature is only configurable on GitLab.com. -For self-managed GitLab instances, use -[Slack slash commands](slack_slash_commands.md) and [Slack notifications](slack.md) instead. -For more information about our plans to make this feature configurable for all GitLab installations, -see [epic 1211](https://gitlab.com/groups/gitlab-org/-/epics/1211). +This page contains information about configuring the GitLab for Slack app on GitLab.com. For administrator documentation, see [GitLab for Slack app administration](../../admin_area/settings/slack_app.md). + +The GitLab for Slack app is a native Slack app that provides [slash commands](#slash-commands) and [notifications](#slack-notifications) +in your Slack workspace. GitLab links your Slack user with your GitLab user so that any command +you run in Slack is run by your linked GitLab user. + +## Install the GitLab for Slack app -Slack provides a native application that you can enable with your project's -integrations on GitLab.com. +Prerequisites: -## Installation +- You must have the [appropriate permissions to add apps to your Slack workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). +- On self-managed GitLab, an administrator must [enable the integration](../../admin_area/settings/slack_app.md). In GitLab 15.0 and later, the GitLab for Slack app uses [granular permissions](https://medium.com/slack-developer-blog/more-precision-less-restrictions-a3550006f9c3). Although functionality has not changed, you should [reinstall the app](#update-the-gitlab-for-slack-app). -### Through the Slack App Directory +### From project integration settings -To enable the GitLab for Slack app for your workspace, -install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) -from the [Slack App Directory](https://slack.com/apps). +To install the GitLab for Slack app from project integration settings: -On the [GitLab for Slack app landing page](https://gitlab.com/-/profile/slack/edit), -you can select a GitLab project to link with your Slack workspace. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select **GitLab for Slack app**. +1. Select **Install GitLab for Slack app**. +1. On the Slack confirmation page, select **Allow**. -### Through GitLab project settings +To update the app in your Slack workspace to the latest version, +you can also select **Reinstall GitLab for Slack app**. -Alternatively, you can configure the GitLab for Slack app with your project's -integration settings. +### From the Slack App Directory **(FREE SAAS)** -You must have the appropriate permissions for your Slack -workspace to be able to install a new application. See -[Add apps to your Slack workspace](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace). +On GitLab.com, you can also install the GitLab for Slack app from the +[Slack App Directory](https://slack-platform.slack.com/apps/A676ADMV5-gitlab). -To enable the GitLab integration for your Slack workspace: +To install the GitLab for Slack app from the Slack App Directory: -1. Go to your project's **Settings > Integration > GitLab for Slack app** (only - visible on GitLab.com). -1. Select **Install GitLab for Slack app**. -1. Select **Allow** on Slack's confirmation screen. +1. Go to the [GitLab for Slack page](https://gitlab.com/-/profile/slack/edit). +1. Select a GitLab project to link with your Slack workspace. -To update the app in your Slack workspace to the latest version, -you can also select **Reinstall GitLab for Slack app**. +## Update the GitLab for Slack app + +When GitLab releases new features for the GitLab for Slack app, you might have to manually update your app to use the new features. + +To update your GitLab for Slack app: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for + which the GitLab for Slack app is configured. +1. Select **Settings > Integrations**. +1. Select **GitLab for Slack app**. +1. Select **Reinstall GitLab for Slack app**. + +The GitLab for Slack app is updated for all projects that use the integration. + +Alternatively, you can [configure the integration](https://about.gitlab.com/solutions/slack/) again. ## Slash commands -After installing the GitLab for Slack app, everyone in your Slack workspace can use slash commands. +You can use slash commands to run common GitLab operations. Replace `<project>` with a project full path. + +**For the GitLab for Slack app**: + +- You must authorize your Slack user on GitLab.com when you run your first slash command. +- You can [create a shorter project alias](#create-a-project-alias-for-slash-commands) for slash commands. + +**For [Slack slash commands](slack_slash_commands.md) on self-managed GitLab, [Mattermost slash commands](mattermost_slash_commands.md), and [ChatOps](../../../ci/chatops/index.md)**, replace `/gitlab` with the slash command trigger name configured for your integration. -Replace `<project>` with the project full path, or create a shorter [project alias](#create-a-project-alias-for-slash-commands) for the slash commands. +The following slash commands are available: -| Command | Effect | -| ------- | ------ | +| Command | Description | +| ------- | ----------- | | `/gitlab help` | Shows all available slash commands. | -| `/gitlab <project> issue new <title> <shift+return> <description>` | Creates a new issue with the title `<title>` and description `<description>`. | +| `/gitlab <project> issue new <title>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<description>` | Creates a new issue with the title `<title>` and description `<description>`. | | `/gitlab <project> issue show <id>` | Shows the issue with the ID `<id>`. | | `/gitlab <project> issue close <id>` | Closes the issue with the ID `<id>`. | -| `/gitlab <project> issue search <query>` | Shows up to 5 issues matching `<query>`. | +| `/gitlab <project> issue search <query>` | Shows up to five issues matching `<query>`. | | `/gitlab <project> issue move <id> to <project>` | Moves the issue with the ID `<id>` to `<project>`. | -| `/gitlab <project> issue comment <id> <shift+return> <comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. | +| `/gitlab <project> issue comment <id>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<comment>` | Adds a new comment with the comment body `<comment>` to the issue with the ID `<id>`. | | `/gitlab <project> deploy <from> to <to>` | [Deploys](#the-deploy-slash-command) from the `<from>` environment to the `<to>` environment. | | `/gitlab <project> run <job name> <arguments>` | Executes the [ChatOps](../../../ci/chatops/index.md) job `<job name>` on the default branch. | -| `/gitlab incident declare` | **Beta** Opens modal to [create a new incident](../../../operations/incident_management/slack.md). | +| `/gitlab incident declare` | Opens a dialog to [create a new incident from Slack](../../../operations/incident_management/slack.md) (Beta). | -### The deploy slash command +### The `deploy` slash command -To deploy to an environment, GitLab tries to find a deployment -manual action in the pipeline. +To deploy to an environment, GitLab tries to find a deployment manual action in the pipeline. -If there's only one action for a given environment, it is triggered. -If more than one action is defined, GitLab finds an action -name that matches the environment name to deploy to. +If only one action is defined for a given environment, it is triggered. +If more than one action is defined, GitLab tries to find an action name +that matches the environment name to deploy to. The command returns an error if no matching action is found. -### User authorization - -When you perform your first slash command, you must -authorize your Slack user on GitLab.com. - ### Create a project alias for slash commands -By default, slash commands expect a project full path. To use a shorter alias -instead: +By default, slash commands expect a project full path. To create a shorter project alias in the GitLab for Slack app: -1. Go to your project's home page. -1. Go to **Settings > Integrations** (only visible on GitLab.com). -1. On the **Integrations** page, select **GitLab for Slack app**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > Integrations**. +1. Select **GitLab for Slack app**. 1. The current **Project Alias**, if any, is displayed. To edit this value, select **Edit**. 1. Enter your desired alias, and select **Save changes**. @@ -101,19 +116,19 @@ instead: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/381012) in GitLab 15.9. -With Slack notifications, GitLab can send messages to Slack workspace channels for certain GitLab [events](#events-for-slack-notifications) (for example, when an issue is created). +With Slack notifications, GitLab can send messages to Slack workspace channels for certain GitLab [events](#notification-events). ### Configure notifications To configure Slack notifications: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for - which the GitLab for Slack app has been [installed](#installation). + which the GitLab for Slack app is [installed](#install-the-gitlab-for-slack-app). 1. Select **Settings > Integrations**. 1. Select **GitLab for Slack app**. 1. In the **Trigger** section, select the checkbox for each GitLab event you want to receive a notification for in Slack. For a full list, see - [Events for Slack notifications](#events-for-slack-notifications). + [Notification events](#notification-events). 1. For each checkbox you select, enter the name of the channel that receives the notifications (for example, `#my-channel`). - To send notifications to multiple Slack channels, enter up to 10 channel names separated by commas (for example, `#channel-one, #channel-two`). @@ -136,7 +151,7 @@ To receive notifications to a private Slack channel, you must add the GitLab for 1. Mention the app in the channel by typing `@GitLab` and pressing <kbd>Enter</kbd>. 1. Select **Add to Channel**. -### Events for Slack notifications +### Notification events The following events are available for Slack notifications: @@ -153,25 +168,17 @@ The following events are available for Slack notifications: | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | +| **Group mention in public** | A group is mentioned in a public context. | +| **Group mention in private** | A group is mentioned in a confidential context. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | ## Troubleshooting -### Update the GitLab for Slack app - -New releases of the app might require permissions to be authorized before some features work in your Slack workspace. You should ensure the app is up to date in your Slack workspace to enjoy all the latest features. +### GitLab for Slack app does not appear in the list of integrations -To update your GitLab for Slack app: - -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find a project for - which the GitLab for Slack app has been configured. -1. Select **Settings > Integrations**. -1. Select **GitLab for Slack app**. -1. Select **Reinstall GitLab for Slack app**. - -The GitLab for Slack app is updated for all projects that use the integration. +The GitLab for Slack app might not appear in the list of integrations. To have the GitLab for Slack app on your self-managed instance, an administrator must [enable the integration](../../admin_area/settings/slack_app.md). On GitLab.com, the GitLab for Slack app is available by default. -Alternatively, you can [configure a new Slack integration](https://about.gitlab.com/solutions/slack/). +The GitLab for Slack app is enabled at the project level only. Support for the app at the group and instance levels is proposed in [issue 391526](https://gitlab.com/gitlab-org/gitlab/-/issues/391526). ### Project or alias not found @@ -186,7 +193,11 @@ As a workaround, ensure: - The project full path is correct. - If using a [project alias](#create-a-project-alias-for-slash-commands), the alias is correct. -- The GitLab for Slack app integration is [enabled for the project](#through-gitlab-project-settings). +- The GitLab for Slack app is [enabled for the project](#from-project-integration-settings). + +### Slash commands return `/gitlab failed with the error "dispatch_failed"` in Slack + +Slash commands might return `/gitlab failed with the error "dispatch_failed"` in Slack. To resolve this issue, ensure an administrator has properly configured the [GitLab for Slack app settings](../../admin_area/settings/slack_app.md) on your self-managed instance. ### Notifications are not received to a channel diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index c70a58a24d2..fd59f54a066 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -72,7 +72,6 @@ You can configure the following integrations. | Packagist | Keep your PHP dependencies updated on Packagist. | **{check-circle}** Yes | | [Pipelines emails](pipeline_status_emails.md) | Send the pipeline status to a list of recipients by email. | **{dotted-circle}** No | | [Pivotal Tracker](pivotal_tracker.md) | Add commit messages as comments to Pivotal Tracker stories. | **{dotted-circle}** No | -| [Prometheus](prometheus.md) | Monitor application metrics. | **{dotted-circle}** No | | [Pumble](pumble.md) | Send event notifications to a Pumble channel. | **{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 | diff --git a/doc/user/project/integrations/mattermost_slash_commands.md b/doc/user/project/integrations/mattermost_slash_commands.md index a8d8323a651..6a09a1cfbcd 100644 --- a/doc/user/project/integrations/mattermost_slash_commands.md +++ b/doc/user/project/integrations/mattermost_slash_commands.md @@ -6,12 +6,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Mattermost slash commands **(FREE)** -You can use slash commands to run common GitLab operations, like creating an issue, -from a [Mattermost](https://mattermost.com/) chat environment. +You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations, +like creating an issue, from a [Mattermost](https://mattermost.com/) chat environment. GitLab can also send events (such as `issue created`) to Mattermost as part of the separately configured [Mattermost notifications](mattermost.md). +For a list of available slash commands, see [Slash commands](gitlab_slack_application.md#slash-commands). + ## Configuration options GitLab provides different ways to configure Mattermost slash commands. For any of these options, @@ -109,7 +111,7 @@ Your slash command can now communicate with your GitLab project. Prerequisite: -- To run [slash commands](#available-slash-commands), you must have +- To run [slash commands](gitlab_slack_application.md#slash-commands), you must have [permission](../../permissions.md#project-members-permissions) to perform the action in the GitLab project. @@ -120,21 +122,10 @@ To interact with GitLab using Mattermost slash commands: You can see all authorized chat accounts in your Mattermost profile page under **Chat**. -## Available slash commands - -The available slash commands for Mattermost are: - -| Command | Description | Example | -| ------- | ----------- | ------- | -| `/<trigger> issue new <title>` <kbd>Shift</kbd>+<kbd>Enter</kbd> `<description>` | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` | -| `/<trigger> issue show <issue-number>` | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` | -| `/<trigger> deploy <environment> to <environment>` | Start the CI/CD job that deploys from one environment to another (for example, `staging` to `production`). CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` | -| `/<trigger> help` | View a list of available slash commands. | `/gitlab help` | - ## Related topics -- [Mattermost slash commands](https://developers.mattermost.com/integrate/slash-commands/) -- [Linux package Mattermost](../../../integration/mattermost/index.md) +- [Mattermost Linux package](../../../integration/mattermost/index.md) +- [Slash commands at Mattermost](https://developers.mattermost.com/integrate/slash-commands/) ## Troubleshooting diff --git a/doc/user/project/integrations/mlflow_client.md b/doc/user/project/integrations/mlflow_client.md index cffa2649cc8..ce092d10d20 100644 --- a/doc/user/project/integrations/mlflow_client.md +++ b/doc/user/project/integrations/mlflow_client.md @@ -1,104 +1,11 @@ --- -stage: Create -group: Incubation -info: Machine Learning Experiment Tracking is a GitLab Incubation Engineering program. No technical writer assigned to this group. +redirect_to: '../ml/experiment_tracking/mlflow_client.md' +remove_date: '2023-10-12' --- -# MLflow client integration **(FREE)** +This document was moved to [another location](../ml/experiment_tracking/mlflow_client.md). -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8560) in GitLab 15.11 as an [Experiment](../../../policy/experiment-beta-support.md#experiment) release [with a flag](../../../administration/feature_flags.md) named `ml_experiment_tracking`. Disabled by default. - -NOTE: -Model experiment tracking is an [experimental feature](../../../policy/experiment-beta-support.md). -Refer to <https://gitlab.com/gitlab-org/gitlab/-/issues/381660> for feedback and feature requests. - -[MLflow](https://mlflow.org/) is a popular open source tool for Machine Learning Experiment Tracking. -GitLab works as a backend to the MLflow Client, [logging experiments](../ml/experiment_tracking/index.md). -Setting up your integrations requires minimal changes to existing code. - -GitLab plays the role of a MLflow server. Running `mlflow server` is not necessary. - -## Enable MLflow client integration - -Prerequisites: - -- A [personal access token](../../../user/profile/personal_access_tokens.md) for the project, with minimum access level of `api`. -- The project ID. To find the project ID: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. - 1. Select **Settings > General**. - -To enable MLflow client integration: - -1. Set the tracking URI and token environment variables on the host that runs the code. - This can be your local environment, CI pipeline, or remote host. For example: - - ```shell - export MLFLOW_TRACKING_URI="http://<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow" - export MLFLOW_TRACKING_TOKEN="<your_access_token>" - ``` - -1. If your training code contains the call to `mlflow.set_tracking_uri()`, remove it. - -When running the training code, MLflow creates experiments, runs, log parameters, metrics, metadata -and artifacts on GitLab. - -After experiments are logged, they are listed under `/<your project>/-/ml/experiments`. -Runs are registered as: - -- Model Candidates, which can be explored by selecting an experiment. -- Tags, which are registered as metadata. - -## Associating a candidate to a CI/CD job - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119454) in GitLab 16.1. - -If your training code is being run from a CI/CD job, GitLab can use that information to enhance -candidate metadata. To do so, add the following snippet to your training code within the run -execution context: - -```python -with mlflow.start_run(run_name=f"Candidate {index}"): - # Your training code - - # Start of snippet to be included - if os.getenv('GITLAB_CI'): - mlflow.set_tag('gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID')) - # End of snippet to be included -``` - -## Supported MLflow client methods and caveats - -GitLab supports these methods from the MLflow client. Other methods might be supported but were not -tested. More information can be found in the [MLflow Documentation](https://www.mlflow.org/docs/1.28.0/python_api/mlflow.html). - -| Method | Supported | Version Added | Comments | -|--------------------------|------------------|----------------|----------| -| `get_experiment` | Yes | 15.11 | | -| `get_experiment_by_name` | Yes | 15.11 | | -| `set_experiment` | Yes | 15.11 | | -| `get_run` | Yes | 15.11 | | -| `start_run` | Yes | 15.11 | | -| `log_artifact` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. -| `log_artifacts` | Yes with caveat | 15.11 | (15.11) `artifact_path` must be empty string. Does not support directories. -| `log_batch` | Yes | 15.11 | | -| `log_metric` | Yes | 15.11 | | -| `log_metrics` | Yes | 15.11 | | -| `log_param` | Yes | 15.11 | | -| `log_params` | Yes | 15.11 | | -| `log_figure` | Yes | 15.11 | | -| `log_image` | Yes | 15.11 | | -| `log_text` | Yes with caveat | 15.11 | (15.11) Does not support directories. -| `log_dict` | Yes with caveat | 15.11 | (15.11) Does not support directories. -| `set_tag` | Yes | 15.11 | | -| `set_tags` | Yes | 15.11 | | -| `set_terminated` | Yes | 15.11 | | -| `end_run` | Yes | 15.11 | | -| `update_run` | Yes | 15.11 | | -| `log_model` | Partial | 15.11 | (15.11) Saves the artifacts, but not the model data. `artifact_path` must be empty. - -## Limitations - -- The API GitLab supports is the one defined at MLflow version 1.28.0. -- API endpoints not listed above are not supported. -- During creation of experiments and runs, ExperimentTags are stored, even though they are not displayed. -- MLflow Model Registry is not supported. +<!-- This redirect file can be deleted after <2023-10-12>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index 14183a47625..55000a0a992 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -79,6 +79,8 @@ The following triggers are available for Slack notifications: | **Wiki page** | A wiki page is created or updated. | | **Deployment** | A deployment starts or finishes. | | **Alert** | A new, unique alert is recorded. | +| **Group mention in public** | A group is mentioned in a public context. | +| **Group mention in private** | A group is mentioned in a confidential context. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | ## Troubleshooting diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 74bd12561fb..c1e04f2aa63 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -10,16 +10,18 @@ NOTE: This feature is only configurable on self-managed GitLab instances. For GitLab.com, use the [GitLab for Slack app](gitlab_slack_application.md) instead. -If you want to control and view GitLab content while you're -working in Slack, you can use Slack slash commands. -To use Slack slash commands, you must configure both Slack and GitLab. +You can use [slash commands](gitlab_slack_application.md#slash-commands) to run common GitLab operations, +like creating an issue, from a [Slack](https://slack.com/) chat environment. +To use slash commands in Slack, you must configure both Slack and GitLab. -GitLab can also send events (for example, `issue created`) to Slack as notifications. -The [Slack notifications integration](slack.md) is configured separately. +GitLab can also send events (such as `issue created`) to Slack as part of the +separately configured [Slack notifications](slack.md). -## Configure GitLab and Slack +For a list of available slash commands, see [Slash commands](gitlab_slack_application.md#slash-commands). -Slack slash command integrations are scoped to a project. +## Configure the integration + +Slack slash commands are scoped to a project. To configure Slack slash commands: 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. 1. Select **Settings > Integrations**. @@ -35,7 +37,3 @@ Slack slash command integrations are scoped to a project. 1. On the Slack configuration page, select **Save Integration** and copy the **Token**. 1. Go back to the GitLab configuration page and paste in the **Token**. 1. Ensure the **Active** checkbox is selected and select **Save changes**. - -## Slash commands - -You can now use the available [Slack slash commands](../../../integration/slash_commands.md). diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index dfff537e4a1..8d66f3e48dd 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -24,6 +24,7 @@ Event type | Trigger [Subgroup event](#subgroup-events) | A subgroup is created or removed from a group. [Feature flag event](#feature-flag-events) | A feature flag is turned on or off. [Release event](#release-events) | A release is created or updated. +[Emoji event](#emoji-events) | An emoji is awarded or revoked. NOTE: If an author has no public email listed in their @@ -61,6 +62,7 @@ Payload example: "before": "95790bf891e76fee5e1747ab589903a6a1f80f22", "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", "ref": "refs/heads/master", + "ref_protected": true, "checkout_sha": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", "user_id": 4, "user_name": "John Smith", @@ -151,6 +153,7 @@ Payload example: "before": "0000000000000000000000000000000000000000", "after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", "ref": "refs/tags/v1.0.0", + "ref_protected": true, "checkout_sha": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7", "user_id": 1, "user_name": "John Smith", @@ -1468,13 +1471,8 @@ Payload example: ### Number of retries -> `retries_count` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `job_webhook_retries_count`. Disabled by default. - -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 -`job_webhook_retries_count`. -On GitLab.com, this feature is not available. +> - `retries_count` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 15.6 [with a flag](../../../administration/feature_flags.md) named `job_webhook_retries_count`. Disabled by default. +> - `retries_count` [enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/382046) in GitLab 16.2. `retries_count` is an integer that indicates if the job is a retry. `0` means that the job has not been retried. `1` means that it's the first retry. @@ -1850,3 +1848,149 @@ Payload example: } } ``` + +## Emoji events + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123952) in GitLab 16.2 [with a flag](../../../administration/feature_flags.md) named `emoji_webhooks`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `emoji_webhooks`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +NOTE: +To have the `emoji_webhooks` flag enabled on GitLab.com, see [issue 417288](https://gitlab.com/gitlab-org/gitlab/-/issues/417288). + +An emoji event is triggered when an emoji is awarded or revoked on: + +- Issues +- Merge requests +- Project snippets +- Comments on: + - Issues + - Merge requests + - Project snippets + - Commits + +The available values for `object_attributes.action` in the payload are: + +- `award` +- `revoke` + +Request header: + +```plaintext +X-Gitlab-Event: Emoji Hook +``` + +Payload example: + +```json +{ + "object_kind": "emoji", + "event_type": "award", + "user": { + "id": 1, + "name": "Blake Bergstrom", + "username": "root", + "avatar_url": "http://example.com/uploads/-/system/user/avatar/1/avatar.png", + "email": "[REDACTED]" + }, + "project_id": 6, + "project": { + "id": 6, + "name": "Flight", + "description": "Velit fugit aperiam illum deleniti odio sequi.", + "web_url": "http://example.com/flightjs/Flight", + "avatar_url": null, + "git_ssh_url": "ssh://git@example.com/flightjs/Flight.git", + "git_http_url": "http://example.com/flightjs/Flight.git", + "namespace": "Flightjs", + "visibility_level": 20, + "path_with_namespace": "flightjs/Flight", + "default_branch": "master", + "ci_config_path": null, + "homepage": "http://example.com/flightjs/Flight", + "url": "ssh://git@example.com/flightjs/Flight.git", + "ssh_url": "ssh://git@example.com/flightjs/Flight.git", + "http_url": "http://example.com/flightjs/Flight.git" + }, + "object_attributes": { + "user_id": 1, + "created_at": "2023-07-04 20:44:11 UTC", + "id": 1, + "name": "thumbsup", + "awardable_type": "Note", + "awardable_id": 363, + "updated_at": "2023-07-04 20:44:11 UTC", + "action": "award", + "awarded_on_url": "http://example.com/flightjs/Flight/-/issues/42#note_363" + }, + "note": { + "attachment": null, + "author_id": 1, + "change_position": null, + "commit_id": null, + "created_at": "2023-07-04 15:09:55 UTC", + "discussion_id": "c3d97fd471f210a5dc8b97a409e3bea95ee06c14", + "id": 363, + "line_code": null, + "note": "Testing 123", + "noteable_id": 635, + "noteable_type": "Issue", + "original_position": null, + "position": null, + "project_id": 6, + "resolved_at": null, + "resolved_by_id": null, + "resolved_by_push": null, + "st_diff": null, + "system": false, + "type": null, + "updated_at": "2023-07-04 19:58:46 UTC", + "updated_by_id": null, + "description": "Testing 123", + "url": "http://example.com/flightjs/Flight/-/issues/42#note_363" + }, + "issue": { + "author_id": 1, + "closed_at": null, + "confidential": false, + "created_at": "2023-07-04 14:59:43 UTC", + "description": "Issue description!", + "discussion_locked": null, + "due_date": null, + "id": 635, + "iid": 42, + "last_edited_at": null, + "last_edited_by_id": null, + "milestone_id": null, + "moved_to_id": null, + "duplicated_to_id": null, + "project_id": 6, + "relative_position": 18981, + "state_id": 1, + "time_estimate": 0, + "title": "New issue!", + "updated_at": "2023-07-04 15:09:55 UTC", + "updated_by_id": null, + "weight": null, + "health_status": null, + "url": "http://example.com/flightjs/Flight/-/issues/42", + "total_time_spent": 0, + "time_change": 0, + "human_total_time_spent": null, + "human_time_change": null, + "human_time_estimate": null, + "assignee_ids": [ + 1 + ], + "assignee_id": 1, + "labels": [ + + ], + "state": "opened", + "severity": "unknown" + } +} +``` diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 5c8fc5703dd..9f24f3b49ff 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -126,7 +126,7 @@ Endpoints should follow these best practices: > - [Disabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/390157) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`. 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 `auto_disabling_web_hooks`. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../../administration/feature_flags.md) named `auto_disabling_web_hooks`. On GitLab.com, this feature is available. Project or group webhooks that fail four consecutive times are automatically disabled. @@ -279,6 +279,7 @@ For more information about supported events for webhooks, see [webhook events](w > - `X-Gitlab-Event-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8. > - `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5. +> - `X-Gitlab-Webhook-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230830) in GitLab 16.2. Webhook requests to your endpoint include the following headers: @@ -286,6 +287,7 @@ Webhook requests to your endpoint include the following headers: | ------ | ------ | ------ | | `User-Agent` | In the format `"Gitlab/<VERSION>"`. | `"GitLab/15.5.0-pre"` | | `X-Gitlab-Instance` | Hostname of the GitLab instance that sent the webhook. | `"https://gitlab.com"` | +| `X-Gitlab-Webhook-UUID` | Unique ID per webhook. If a webhook request fails and retries, the second request has a new ID. | `"02affd2d-2cba-4033-917d-ec22d5dc4b38"` | | `X-Gitlab-Event` | Name of the webhook type. Corresponds to [event types](webhook_events.md) but in the format `"<EVENT> Hook"`. | `"Push Hook"` | | `X-Gitlab-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` | |