Add GitLab for Slack app release and manifest process page

TBD

## What we own

* The [GitLab for Slack app](https://docs.gitlab.com/user/project/integrations/gitlab_slack_application/)

  is owned by the External Agents feature team

  ([`#f_external-agents`](https://gitlab.enterprise.slack.com/archives/C0B4V7TJPG9))

  within this group. See the

  [release and manifest process](/handbook/engineering/ai/agent-foundations/ai-catalog/slack-app-release-process/).

## How we work

We're just getting started and will be defining how we work as we settle in to the new team.

---

title: "GitLab for Slack app: release and manifest process"

description: How the GitLab for Slack app is released across GitLab.com, Self-Managed, and Dedicated, when manifest updates and Slack Marketplace reviews are required, and the rules we follow to avoid breaking installations.

---

## Overview

The GitLab for Slack app ships to three deployment surfaces, and its configuration

lives in **two places that must be kept in sync manually**:

1. The **live app configuration** of the marketplace app

   ([`A676ADMV5`](https://api.slack.com/apps/A676ADMV5)), edited in Slack's app

   dashboard. Changes are subject to Slack Marketplace review and happen

   out-of-band from GitLab releases.

1. [`lib/slack/manifest.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/slack/manifest.rb)

   in the GitLab monolith, which generates the manifest that Self-Managed and

   Dedicated admins use to create and update their own private copy of the app.

   This ships with GitLab releases.

Nothing synchronizes these automatically. Every manifest-affecting change must be

applied to both, deliberately.

A Slack app's configuration hardcodes the URLs of exactly one backend. The

marketplace app points at `gitlab.com`, so it **only works with GitLab.com**.

Self-Managed and Dedicated instances cannot use it — their admins create a

private copy of the app from the generated manifest, pointing at their own

instance. There is no choice on any surface; each has exactly one option:

| Surface | Slack app | Who updates the app | How |

|---------|-----------|---------------------|-----|

| GitLab.com | Marketplace app [`A676ADMV5`](https://api.slack.com/apps/A676ADMV5) | Us | Edit config → submit for Slack review → publish |

| Self-Managed | Private per-instance copy | Customer admin | Creates the app via a pre-filled Slack redirect from the instance settings; to update, [downloads the generated `slack_manifest.json` and pastes it into the app's manifest editor](https://docs.gitlab.com/administration/settings/slack_app/#update-the-gitlab-for-slack-app) |

| Dedicated | Private per-instance copy | Instance admin | Same as Self-Managed, tied to the instance's GitLab version |

The practical consequence: the marketplace app is **one shared app we update

centrally** (with a review cycle, but instant rollout once published), while

Self-Managed and Dedicated are **thousands of independent app copies we can

never touch** — they only get updates when an admin manually re-applies the

manifest generated by whatever GitLab version their instance runs.

## Ownership and access

1. The GitLab for Slack app is owned by the External Agents feature team within

   the [AI Catalog group](/handbook/engineering/ai/agent-foundations/ai-catalog/)

   (`group::ai catalog`, Agent Foundations stage). Reach the team in

   [`#f_external-agents`](https://gitlab.enterprise.slack.com/archives/C0B4V7TJPG9).

1. The production app is registered to the

   [`gitlab-slack-app@gitlab.com`](https://groups.google.com/a/gitlab.com/g/gitlab-slack-app/members)

   Google group, which receives all review-status communication from Slack.

1. To publish, you must be a

   [collaborator on the production app](https://app.slack.com/app-settings/T02592416/A676ADMV5/collaborators).

1. GitLab has a **Slack Connect channel with Slack (the company)**:

   [`#slack-and-gitlab`](https://gitlab.slack.com/archives/CC3NCBU07). Use it to

   coordinate reviews with Slack's Platform Partnerships contacts.

## When is what required?

Per [Slack's Marketplace review guide](https://docs.slack.dev/slack-marketplace/slack-marketplace-review-guide#updating),

**once published, the live app configuration is locked**: any change to

configuration, features, or scopes requires re-submission for review.

| Change | Update `manifest.rb` | Marketplace re-review | Customer action |

|--------|---------------------|----------------------|-----------------|

| Backend-only behavior | No | No | None |

| New bot event subscription | Yes | Yes | None |

| New OAuth scope | Yes | Yes (demo/test app) | **Admins reinstall in each workspace** — feature is inert there until they do (see note 1) |

| New slash command, app home, or agent view | Yes | Yes | Admins reinstall in each workspace, for some features |

| Converting to a Slack agent app | Yes | Yes (new review) | Admins reinstall in each workspace |

| Request URL change | Yes | Yes, lightweight | SM/Dedicated re-apply manifest |

| Display name, description, icon | Usually | Listing-only, fast | None |

Notes:

1. New scopes are **not pushed to existing installs** — the feature stays

   silently unavailable in a workspace until an admin reinstalls there.

1. New event subscriptions fire for all installed workspaces as soon as they're

   saved; no customer action needed.

1. **Never rename the bot user** — it breaks existing installs.

Review timelines: after submitting, we ask a Platform Partnerships contact in

[`#slack-and-gitlab`](https://gitlab.slack.com/archives/CC3NCBU07) to expedite —

expedited reviews have historically turned around in about **1 day**. Still plan

buffer time, expediting is a courtesy, not an SLA. After approval, **we choose

when to publish** — publishing takes effect immediately for every workspace with

the app installed.

## Release checklist for manifest-affecting changes

1. Develop and test the feature behind a feature flag — **including any new

   scopes**. The OAuth install flow requests whatever

   [`SlackIntegration.scopes_for`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/slack_integration.rb)

   returns (both the generated manifest and the "Add to Slack" link use it), so

   requesting a scope the published marketplace app does not yet have breaks

   new installs. The flag must only expand the requested scopes after the

   updated app is published.

1. Update `lib/slack/manifest.rb` (and its spec) in the same MR as the feature.

1. Prepare the production app: apply the configuration changes at

   [api.slack.com](https://api.slack.com/apps/A676ADMV5). Saved changes do not

   apply to the published app until the review is approved and published.

1. Submit for review (see below).

1. Once approved, coordinate the publish moment: **publish the app and enable

   the feature flag together**, because published changes go live immediately.

1. For Self-Managed and Dedicated: ensure the release post and docs tell admins

   to [update their copy of the app](https://docs.gitlab.com/administration/settings/slack_app/#update-the-gitlab-for-slack-app)

   — this is their only update mechanism.

1. If new scopes were added, communicate the reinstall requirement (reinstall

   banner via `upgrade_needed?`, docs, release post). Existing installations do

   not get new scopes until each workspace re-authorizes; until then the new

   functionality is silently unavailable, while existing features keep working.

### How to submit a Slack review

1. Go to the [production app's settings](https://api.slack.com/apps/A676ADMV5)

   and open **Submit to the Slack Marketplace**.

1. Fix anything the automated pre-checks flag.

1. In **Testing Information**, provide:

   - A **video demo** showing the new functionality end to end.

   - For scope additions or privacy-relevant changes: access to a test

     environment where the Slack review team can exercise the feature

     (reviewers cannot use feature-flagged features on production — the

     staging-ref copy of the app with a provisioned reviewer account has been

     used for this; verify how to reach the review team in

     [`#slack-and-gitlab`](https://gitlab.slack.com/archives/CC3NCBU07)).

   - Answers to the privacy and governance questionnaire.

1. Submit, then post in

   [`#slack-and-gitlab`](https://gitlab.slack.com/archives/CC3NCBU07) to ask

   Platform Partnerships to expedite.

1. Review feedback arrives in the submission flow and by email to

   `gitlab-slack-app@gitlab.com`.

1. After approval, publish from the app settings page at the moment of your

   choosing.

## Rules we hold ourselves to

1. **`manifest.rb` is the single source of truth for app configuration.** Any MR

   touching it must state whether it requires (a) marketplace re-review,

   (b) workspace reinstall, (c) a release-post callout for Self-Managed and

   Dedicated admins.

1. **Code must degrade gracefully with stale manifests.** Self-Managed and

   Dedicated customers run old app copies indefinitely, and existing GitLab.com

   installs keep their old token and scopes until re-authorized. Handle

   `missing_scope` errors and absent event subscriptions without breaking

   existing functionality.

1. **Batch scope additions.** New scopes only take effect in a workspace after

   an admin manually reinstalls the app there — every scope addition is

   therefore a reinstall campaign across all customer workspaces. Don't add one

   scope per milestone (each would force another reinstall); collect scope

   needs and ship them together in a single release, paired with reinstall

   communication (in-product banner, docs, release post).

1. **One scope set per GitLab instance.** The manifest already varies per

   instance (each Self-Managed and Dedicated instance generates its own, with

   its own URLs). Within an instance, however, every workspace install must get

   the same scope set — don't persistently vary scopes by license tier or

   per-group feature flag state, because then any license or flag change would

   require a reinstall to fix the app's permissions. The one exception is

   release gating (see the checklist above): a temporary instance-wide flag

   that keeps new scopes out of the auth flow until the updated marketplace

   app is published, then is enabled for everyone at once.

1. **No speculative scopes.** Slack's review guide explicitly prohibits

   requesting scopes for unbuilt features; only submit scopes the reviewable

   feature uses.

1. **Never rename the bot user** (`GitLab`). Confirmed breaking for existing

   installs.

1. **Configuration changes to the published app go through Slack review** —

   even when the feature is behind a feature flag. Give reviewers a testable

   environment where the flag is enabled.

| Integration | DRI Group | Rationale |

|---|---|---|

| [Slack slash commands](https://docs.gitlab.com/ee/user/project/integrations/slack_slash_commands.html) | group Create:Import | Run slash commands from a Slack workspace to operate on GitLab data |

| [GitLab for Slack app](https://docs.gitlab.com/ee/user/project/integrations/slack.html) | group Plan:Work Items | Combination of Slack slash commands integration, and Slack notifications integrations, with additional incident management flows |

| [GitLab for Slack app](https://docs.gitlab.com/ee/user/project/integrations/slack.html) | group Agent Foundations:AI Catalog (External Agents feature team) | Combination of Slack slash commands integration, and Slack notifications integrations, with additional incident management flows. See the [release and manifest process](/handbook/engineering/ai/agent-foundations/ai-catalog/slack-app-release-process/) |

| [Mattermost slash commands](https://docs.gitlab.com/ee/user/project/integrations/mattermost.html) | group Plan:Work Items | Run slash commands from a Mattermost environment to operate on GitLab data |

| [Trello PowerUp](https://docs.gitlab.com/ee/integration/trello_power_up.html) | group Plan:Work Items | Board-based project management integration |

| [Pipeline status emails](https://docs.gitlab.com/ee/user/project/integrations/pipeline_status_emails.html) | group Verify:Pipeline Execution | CI/CD pipeline notification integration |