GitLab for Slack app administration

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed

• Introduced for self-managed in GitLab 16.2.

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 self-managed GitLab, 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 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. On the left sidebar, at the bottom, select Admin.
  2. On 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. On the left sidebar, at the bottom, 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.

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 Enter.

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.

Install the GitLab for Slack app

• 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, self-managed, and GitLab Dedicated in GitLab 16.11.

FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can disable the feature flag named gitlab_for_slack_app_instance_and_group_level. On GitLab.com and GitLab Dedicated, this feature is available.

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. On the left sidebar, at the bottom, 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.

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. On the left sidebar, at the bottom, select Admin.
  2. On 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. On 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.

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.