Document migrating from Slack notifications to the GitLab for Slack app

What does this MR do?

The Slack notifications integration has been deprecated since GitLab 15.9. The page tells readers to "Use the GitLab for Slack app instead", but there are no steps for doing that and nothing that explains how the two differ. gitlab_slack_application.md has no "migrate from" content either.

This MR changes two files.

doc/user/project/integrations/slack.md gets two new sections:

  • Comparison with the GitLab for Slack app. A short list of what both integrations share, then a five-row table (Status, Setup, Capabilities, Credentials, Availability).
  • Migrate to the GitLab for Slack app. Numbered steps that link to the existing install, notification-configuration, and private-channel sections instead of restating them.

The hiding paragraph in Configure GitLab is replaced with one sentence that points to the new subsection below.

doc/user/project/integrations/gitlab_slack_application.md gets a new subsection, Effect on the Slack notifications integration, under Install the GitLab for Slack app. It says when the deprecated integration is hidden from the list and that hiding affects only the list.

The hiding paragraph was moved and corrected. It came from !254341 (merged), which is already on master, so this edits text from the author's own earlier MR. Two of its three conditions were worded wrong and are fixed. An earlier version of this MR also claimed the settings page and API become unavailable while hidden. That was false and is gone.

The one thing a reader most needs to know is called out in the migration section. Settings do not transfer, so event selections and channel names must be re-entered.

The comparison and migration sections went on the deprecated page. This follows ## Migrate from release-cli to glab CLI in doc/user/project/releases/release_cli.md and ## Migrate from the default analyzer in the secret detection docs.

No deprecations.md entry was added. Entries there need an announced removal milestone, and Slack notifications does not have one.

The Private Slack channels row was present in earlier rounds and is now removed. The webhook half had no repository evidence. The app half is still covered by migration step 4.

Evidence for every claim in the diff

Claim Evidence
Status: deprecated in 15.9 This page's deprecation warning, issue 435909
Status: "Current and recommended" The same warning says "Use the GitLab for Slack app instead"
Setup: paste a webhook URL Integrations::Slack.webhook_help (app/models/integrations/slack.rb) and this page's Configure Slack steps
Setup: install a native app gitlab_slack_application.md intro and its install procedure
Capabilities: notifications only Integrations::Slack includes only Base::SlackNotification
Capabilities: notifications, slash commands, GitLab Duo Integrations::GitlabSlackApplication.description and the app page intro
Credentials: anyone with the URL can post SlackMattermostNotifier#notify posts to the webhook URL with no other credential (app/models/concerns/integrations/slack_mattermost_notifier.rb)
Credentials: OAuth bot token stored in GitLab oauth.v2.access exchange in app/services/integrations/slack_installation/base_service.rb, attr_encrypted :bot_access_token in app/models/slack_integration.rb, sent as a Bearer token in lib/slack/api.rb. The old "you can revoke from Slack at any time" clause was removed because no code handles token revocation or app uninstall
Availability: Slack notifications need no administrator setup slack is not gated in integration_names or disabled_integration_names (app/models/concerns/integrations/base/integration.rb). The old wording "Always available" was false now that the integration can be hidden
Availability: the app needs an administrator on Self-Managed and Dedicated integration_names drops gitlab_slack_application unless slack_app_enabled. administration/settings/slack_app.md lists the offering as GitLab Self-Managed, GitLab Dedicated
Up to 10 channels per event Base::ChatNotification#channel_limit_per_event returns 10, enforced by validate_channel_limit. Both classes inherit it and neither overrides it (Discord does)
Four notification settings in the list Fields in slack_mattermost_fields.rb, included by both classes. Names match this page's Configure GitLab steps and gitlab_slack_application.md#configure-notifications
Installation level: project, group, or instance slack and gitlab_slack_application are in none of the level-restriction lists in base/integration.rb
Roles: project Maintainer, group Owner, instance administrator config/authz/roles/maintainer.yml grants admin_integrations under project, and owner.yml under group. This matches the prerequisites in doc/user/project/integrations/_index.md. Instance integrations are in the Admin area
Settings do not transfer Separate STI types. Integration.build_from_integration only copies within one type
Private channels need the app added gitlab_slack_application.md#receive-notifications-to-a-private-channel
Navigation paths Copied from this page's Configure GitLab steps, _index.md, and project_integration_management.md
Active checkbox wording app/assets/javascripts/integrations/edit/components/active_checkbox.vue
Hiding conditions, and "hiding affects only the list" Project#hidden_integrations and #hide_deprecated_slack_notifications? in app/models/project.rb, plus the specs named in the D6 and F6 replies

slack.md links to gitlab_slack_application.md once without an anchor, in the deprecation warning. It also has anchored links to distinct sections:

  • #gitlab-duo in the table.
  • Three procedure anchors in the migration steps.
  • One pointer to the new subsection from Configure GitLab.

Each anchored link points at a distinct section the reader needs at that moment. Removing one would mean restating that content here.

Duo review outcomes

Round 1 had three threads, all resolved:

  • Duplicate link to gitlab_slack_application.md: accepted. The table intro no longer links. The rule is in doc/development/documentation/styleguide/_index.md and .gitlab/duo/mr-review-instructions.yaml. The anchored links in the migration steps are kept on purpose, as explained above.
  • Unverified cascading claim: accepted, and the sentence was deleted. Cascading is generic to group-level integrations. It is not specific to the app, so the sentence was misleading in an app-only column.
  • "For the project" in the final step: accepted. Widened to project, group, or instance. The table was correct, so narrowing it would have made it false.

Rounds 2 to 5:

  • D1: accepted. The claim that the page and API were unavailable was false, so it was removed.
  • D2: accepted. 19.5 is correct. The history entry is kept only on slack.md.
  • D3 and D4: accepted. Each target is linked once.
  • D5: accepted. The duplicate paragraph was removed.
  • D6: accepted. Verified against the code. Two hiding conditions were reworded.
  • D7: accepted. Split into two sentences, one per actor.

Author's checklist

  • Follow the documentation process, guidelines, and Style Guide.
  • Not adding a new page, so no product availability details are needed.
  • Technical writer review. @fneill is reviewing.

Linters run locally:

  • Vale 3.21.0: 0 errors (--minAlertLevel error, as in scripts/lint-doc.sh).
  • markdownlint-cli2 0.23.2: 0 issues.
  • lychee 0.24.2 with --offline --include-fragments doc tooling/docs/api/tags (the docs-lint links job command): 0 errors across 33,788 unique links, anchors included.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • Check content topic type principles are in use.
  • Review by assigned maintainer.

🤖 Generated with Claude Code

Edited by Buck O'Leary

Merge request reports

Loading
Loading