GitLab for Slack app: release and manifest process

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), edited in Slack’s app dashboard. Changes are subject to Slack Marketplace review and happen out-of-band from GitLab releases.
2. 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:

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 (group::ai catalog, Agent Foundations stage). Reach the team in #f_external-agents.
2. The production app is registered to the gitlab-slack-app@gitlab.com Google group, which receives all review-status communication from Slack.
3. To publish, you must be a collaborator on the production app.
4. GitLab has a Slack Connect channel with Slack (the company): #slack-and-gitlab. Use it to coordinate reviews with Slack’s Platform Partnerships contacts.

When is what required?

Per Slack’s Marketplace review guide, once published, the live app configuration is locked: any change to configuration, features, or scopes requires re-submission for review.

Notes:

1. New scopes are not pushed to existing installs — the feature stays silently unavailable in a workspace until an admin reinstalls there.
2. New event subscriptions fire for all installed workspaces as soon as they’re saved; no customer action needed.
3. Never rename the bot user — it breaks existing installs.

Review timelines: after submitting, we ask a Platform Partnerships contact in #slack-and-gitlab 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 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.
2. Update lib/slack/manifest.rb (and its spec) in the same MR as the feature.
3. Prepare the production app: apply the configuration changes at api.slack.com. Saved changes do not apply to the published app until the review is approved and published.
4. Submit for review (see below).
5. Once approved, coordinate the publish moment: publish the app and enable the feature flag together, because published changes go live immediately.
6. For Self-Managed and Dedicated: ensure the release post and docs tell admins to update their copy of the app — this is their only update mechanism.
7. 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 and open Submit to the Slack Marketplace.
2. Fix anything the automated pre-checks flag.
3. 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).
   • Answers to the privacy and governance questionnaire.
4. Submit, then post in #slack-and-gitlab to ask Platform Partnerships to expedite.
5. Review feedback arrives in the submission flow and by email to gitlab-slack-app@gitlab.com.
6. 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.
2. 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.
3. 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).
4. 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.
5. No speculative scopes. Slack’s review guide explicitly prohibits requesting scopes for unbuilt features; only submit scopes the reviewable feature uses.
6. Never rename the bot user (GitLab). Confirmed breaking for existing installs.
7. 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.

View page source - Edit this page - please contribute.