Document migrating from Slack notifications to the GitLab for Slack app

Buck O'Learyrequested to merge
docs-slack-notifications-migration into master

What does this MR do?

The Slack notifications integration has been deprecated since GitLab 15.9, and 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 adds two sections to the deprecated page:

  • Comparison with the GitLab for Slack app — a three-row table covering setup, features, and installation level, plus a note that both integrations share the same events and notification options.
  • Migrate to the GitLab for Slack app — numbered steps that link out to the existing install, notification-configuration, and private-channel sections rather than restating them.

The one thing a reader most needs to know is called out explicitly: settings do not transfer, so event selections and channel names have to be re-entered.

Both sections went on the deprecated page rather than the replacement's, following the pattern already used for ## 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.

Evidence for every claim in the diff

Claim Evidence
Setup: paste an incoming webhook URL Integrations::Slack.webhook_help returns https://hooks.slack.com/services/... (app/models/integrations/slack.rb), matching this page's existing Configure Slack steps
Setup: install a native Slack app gitlab_slack_application.md:19 and its #install-the-gitlab-for-slack-app procedure
Features: notifications only Integrations::Slack includes Base::SlackNotification only. Slash commands were a separate integration, Integrations::SlackSlashCommands, now an STI stub that appears in no name list
Features: notifications, slash commands, GitLab Duo Integrations::GitlabSlackApplication.description is "Enable slash commands and notifications for a Slack workspace"; gitlab_slack_application.md:19 names all three
Installation level: project, group, or instance, for both slack and gitlab_slack_application appear in none of INSTANCE_LEVEL_ONLY_INTEGRATION_NAMES, PROJECT_LEVEL_ONLY_INTEGRATION_NAMES, or PROJECT_AND_GROUP_LEVEL_ONLY_INTEGRATION_NAMES (app/models/concerns/integrations/base/integration.rb:21-33). The counts.groups_slack_active and counts.instances_slack_active Service Ping metrics confirm both non-project levels are in use
Up to 10 channel names per event, comma separated Base::ChatNotification#channel_limit_per_event returns 10 (app/models/concerns/integrations/base/chat_notification.rb:204-205), enforced by validate_channel_limit (:385-394). Both classes reach it through include ChatNotification at base/slack_notification.rb:9, and neither overrides it — Integrations::Discord does (base/discord.rb:149), so this needed checking rather than assuming
Same notification options on both The four options named are the ones in this page's existing Configure GitLab steps and in gitlab_slack_application.md#configure-notifications
Settings do not transfer automatically The two are separate STI types, and Integration.build_from_integration (base/integration.rb:307-319) only duplicates a record within its own type. No code path copies configuration between the two
Private channels need the app added gitlab_slack_application.md:274 and :295-297
Turning off applies at project, group, or instance Same level evidence as the installation-level row. The incoming webhook itself is a Slack-side artifact referenced by whichever integration record holds it, so deleting it applies at any level

All three linked anchors were re-verified against gitlab_slack_application.md after the rebase onto master.

Duo review outcomes

Three threads, all resolved. Recording the decisions so they do not get re-litigated:

  • Duplicate link to gitlab_slack_application.md — accepted. The table intro no longer links. The rule is real: doc/development/documentation/styleguide/_index.md:1119 and .gitlab/duo/mr-review-instructions.yaml:850. I also considered keeping a link but pointing it at an anchor, on the theory that an anchored link is not a duplicate; that does not survive the rule text, which is about linking to the target page more than once. The three anchored links inside the migration steps are kept deliberately — each points at a distinct procedure, and removing them would mean restating those procedures here.
  • Unverified cascading claim — accepted, and the sentence was deleted rather than confirmed. It claimed that installing for a group turns the integration on for subgroups and projects without their own configuration. Verifying it found the behaviour is generic to group-level integrations, not specific to the GitLab for Slack app: inheritable? (base/integration.rb:627-629), build_from_integration setting inherit_from_id (:314), and Integrations::PropagateService (app/services/integrations/propagate_service.rb:12-23, :79) all live on the base class and branch only on instance_specific?, and none of slack.rb, base/slack_notification.rb, or gitlab_slack_application.rb overrides them. Slack notifications cascades the same way, so the sentence was misleading in an app-only column. It was also imprecise — descendants get inherited records, which is a different reader-facing state from an independently configured integration — and I could not evidence it for both SaaS and self-managed. Removed.
  • "For the project" in the final step — accepted. Widened to project, group, or instance. I checked which side of the inconsistency was wrong first: the table is correct, so narrowing it would have made it false.

One claim Duo did not flag was also removed: a "Private Slack channels: no extra setup required" row. The app half was grounded, but nothing in the repository documents incoming-webhook behaviour for private Slack channels, so the row was an inference and is gone rather than softened.

Related issues

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 still needed. This page's metadata is stage Plan, group Work Items, but there is no CODEOWNERS entry for slack.md or for any Slack doc page, and Danger did not suggest a writer. Assignment left open rather than guessed at.

Linters run locally after the rebase: Vale 0 errors, markdownlint 0 errors, docs-link-check 0 errors across 31,227 unique links.

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