diff options
Diffstat (limited to 'doc/user/project/integrations')
| -rw-r--r-- | doc/user/project/integrations/aws_codepipeline.md | 114 | ||||
| -rw-r--r-- | doc/user/project/integrations/bamboo.md | 4 | ||||
| -rw-r--r-- | doc/user/project/integrations/bugzilla.md | 2 | ||||
| -rw-r--r-- | doc/user/project/integrations/gitlab_slack_application.md | 11 | ||||
| -rw-r--r-- | doc/user/project/integrations/index.md | 201 | ||||
| -rw-r--r-- | doc/user/project/integrations/mock_ci.md | 4 | ||||
| -rw-r--r-- | doc/user/project/integrations/servicenow.md | 2 | ||||
| -rw-r--r-- | doc/user/project/integrations/shimo.md | 17 | ||||
| -rw-r--r-- | doc/user/project/integrations/telegram.md | 2 | ||||
| -rw-r--r-- | doc/user/project/integrations/webhook_events.md | 33 | ||||
| -rw-r--r-- | doc/user/project/integrations/webhooks.md | 6 | ||||
| -rw-r--r-- | doc/user/project/integrations/zentao.md | 11 |
12 files changed, 286 insertions, 121 deletions
diff --git a/doc/user/project/integrations/aws_codepipeline.md b/doc/user/project/integrations/aws_codepipeline.md new file mode 100644 index 00000000000..b081544199e --- /dev/null +++ b/doc/user/project/integrations/aws_codepipeline.md @@ -0,0 +1,114 @@ +--- +stage: Manage +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 +--- + +# AWS CodePipeline **(FREE SAAS)** + +> [Introduced](https://gitlab.com/gitlab-com/alliances/aws/wip/aws-cs-collab/aws-gitlab-collaboration/-/issues/25) in GitLab 16.5. + +You can use your GitLab project to build, test, and deploy code changes using [AWS CodePipeline](https://aws.amazon.com/codepipeline/). To do so, you use: + +- AWS CodeStar Connections to connect your GitLab.com account to AWS. +- That connection to automatically start a pipeline based on changes to your code. + +## Create a connection from AWS CodePipeline to GitLab + +Prerequisites: + +- You must have the Owner role on the GitLab project that you are connecting with AWS CodePipeline. +- You must have the appropriate permissions to create a connection in AWS. +- You must use a supported AWS region. Unsupported regions (also listed in the [AWS documentation](https://docs.aws.amazon.com/codepipeline/latest/userguide/connections-gitlab.html)) are: + - Asia Pacific (Hong Kong). + - Africa (Cape Town). + - Middle East (Bahrain). + - Europe (Zurich). + - AWS GovCloud (US-West and US-East). + +To create a connection to a project on GitLab.com, you can use either the AWS Management Console, or the AWS Command Line Interface (AWS CLI). + +### Use the AWS Management Console + +To connect a new or existing pipeline in AWS CodePipeline with GitLab.com, first authorize the AWS connection to use your GitLab account. + +1. Sign in to the AWS Management Console, and open the [AWS Developer Tools console](https://console.aws.amazon.com/codesuite/settings/connections). +1. Select **Settings** > **Connections** > **Create connection**. +1. In **Select a provider**, select **GitLab**. +1. In **Connection name**, enter the name for the connection that you want to create and select **Connect to GitLab**. +1. In the GitLab sign-in page, enter your credentials and select **Sign in**. +1. An authorization page displays with a message requesting authorization for the connection to access your GitLab account. Select **Authorize**. +1. The browser returns to the connections console page. In the **Create GitLab connection** section, the new connection is shown in **Connection name**. +1. Select **Connect to GitLab**. After the connection is created successfully, a success banner displays. The connection details are shown on the **Connection settings** page. + +Now you've connected AWS CodeSuite to GitLab.com, you can create or edit a pipeline in AWS CodePipeline that leverages your GitLab projects. + +1. Sign in to the [AWS CodePipeline console](https://console.aws.amazon.com/codesuite/codepipeline/start). +1. Create or edit a pipeline: + - If you are creating a pipeline: + - Complete the fields in the first screen and select **Next**. + - On the **Source** page, in the **Source Provider** section, select **GitLab**. + - If you are editing an existing pipeline: + - Select **Edit** > **Edit stage** to add or edit your source action. + - On the **Edit action** page, in the **Action name** section, enter the name for your action. + - In **Action provider**, select **GitLab**. +1. In **Connection**, select the connection you created earlier. +1. In **Repository name**, to choose the name of your GitLab project, specify the full project path with the namespace and all subgroups. + For example, for a group-level project, enter the project name in the following format: `group-name/subgroup-name/project-name`. + The project path with the namespace is in the URL in GitLab. Do not copy URLs from the Web IDE or raw views as they contain other special URL segments. + You can also pick an option from the dialog, or type a new path manually. + For more information about the: + - Path and namespace, see the `path_with_namespace` field in the [projects API](../../../api/projects.md#get-single-project). + - Namespace in GitLab, see [namespaces](../../namespace/index.md). + +1. In **Branch name**, select the branch where you want your pipeline to detect source changes. + If the branch name does not populate automatically, this might be because of one of the following: + - You do not have the Owner role for the project. + - The project name is not valid. + - The connection used does not have access to the project. + +1. In **Output artifact format**, select the format for your artifacts. To store: + - Output artifacts from the GitLab action using the default method, select **CodePipeline default**. The action accesses the files from the GitLab repository and + stores the artifacts in a ZIP file in the pipeline artifact store. + - A JSON file that contains a URL reference to the repository so that downstream actions can perform Git commands directly, select **Full clone**. This option can only be used + by CodeBuild downstream actions. To choose this option: + - [Update the permissions for your CodeBuild project service role](https://docs.aws.amazon.com/codepipeline/latest/userguide/troubleshooting.html#codebuild-role-connections). + - Follow the [AWS CodePipeline tutorial on how to use full clone with a GitHub pipeline source](https://docs.aws.amazon.com/codepipeline/latest/userguide/tutorials-github-gitclone.html). +1. Save the source action and continue. + +### Use the AWS CLI + +To use the AWS CLI to create a connection: + +- Use the `create-connection` command. +- Go to the AWS Console to authenticate with your GitLab.com account. +- Connect your GitLab project to AWS CodePipeline. + +To use the `create-connection` command: + +1. Open a terminal (Linux, macOS, or Unix) or command prompt (Windows). Use the AWS CLI to run the `create-connection` command, + specifying the `--provider-type` and `--connection-name` for your connection. In this example, the third-party provider name is + `GitLab` and the specified connection name is `MyConnection`. + + ```shell + aws codestar-connections create-connection --provider-type GitLab --connection-name MyConnection + ``` + + If successful, this command returns the connection's Amazon Resource Name (ARN) information. For example: + + ```json + { + "ConnectionArn": "arn:aws:codestar-connections:us-west-2:account_id:connection/aEXAMPLE-8aad-4d5d-8878-dfcab0bc441f" + } + ``` + +1. The new connection is created with a `PENDING` status by default. Use the console to change the connection's status to `AVAILABLE`. + +1. [Use the AWS Console to complete the connection](#use-the-aws-management-console). Make sure you select your pending GitLab connection. Do not select **Create connection**. + +## Related topics + +- [Announcement that AWS CodePipeline supports GitLab](https://aws.amazon.com/about-aws/whats-new/2023/08/aws-codepipeline-supports-gitlab/) +- [GitLab connections - AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/connections-gitlab.html) +- [Create a connection to GitLab - Developer Tools console](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-gitlab.html) +- [CodeStarSourceConnection for Bitbucket, GitHub, GitHub Enterprise Server, and GitLab actions - AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/action-reference-CodestarConnectionSource.html) diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 242d5e6974c..85cab40626d 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -41,7 +41,7 @@ integration in GitLab. 1. Select **Atlassian Bamboo**. 1. Ensure the **Active** checkbox is selected. 1. Enter the base URL of your Bamboo server. For example, `https://bamboo.example.com`. -1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](index.md#manage-ssl-verification). +1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](index.md#ssl-verification). 1. Enter the [build key](#identify-the-bamboo-build-plan-build-key) from your Bamboo build plan. 1. If necessary, enter a username and password for a Bamboo user that has @@ -124,7 +124,7 @@ For example: ### Builds not triggered If builds are not triggered, ensure you entered the right GitLab IP address in -Bamboo under **Trigger IP addresses**. Also check [integration webhook logs](index.md#troubleshooting) for request failures. +Bamboo under **Trigger IP addresses**. Also, check the integration webhook logs for request failures. ### Advanced Atlassian Bamboo features not available in GitLab UI diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index febbee66c33..8b04d6aad8e 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -58,4 +58,4 @@ internal issue tracker, the internal issue is linked. ## Troubleshooting -For recent integration webhook deliveries, check [integration webhook logs](index.md#troubleshooting). +For recent integration webhook deliveries, check the integration webhook logs. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index d762c71242d..6f70305ce8b 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -168,19 +168,8 @@ 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](#trigger-notifications-for-group-mentions) in public** | A group is mentioned in a public context. | -| **[Group mention](#trigger-notifications-for-group-mentions) in private** | A group is mentioned in a confidential context. | | [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. | -### Trigger notifications for group mentions - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/417751) in GitLab 16.4. - -To trigger a [notification event](#notification-events) for a group mention, use `@<group_name>` in: - -- Issue and merge request descriptions -- Comments on issues, merge requests, and commits - ## Troubleshooting ### GitLab for Slack app does not appear in the list of integrations diff --git a/doc/user/project/integrations/index.md b/doc/user/project/integrations/index.md index 59b5043b8f7..01dbdd0b3f2 100644 --- a/doc/user/project/integrations/index.md +++ b/doc/user/project/integrations/index.md @@ -6,120 +6,181 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Project integrations **(FREE ALL)** -You can integrate your GitLab projects with other applications. Integrations are -like plugins, and give you the freedom to add -functionality to GitLab. +NOTE: +This page contains information about configuring project integrations on GitLab.com. For administrator documentation, see [Project integration administration](../../../administration/settings/project_integration_management.md). + +You can integrate with external applications to add functionality to GitLab. + +You can view and manage integrations at the: + +- [Instance level](../../../administration/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration) (self-managed GitLab) +- [Group level](#manage-group-level-default-settings-for-a-project-integration) + +You can use: + +- [Instance-level or group-level default settings for a project integration](#use-instance-level-or-group-level-default-settings-for-a-project-integration) +- [Custom settings for a project or group integration](#use-custom-settings-for-a-project-or-group-integration) + +## Manage group-level default settings for a project integration + +Prerequisite: + +- You must have at least the Maintainer role for the group. + +To manage group-level default settings for a project integration: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > Integrations**. +1. Select an integration. +1. Complete the fields. +1. Select **Save changes**. + +WARNING: +This may affect all or most of the subgroups and projects belonging to the group. Review the details below. + +If this is the first time you are setting up group-level settings for an integration: + +- The integration is enabled for all subgroups and projects belonging to the group that don't already have + this integration configured, if you have the **Enable integration** toggle turned on in the group-level + settings. +- Subgroups and projects that already have the integration configured are not affected, but can choose to use + the inherited settings at any time. + +When you make further changes to the group defaults: + +- They are immediately applied to all subgroups and projects belonging to the group that have the integration + set to use default settings. +- They are immediately applied to newer subgroups and projects, even those created after you last saved defaults for the + integration. If your group-level default setting has the **Enable integration** toggle turned on, + the integration is automatically enabled for all such subgroups and projects. +- Subgroups and projects with custom settings selected for the integration are not immediately affected and + may choose to use the latest defaults at any time. + +If [instance-level settings](../../../administration/settings/project_integration_management.md#manage-instance-level-default-settings-for-a-project-integration) +have also been configured for the same integration, projects in the group inherit settings from the group. + +Only the entire settings for an integration can be inherited. Per-field inheritance +is proposed in [epic 2137](https://gitlab.com/groups/gitlab-org/-/epics/2137). + +### Remove a group-level default setting -## View project integrations +Prerequisite: -Prerequisites: +- You must have at least the Maintainer role for the group. + +To remove a group-level default setting: + +1. On the left sidebar, select **Search or go to** and find your group. +1. Select **Settings > Integrations**. +1. Select an integration. +1. Select **Reset** and confirm. + +Resetting a group-level default setting removes integrations that use default settings and belong to a project or subgroup of the group. + +## Use instance-level or group-level default settings for a project integration + +Prerequisite: - You must have at least the Maintainer role for the project. -To view the available integrations for your project: +To use instance-level or group-level default settings for a project integration: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > Integrations**. +1. Select an integration. +1. On the right, from the dropdown list, select **Use default settings**. +1. Under **Enable integration**, ensure the **Active** checkbox is selected. +1. Complete the fields. +1. Select **Save changes**. -You can also view and manage integration settings across [all projects in an instance or group](../../admin_area/settings/project_integration_management.md). -For a single project, you can choose to inherit the instance or group configuration, -or provide custom settings. +## Use custom settings for a project or group integration -NOTE: -Instance and group-based integration management replaces service templates, which -were [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/268032) in GitLab 14.0. +Prerequisite: -## Manage SSL verification +- You must have at least the Maintainer role for the project or group. -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. +To use custom settings for a project or group integration: -You can turn off SSL verification in the configuration settings for [webhooks](webhooks.md#configure-a-webhook-in-gitlab) -and some integrations. +1. On the left sidebar, select **Search or go to** and find your project or group. +1. Select **Settings > Integrations**. +1. Select an integration. +1. On the right, from the dropdown list, select **Use custom settings**. +1. Under **Enable integration**, ensure the **Active** checkbox is selected. +1. Complete the fields. +1. Select **Save changes**. ## Available integrations -You can configure the following integrations. - | Integration | Description | Integration 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 | +| Assembla | Manage projects with Assembla. | **{dotted-circle}** No | +| [Atlassian Bamboo](bamboo.md) | Run CI/CD pipelines with Atlassian Bamboo. | **{check-circle}** Yes | +| [Bugzilla](bugzilla.md) | Use Bugzilla as an issue tracker. | **{dotted-circle}** No | | Buildkite | Run CI/CD pipelines with Buildkite. | **{check-circle}** Yes | -| Campfire | Connect to chat. | **{dotted-circle}** No | -| [ClickUp](clickup.md) | Use ClickUp as the issue tracker. | **{dotted-circle}** No | -| [Confluence Workspace](../../../api/integrations.md#confluence-integration) | Use Confluence Cloud Workspace as an internal wiki. | **{dotted-circle}** No | +| Campfire | Connect Campfire to chat. | **{dotted-circle}** No | +| [ClickUp](clickup.md) | Use ClickUp as an issue tracker. | **{dotted-circle}** No | +| [Confluence Workspace](../../../api/integrations.md#confluence-workspace) | Use Confluence Workspace as an internal wiki. | **{dotted-circle}** No | | [Custom issue tracker](custom_issue_tracker.md) | Use a custom issue tracker. | **{dotted-circle}** No | | [Datadog](../../../integration/datadog.md) | Trace your GitLab pipelines with Datadog. | **{check-circle}** Yes | | [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 | +| Drone | Run CI/CD pipelines with Drone. | **{check-circle}** Yes | +| [Emails on push](emails_on_push.md) | Send commits and diffs on push by email. | **{dotted-circle}** No | +| [Engineering Workflow Management (EWM)](ewm.md) | Use EWM as an issue tracker. | **{dotted-circle}** No | | [External wiki](../wiki/index.md#link-an-external-wiki) | Link an external wiki. | **{dotted-circle}** No | -| [GitHub](github.md) | Obtain statuses for commits and pull requests. | **{dotted-circle}** No | +| [GitHub](github.md) | Receive statuses for commits and pull requests. | **{dotted-circle}** No | +| [GitLab for Slack app](gitlab_slack_application.md) | Use the native Slack app to receive notifications and run commands. | **{dotted-circle}** No | | [Google Chat](hangouts_chat.md) | Send notifications from your GitLab project to a room in Google Chat. | **{dotted-circle}** No | -| [Harbor](harbor.md) | Use Harbor as the container registry. | **{dotted-circle}** No | +| [Harbor](harbor.md) | Use Harbor as the Container Registry for GitLab. | **{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](../../../integration/jira/index.md) | Use Jira as the issue tracker. | **{dotted-circle}** No | +| JetBrains TeamCity | Run CI/CD pipelines with TeamCity. | **{check-circle}** Yes | +| [Jira](../../../integration/jira/index.md) | Use Jira as an 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 | 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 | +| [Mattermost slash commands](mattermost_slash_commands.md) | Run slash commands from a Mattermost chat environment. | **{dotted-circle}** No | +| [Microsoft Teams notifications](microsoft_teams.md) | Receive event notifications in Microsoft Teams. | **{dotted-circle}** No | +| Packagist | Update your PHP dependencies in Packagist. | **{check-circle}** Yes | +| [Pipeline status 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 | | [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 | -| [Shimo](shimo.md) (deprecated) | Use Shimo instead of the GitLab Wiki. | **{dotted-circle}** No | -| [GitLab for Slack app](gitlab_slack_application.md) | Use Slack's official GitLab application. | **{dotted-circle}** No | -| [Slack notifications](slack.md) (deprecated) | Send notifications about project events to Slack. | **{dotted-circle}** No | -| [Slack slash commands](slack_slash_commands.md) | Enable slash commands in a workspace. | **{dotted-circle}** No | +| [Redmine](redmine.md) | Use Redmine as an issue tracker. | **{dotted-circle}** No | +| [Slack slash commands](slack_slash_commands.md) | Run slash commands from a Slack chat environment. | **{dotted-circle}** No | | [Squash TM](squash_tm.md) | Update Squash TM requirements when GitLab issues are modified. | **{check-circle}** Yes | | [Telegram](telegram.md) | Send notifications about project events to Telegram. | **{dotted-circle}** No | | [Unify Circuit](unify_circuit.md) | Send notifications about project events to Unify Circuit. | **{dotted-circle}** No | -| [Webex Teams](webex_teams.md) | Receive events notifications. | **{dotted-circle}** No | -| [YouTrack](youtrack.md) | Use YouTrack as the issue tracker. | **{dotted-circle}** No | -| [ZenTao](zentao.md) (deprecated) | Use ZenTao as the issue tracker. | **{dotted-circle}** No | +| [Webex Teams](webex_teams.md) | Receive event notifications in Webex Teams. | **{dotted-circle}** No | +| [YouTrack](youtrack.md) | Use YouTrack as an issue tracker. | **{dotted-circle}** No | -### Project webhooks +## Project webhooks -You can configure a project webhook to listen for specific events -like pushes, issues, or merge requests. When the webhook is triggered, GitLab -sends a POST request with data to a specified webhook URL. +Some integrations use [webhooks](webhooks.md) for external applications. -For more information, see [Webhooks](webhooks.md). +You can configure a project webhook to listen for specific events +like pushes, issues, or merge requests. When the webhook is triggered, +GitLab sends a POST request with data to a specified webhook URL. -## Push hooks limit +For a list of integrations that use webhooks, see [Available integrations](#available-integrations). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17874) in GitLab 12.4. +## Push hook limit 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. - -You can change the number of supported branches or tags by changing the -[`push_event_hooks_limit` application setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). - -## Contribute to integrations +supported by `push_hooks` and `tag_push_hooks` events are not executed. -If you're interested in developing a new native integration for GitLab, see: +To change the number of supported branches or tags, configure the +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls). -- [Integrations development guidelines](../../../development/integrations/index.md) -- [GitLab Developer Portal](https://developer.gitlab.com) - -## Troubleshooting +## SSL verification -Some integrations use hooks to integrate with external applications. To confirm which ones use integration hooks, see the [available integrations](#available-integrations). For more information, see [webhook troubleshooting](webhooks.md#troubleshooting). +By default, the SSL certificate for outgoing HTTP requests is verified based on +an internal list of certificate authorities. The SSL certificate cannot +be self-signed. -### `Test Failed. Save Anyway` error +You can disable SSL verification when you configure +[webhooks](webhooks.md#configure-a-webhook-in-gitlab) and some integrations. -Some integrations fail with an error `Test Failed. Save Anyway` when you set them -up on uninitialized repositories. This error occurs because the integration uses -push data to build the test payload, and there are no push events in the project. +## Related topics -To resolve this error, initialize the repository by pushing a test file to the project -and set up the integration again. +- [Integrations API](../../../api/integrations.md) +- [Integration development guidelines](../../../development/integrations/index.md) +- [GitLab Developer Portal](https://developer.gitlab.com) diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index fe702766a1d..ddd000f4c0e 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Mock CI **(FREE ALL)** NOTE: -This integration only appears if you're in a [development environment](https://gitlab.com/gitlab-org/gitlab-mock-ci-service#setup-mockci-integration). +This integration is only available in a development environment. To set up the mock CI service server, respond to the following endpoints: @@ -17,4 +17,4 @@ To set up the mock CI service server, respond to the following endpoints: - `build_page`: `#{project.namespace.path}/#{project.path}/status/#{sha}` - Where the build is linked to (whether or not it's implemented). -For an example of a mock CI server, see [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service). +For an example Mock CI server, see [`gitlab-org/gitlab-mock-ci-service`](https://gitlab.com/gitlab-org/gitlab-mock-ci-service). diff --git a/doc/user/project/integrations/servicenow.md b/doc/user/project/integrations/servicenow.md index 2d02a4f631c..156ff4a54aa 100644 --- a/doc/user/project/integrations/servicenow.md +++ b/doc/user/project/integrations/servicenow.md @@ -17,7 +17,7 @@ With the GitLab spoke in ServiceNow, you can automate actions for GitLab projects, groups, users, issues, merge requests, branches, and repositories. For a full list of features, see the -[GitLab spoke documentation](https://docs.servicenow.com/bundle/sandiego-application-development/page/administer/integrationhub-store-spokes/concept/gitlab-spoke.html). +[GitLab spoke documentation](https://docs.servicenow.com/bundle/tokyo-application-development/page/administer/integrationhub-store-spokes/concept/gitlab-spoke.html). You must [configure GitLab as an OAuth2 authentication service provider](../../../integration/oauth_provider.md), which involves creating an application and then providing the Application ID diff --git a/doc/user/project/integrations/shimo.md b/doc/user/project/integrations/shimo.md index aeddee29109..6ea0cfa6fff 100644 --- a/doc/user/project/integrations/shimo.md +++ b/doc/user/project/integrations/shimo.md @@ -4,20 +4,17 @@ 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 --- -<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> - # Shimo (deprecated) **(FREE ALL)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) in GitLab 14.5 [with a flag](../../../administration/feature_flags.md) named `shimo_integration`. Disabled by default. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. Feature flag `shimo_integration` removed. + WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7 -and is planned for removal in 16.0. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377824) in GitLab 15.7. This change is a breaking change. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343386) in GitLab 14.5 with a feature flag named `shimo_integration`. Disabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) in GitLab 15.4. [Feature flag `shimo_integration`](https://gitlab.com/gitlab-org/gitlab/-/issues/345356) removed. - -[Shimo](https://shimo.im/) is a productivity suite that includes documents, spreadsheets, and slideshows in one interface. With this integration, you can use the Shimo Wiki directly within GitLab instead of the [GitLab group/project wiki](../wiki/index.md). +[Shimo](https://shimo.im/) is a productivity suite that includes documents, spreadsheets, and slideshows in one interface. +With this integration, you can use the Shimo wiki directly in GitLab instead of the [GitLab group or project wiki](../wiki/index.md). ## Configure settings in GitLab @@ -39,5 +36,3 @@ To view the Shimo Workspace from your group or project: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Shimo**. 1. On the **Shimo Workspace** page, select **Go to Shimo Workspace**. - -<!--- end_remove --> diff --git a/doc/user/project/integrations/telegram.md b/doc/user/project/integrations/telegram.md index 4e94ef76f58..94d0f887730 100644 --- a/doc/user/project/integrations/telegram.md +++ b/doc/user/project/integrations/telegram.md @@ -32,7 +32,7 @@ To configure the bot in Telegram: 1. Assign the bot `Post Messages` rights to receive events. 1. Create an identifier for the channel. - For public channels, enter a public link and copy the channel identifier (for example, `https:/t.me/MY_IDENTIFIER`). - - For private channels, use the [`getUpdates`](https://telegram-bot-sdk.readme.io/reference/getupdates) method with your API token and copy the channel identifier. + - For private channels, use the [`getUpdates`](https://telegram-bot-sdk.readme.io/reference/getupdates) method with your API token and copy the channel identifier (for example, `-2241293890657`). ## Set up the Telegram integration in GitLab diff --git a/doc/user/project/integrations/webhook_events.md b/doc/user/project/integrations/webhook_events.md index 269fdf304a8..73450971434 100644 --- a/doc/user/project/integrations/webhook_events.md +++ b/doc/user/project/integrations/webhook_events.md @@ -6,8 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Webhook events **(FREE ALL)** -You can configure a [webhook](webhooks.md) in your project that triggers when -an event occurs. The following events are supported. +This page lists the events that are triggered for [project webhooks](webhooks.md) and [group webhooks](webhooks.md#group-webhooks). + +For a list of events triggered for system webhooks, see [system webhooks](../../../administration/system_hooks.md). + +**Events triggered for both project and group webhooks:** Event type | Trigger ---------------------------------------------|----------------------------------------------------------------------------- @@ -20,11 +23,16 @@ Event type | Trigger [Pipeline event](#pipeline-events) | A pipeline status changes. [Job event](#job-events) | A job status changes. [Deployment event](#deployment-events) | A deployment starts, succeeds, fails, or is canceled. +[Feature flag event](#feature-flag-events) | A feature flag is turned on or off. +[Release event](#release-events) | A release is created, updated, or deleted. +[Emoji event](#emoji-events) | An emoji reaction is added or removed. + +**Events triggered for group webhooks only:** + +Event type | Trigger +---------------------------------------------|----------------------------------------------------------------------------- [Group member event](#group-member-events) | A user is added or removed from a group, or a user's access level or access expiration date changes. [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 @@ -1578,7 +1586,7 @@ Payload example: ## Group member events **(PREMIUM ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. +These events are triggered for [group webhooks](webhooks.md#group-webhooks) only. Member events are triggered when: @@ -1673,7 +1681,7 @@ Payload example: ## Subgroup events **(PREMIUM ALL)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260419) in GitLab 13.9. +These events are triggered for [group webhooks](webhooks.md#group-webhooks) only. Subgroup events are triggered when: @@ -1790,12 +1798,15 @@ Payload example: ## Release events -Release events are triggered when a release is created or updated. +> Delete release event [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418113) in GitLab 16.5. + +Release events are triggered when a release is created, updated, or deleted. The available values for `object_attributes.action` in the payload are: - `create` - `update` +- `delete` Request header: @@ -1891,7 +1902,7 @@ On self-managed GitLab, by default this feature is available. To hide the featur 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: +An emoji event is triggered when an [emoji reaction](../../emoji_reactions.md) is added or removed on: - Issues - Merge requests @@ -1904,8 +1915,8 @@ An emoji event is triggered when an emoji is awarded or revoked on: The available values for `object_attributes.action` in the payload are: -- `award` -- `revoke` +- `award` to add a reaction +- `revoke` to remove a reaction Request header: diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 8e7f8bcd67d..1ecc14edcd3 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -60,7 +60,7 @@ To configure a webhook for a project or group: The URL must be percent-encoded if it contains one or more special characters. 1. In **Secret token**, enter the [secret token](#validate-payloads-by-using-a-secret-token) to validate payloads. 1. In the **Trigger** section, select the [events](webhook_events.md) to trigger the webhook. -1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](index.md#manage-ssl-verification). +1. Optional. Clear the **Enable SSL verification** checkbox to disable [SSL verification](index.md#ssl-verification). 1. Select **Add webhook**. ## Mask sensitive portions of webhook URLs @@ -286,9 +286,9 @@ Webhook requests to your endpoint include the following headers: | Header | Description | Example | | ------ | ------ | ------ | -| `User-Agent` | In the format `"Gitlab/<VERSION>"`. | `"GitLab/15.5.0-pre"` | +| `User-Agent` | 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-Webhook-UUID` | Unique ID per webhook. | `"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"` | diff --git a/doc/user/project/integrations/zentao.md b/doc/user/project/integrations/zentao.md index e42b0a032fd..64967e94f68 100644 --- a/doc/user/project/integrations/zentao.md +++ b/doc/user/project/integrations/zentao.md @@ -4,17 +4,14 @@ 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 --- -<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> - # ZenTao (deprecated) **(PREMIUM ALL)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338178) in GitLab 14.5. + WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377825) in GitLab 15.7 -and is planned for removal in 16.0. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/377825) in GitLab 15.7. This change is a breaking change. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/338178) in GitLab 14.5. - [ZenTao](https://www.zentao.net/) is a web-based project management platform. The following versions of ZenTao are supported: @@ -54,5 +51,3 @@ Complete these steps in GitLab: 1. Optional. Select **Test settings**. 1. Select **Save changes**. - -<!--- end_remove --> |