GitLab for Slack app administration

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Introduced for GitLab Self-Managed in GitLab 16.2.

{{< /history >}}

[!note] This page contains administrator documentation for the GitLab for Slack app. For user documentation, see GitLab for Slack app.

The GitLab for Slack app distributed through the Slack App Directory only works with GitLab.com. On GitLab Self-Managed, you can create your own copy of the GitLab for Slack app from a manifest file and configure your instance.

The app is a private one-time copy installed in your Slack workspace only and not distributed through the Slack App Directory. To have the GitLab for Slack app on your GitLab Self-Managed instance, you must enable the integration.

Create a GitLab for Slack app

Prerequisites:

• You must be at least a Slack workspace administrator.

To create a GitLab for Slack app:

• In GitLab:

  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select Settings > General.
  3. Expand GitLab for Slack app.
  4. Select Create Slack app.

You're then redirected to Slack for the next steps.

• In Slack:

  1. Select the Slack workspace to create the app in, then select Next.
  2. Slack displays a summary of the app for review. To view the complete manifest, select Edit Configurations. To go back to the review summary, select Next.
  3. Select Create.
  4. Select Got it to close the dialog.
  5. Select Install to Workspace.

Configure the settings

After you've created a GitLab for Slack app, you can configure the settings in GitLab:

1. In the upper-right corner, select Admin.
2. Select Settings > General.
3. Expand GitLab for Slack app.
4. Select the Enable GitLab for Slack app checkbox.
5. Enter the details of your GitLab for Slack app:
   1. Go to Slack API.
   2. Search for and select GitLab (<your host name>).
   3. Scroll to App Credentials.
6. Select Save changes.

Install the GitLab for Slack app

{{< history >}}

• Installation for a specific instance introduced in GitLab 16.10 with a flag named gitlab_for_slack_app_instance_and_group_level. Disabled by default.
• Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 16.11.
• Generally available in GitLab 17.8. Feature flag gitlab_for_slack_app_instance_and_group_level removed.

{{< /history >}}

Prerequisites:

• You must have the appropriate permissions to add apps to your Slack workspace.
• You must create a GitLab for Slack app and configure the app settings.

To install the GitLab for Slack app from the instance settings:

1. In the upper-right corner, select Admin.
2. Select Settings > Integrations.
3. Select GitLab for Slack app.
4. Select Install GitLab for Slack app.
5. On the Slack confirmation page, select Allow.

Test your configuration

To test your GitLab for Slack app configuration:

1. Enter the /gitlab help slash command into a channel in your Slack workspace.
2. Press <kbd>Enter</kbd>.

You should see a list of available Slash commands.

To use Slash commands for a project, configure the GitLab for Slack app for the project.

Update the GitLab for Slack app

Prerequisites:

• You must be at least a Slack workspace administrator.

When GitLab releases new features for the GitLab for Slack app, you might have to manually update your copy to use the new features.

To update your copy of the GitLab for Slack app:

• In GitLab:
  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select Settings > General.
  3. Expand GitLab for Slack app.
  4. Select Download latest manifest file to download slack_manifest.json.
• In Slack:
  1. Go to Slack API.
  2. Search for and select GitLab (<your host name>).
  3. In the left sidebar, select App Manifest.
  4. Select the JSON tab to switch to a JSON view of the manifest.
  5. Copy the contents of the slack_manifest.json file you've downloaded from GitLab.
  6. Paste the contents into the JSON viewer to replace any existing contents.
  7. Select Save Changes.

Connectivity requirements

To enable the GitLab for Slack app functionality, your network must allow inbound and outbound connections between GitLab and Slack.

• For Slack notifications, the GitLab instance must be able to send requests to https://slack.com.
• For Slash commands and other features, the GitLab instance must be able to receive requests from https://slack.com.

Enable support for multiple workspaces

By default, you can install the GitLab for Slack app in only one Slack workspace. An administrator selects this workspace when they create a GitLab for Slack app.

To enable support for multiple Slack workspaces, you must configure the GitLab for Slack app as an unlisted distributed app. An unlisted distributed app:

• Is not published in the Slack App Directory.
• Can only be used with your GitLab instance and not by other sites.

To configure the GitLab for Slack app as an unlisted distributed app:

1. Go to the Your Apps page on Slack and select your GitLab for Slack app.
2. Select Manage Distribution.
3. In the Share Your App with Other Workspaces section, expand Remove Hard Coded Information.
4. Select the I've reviewed and removed any hard-coded information checkbox.
5. Select Activate Public Distribution.

Troubleshooting

When administering the GitLab for Slack app, you might encounter the following issues.

For user documentation, see GitLab for Slack app.

Slash commands return dispatch_failed in Slack

Slash commands might return /gitlab failed with the error "dispatch_failed" in Slack.

To resolve this issue, ensure:

• The GitLab for Slack app is properly configured and the Enable GitLab for Slack app checkbox is selected.
• Your GitLab instance allows requests to and from Slack.