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 |
Links to gitlab_slack_application.md
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-duoin 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 indoc/development/documentation/styleguide/_index.mdand.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.
Related issues
- https://gitlab.com/gitlab-org/gitlab/-/issues/582684 - hides this integration for projects that never used it, which is what makes a documented migration path matter
- !254341 (merged) - that implementation, which also edits this page. Its hiding paragraph is moved and corrected here
- Original deprecation: #435909
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 inscripts/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.